Cómo comprender la arquitectura completa de la API de Nichi-Rece a partir del código fuente — Leyendo el código fuente público de ORCA (con tabla de correspondencias de los 137 endpoints)

En el artículo anterior repasamos que ORCA (Nichi-i Hyōjun Recept Software, el software estándar de facturación médica de la Asociación Médica Japonesa) es un sistema de facturación médica, y que su código fuente lleva más de veinte años publicándose de forma continua.

En esta entrega vamos a leer de verdad ese código fuente. El tema es comprender la arquitectura completa de la API de Nichi-Rece a partir de información de primera mano. En lugar de leer de arriba abajo las especificaciones oficiales de la API, vamos a probar el siguiente orden:

1. contar desde el código fuente todos los endpoints que existen realmente en el servidor,
2. seguir una sola API desde la implementación hasta la forma del XML de respuesta,
3. cotejarla con la documentación oficial para verificar las diferencias, y
4. medir el cambio de la API mediante un diff entre versiones

Al final del artículo se incluye, como resultado de esta investigación, la tabla de correspondencias de los 137 endpoints (URL, programa COBOL y función).

El objeto de estudio de este artículo es el código fuente público de la serie 5.2 del núcleo de Nichi-Rece (instantánea publicada el 1 de julio de 2026), y como referencia de comparación se usa también la serie 5.1 (publicada el mismo día). Toda la descripción se basa en estas dos versiones, y en el texto se muestran los comandos necesarios para reproducirla.

El público al que se dirige este artículo son los desarrolladores que van a diseñar e implementar, de aquí en adelante, una integración con la API de Nichi-Rece. No hace falta saber leer COBOL. Para captar la arquitectura completa basta con grep e iconv sobre texto plano, y aun en la fase de profundizar en una API concreta, lo que se lee es sobre todo los comentarios de la cabecera y el historial de modificaciones. Tampoco se da por sentado ningún conocimiento práctico de administración médica.

Índice

1. La conclusión primero
2. Requisitos previos — cómo obtener el código fuente y fijar la versión
3. El mecanismo de despacho de la API — la URL la determina lddef
4. Descubrimiento: la API es «la versión API de las pantallas de trabajo» — bind y bindapi
5. Siguiendo una API de principio a fin — disección de patientgetv2
6. Contar todos los endpoints — el procedimiento de investigación con un solo grep
7. Comparación con el listado oficial — ejemplos de API que no aparecen en el listado
8. Derivar la especificación de una API no documentada a partir del código fuente — el caso real de findv3
9. Medir el cambio de la API mediante diff entre versiones — serie 5.1 frente a serie 5.2
10. Cómo relacionarse con las API no documentadas — «documentada» no es garantía
11. Notas prácticas para cuando se profundiza
12. Resumen
13. Apéndice: tabla de correspondencias de los 137 endpoints (serie 5.2, versión de julio de 2026)
14. Referencias

1. La conclusión primero

• La correspondencia entre la URL de la API de Nichi-Rece y el programa del lado del servidor está escrita de forma declarativa en el código fuente, en lddef/*.ld (los archivos de definición LD). Sin necesidad de leer COBOL, basta con un grep sobre texto plano para enumerar toda la arquitectura de la API.
• En la instantánea de la serie 5.2, un total de 137 endpoints están agrupados mediante bindapi en 27 definiciones LD. La página oficial con el listado de especificaciones de la API muestra unos 50, así que en el código fuente existen realmente más del doble de endpoints.
• La estructura de las solicitudes y respuestas XML está declarada en record/*.db, y los nombres de las etiquetas XML son exactamente los nombres de los campos de esa definición. Es decir, incluso en una API no documentada, siguiendo el camino lddef → cobol → record se puede derivar su especificación.
• Al calcular el diff entre versiones con la serie 5.1, se observan 9 endpoints añadidos y 0 eliminados. Las incorporaciones se concentran en la confirmación de elegibilidad en línea (relacionada con la tarjeta MyNumber de seguro médico), lo que permite comprobar de forma empírica que «la API crece con las adaptaciones normativas, y las existentes —al menos entre estas dos series— no desaparecen».
• Una API no documentada no es una «API que no se debe usar». ORCA es de código abierto, y el propio código fuente puede tratarse como especificación de primera mano. El problema no es si existe o no una promesa formal, sino si se cuenta con una operación capaz de detectar por cuenta propia los cambios; ese marco de decisión se organiza en el capítulo 10.

2. Requisitos previos — cómo obtener el código fuente y fijar la versión

El código fuente puede descargarse como un tarball (zip) desde la página oficial de información técnica. Como se actualiza el día 1 de cada mes con la instantánea del día 1 del mes anterior, la regla de oro es registrar siempre el resultado de la investigación junto con la versión utilizada. En este artículo se usan las siguientes versiones.

• Origen: https://ftp.orca.med.or.jp/pub/src/jma-receipt.r_5_2_branch.zip (también r_5_1_branch.zip para la comparación)
• Fecha de obtención: 17-07-2026 (ambas son instantáneas al 1 de julio de 2026)
• Archivo VERSION de la serie 5.2: 5.2.0

Si se quiere probar en la práctica, el procedimiento mínimo es el siguiente. Todos los comandos de los capítulos posteriores se ejecutan tomando como punto de partida el directorio donde se descomprime el archivo.

# Decidir el directorio de trabajo y obtener/descomprimir la instantánea de la serie 5.2
mkdir -p ~/orca-src && cd ~/orca-src
curl -O https://ftp.orca.med.or.jp/pub/src/jma-receipt.r_5_2_branch.zip
unzip -q jma-receipt.r_5_2_branch.zip

# Registro de la versión. Estos dos datos deben quedar siempre en las notas de la investigación
sha256sum jma-receipt.r_5_2_branch.zip
cat jma-receipt.r_5_2_branch/VERSION      # → 5.2.0

# A partir de aquí, los comandos siguientes se ejecutan dentro de este directorio
cd jma-receipt.r_5_2_branch
ls lddef/ | head

Si además se descomprime la serie 5.1 de comparación con el mismo procedimiento, sustituyendo en la URL r_5_2_branch por r_5_1_branch, el diff del capítulo 9 puede ejecutarse tal cual.

Al descomprimir se obtienen unos 8.200 archivos y 237 MB, de los cuales este artículo usa principalmente los tres directorios siguientes.

3. El mecanismo de despacho de la API — la URL la determina lddef

Antes de entrar en el tema, conviene reunir aquí los términos que se usarán a partir de este capítulo. Son expresiones propias de ORCA, pero basta con memorizar cinco.

La URL de la API de Nichi-Rece tiene una estructura de dos niveles, «nombre de módulo/nombre de endpoint», como en /api01rv2/patientgetv2. Esta correspondencia aparece tal cual en los archivos de definición LD de lddef/.

Veamos el principio de lddef/api01rv2.ld.

name	api01rv2;

bindapi	"patientgetv2"	"OpenCOBOL"	"ORAPI012R1V2";
bindapi	"acceptlstv2"	"OpenCOBOL"	"ORAPI011R1V2";
bindapi	"appointlstv2"	"OpenCOBOL"	"ORAPI014R1V2";
...

La lectura es directa: el nombre de la LD es el primer segmento de la URL, el primer argumento de bindapi es el segundo segmento, y el tercer argumento es el nombre del programa COBOL responsable de procesarla. Es decir, una petición a /api01rv2/patientgetv2 se pasa al programa COBOL ORAPI012R1V2.

flowchart LR
    C["Sistema de integración<br/>historia clínica electrónica, etc."] -->|"GET /api01rv2/patientgetv2?id=número de paciente"| M["Servidor de Nichi-Rece<br/>MONTSUQI"]
    M -->|"lddef/api01rv2.ld<br/>consulta la definición bindapi"| P["ORAPI012R1V2.CBL<br/>Obtención de información básica del paciente"]
    P --> D[("PostgreSQL")]
    P -->|"Respuesta XML"| C

Además de esto, en la definición LD también se declaran el conjunto de registros XML usados para construir la respuesta (db "xml2" { ... }) y otros ajustes útiles de conocer (como el tamaño de los arreglos). El archivo LD puede leerse como «el índice de las pantallas, las API y las estructuras de datos que maneja ese módulo».

4. Descubrimiento: la API es «la versión API de las pantallas de trabajo» — bind y bindapi

Si se observan las definiciones LD, hay algo que salta a la vista enseguida: en un mismo archivo conviven bind (pantalla) y bindapi (API). Veamos el módulo de consulta de pacientes, lddef/orca13.ld.

name	orca13;

bind	"Q01"		"OpenCOBOL"	"ORCGQ01";     ← pantalla interactiva de consulta de pacientes
bind	"Q02"		"OpenCOBOL"	"ORCGQ02";
...
bindapi "findv3"    "OpenCOBOL"	"ORCGQAPI01";  ← su versión API
bindapi "findinfv3" "OpenCOBOL"	"ORCGQAPI02";
bindapi "foundv3"   "OpenCOBOL"	"ORCGQAPI03";

Q01 y los que le siguen son los programas de la pantalla de consulta de pacientes que opera el personal administrativo médico, mientras que findv3 y los que le siguen son las API que pertenecen a ese mismo módulo. Incluso el nombre del programa refleja esto: frente a ORCGQ01 (pantalla) está ORCGQAPI01 (API), como si se hubiera insertado «API» en medio del nombre de la serie de pantallas.

Es decir, la API de Nichi-Rece no se diseñó como un servidor de API independiente, sino que se fue añadiendo, módulo de negocio por módulo de negocio, «un punto de entrada que conversa en XML en lugar de la pantalla», sobre la misma base de programas de negocio que las pantallas interactivas. Entender esta estructura permite comprender de forma natural dos cosas.

• Por qué el primer segmento de la URL (orca13, orca42…) proviene del número de negocio de la pantalla, y por eso, visto solo como API, parece un número sin sentido.
• Por qué funciona la estrategia de búsqueda «puede que exista una versión API de cualquier tarea que se pueda hacer en pantalla»: buscar API no documentadas es, en realidad, una tarea muy parecida a enumerar estas «versiones API de las tareas de pantalla».

5. Siguiendo una API de principio a fin — disección de patientgetv2

Antes de contar la arquitectura completa, vamos a seguir una sola API desde la implementación hasta la forma de la respuesta. El caso elegido es el más básico: la obtención de información básica del paciente, /api01rv2/patientgetv2.

(1) Despacho: en lddef/api01rv2.ld, bindapi "patientgetv2" → ORAPI012R1V2. El archivo real es cobol/api01rv2/ORAPI012R1V2.CBL (2.163 líneas). El código fuente COBOL se coloca, en principio, en el mismo directorio que el nombre de la LD, así que con solo leer lddef se puede identificar el archivo de implementación de forma casi mecánica (hay excepciones: por ejemplo, el conjunto de API de orca51 tiene su archivo real en cobol/orca52/. Lo seguro es hacer un find por el nombre del programa).

(2) Cabecera del programa: al principio aparece «Nombre del componente: obtención de información básica del paciente (compatible con la versión 2)», y en el historial de modificaciones que sigue, desde la compatibilidad con el ID de colaboración regional de 2013 hasta la compatibilidad con la receta electrónica de 2022 y la «compatibilidad con la devolución de la validez de la elegibilidad mediante la tarjeta de seguro» de 2024, aparecen alineadas, como una cronología, todas las adaptaciones normativas que ha recibido esta única API. Es más detallado que el «historial de actualizaciones» de las especificaciones oficiales de la API.

(3) Qué datos toca: si se observan las cláusulas COPY (las definiciones comunes que se incorporan) de la WORKING-STORAGE SECTION, se puede saber qué datos maneja esta API. Un extracto:

COPY "CPPTINF.INC".          *> Información básica del paciente (tbl_ptinf)
COPY "CPPTNUM.INC".          *> Número de paciente
COPY "CPJYURRK.INC".         *> Historial de atención
COPY "CPPTCARE-HKNINF.INC".  *> Información del seguro de cuidados de larga duración
COPY "CPPTMYNUMBER.INC".     *> Número personal MyNumber del paciente
COPY "CPONSHI-KAKU.INC".     *> Resultado de la confirmación de elegibilidad en línea
COPY "CPPATIENTXMLV2RES.INC" *> Para la edición de la respuesta

Una API que solo devuelve los datos de un paciente incorpora casi treinta definiciones, que llegan hasta el seguro de cuidados de larga duración, el MyNumber y la confirmación de elegibilidad en línea. Es la prueba material de que el significado de «información básica del paciente» no ha dejado de expandirse junto con el marco normativo.

(4) La forma de la respuesta: la estructura del XML de respuesta está declarada en record/xml_patientinfov2res.db.

xml_patientinfov2res {
    patientinfores {
        Api_Result          varchar(2);
        Patient_Information {
            Patient_ID          varchar(20);
            WholeName           varchar(100);
            WholeName_inKana    varchar(100);
            BirthDate           varchar(10);
            Sex                 varchar(1);
            Home_Address_Information {
                Address_ZipCode varchar(07);
                ...

Quien haya usado la API de Nichi-Rece reconocerá esto de inmediato. Los nombres de las etiquetas XML de la respuesta de la API (Patient_ID, WholeName…) son exactamente los nombres de los campos de esta definición record. Es decir, aquí está el «original» de la tabla de campos que aparece en las especificaciones XML oficiales. Como incluso el tamaño (número de dígitos) de cada campo está escrito, también puede usarse como información de primera mano para diseñar la validación del lado de la integración.

Este recorrido de (1) a (4) es la plantilla del procedimiento de disección de una sola API de Nichi-Rece: identificar el programa con lddef, captar la función y la historia con la cabecera, entender los datos que toca con las cláusulas COPY, y fijar la estructura del mensaje con record. Sin necesidad de leer a fondo la lógica del propio COBOL, con esto ya se reúne la mayor parte de la información necesaria para el trabajo práctico.

6. Contar todos los endpoints — el procedimiento de investigación con un solo grep

Una vez entendido el mecanismo, enumerar el conjunto completo es un trabajo mecánico.

# Enumerar todas las correspondencias endpoint → programa COBOL
grep -H '^[[:space:]]*bindapi' lddef/*.ld

# Número de endpoints por módulo
for f in lddef/*.ld; do
  n=$(grep -c '^[[:space:]]*bindapi' "$f"); [ "$n" -gt 0 ] && echo "$f: $n"
done

# Extraer mecánicamente el nombre de función de cada endpoint desde la cabecera COBOL
# (el código fuente está en EUC-JP, así que se usa iconv. La ubicación del
#  programa tiene excepciones que no coinciden con el nombre de la LD, así
#  que se identifica con find)
for ld in lddef/*.ld; do
  mod=$(basename "$ld" .ld)
  grep '^[[:space:]]*bindapi' "$ld" | sed 's/"//g; s/;//' \
  | while read -r _ ep _ prog; do
      cbl=$(find cobol -name "$prog.CBL" | head -1)
      comp=$(iconv -f EUC-JP -t UTF-8 "$cbl" 2>/dev/null \
             | grep -m1 'コンポーネント名' \
             | sed 's/.*コンポーネント名[[:space:]]*[:：][[:space:]]*//')
      printf '%s\t%s\t%s\t%s\n' "$mod" "$ep" "$prog" "$comp"
    done
done

El tercer script es largo, así que conviene desglosar qué hace cada etapa de la tubería.

1. grep '^[[:space:]]*bindapi' "$ld" — extrae de la definición LD solo las líneas de declaración de API
2. sed 's/"//g; s/;//' — elimina las comillas dobles y el punto y coma final, dejando cuatro palabras separadas por espacios (bindapi / nombre del endpoint / OpenCOBOL / nombre del programa)
3. while read -r _ ep _ prog — descarta la primera y la tercera palabra, y se queda solo con el nombre del endpoint y el del programa
4. find cobol -name "$prog.CBL" — busca el archivo real del programa. Como hay excepciones en las que el nombre de la LD no coincide con el del directorio, no conviene fijar la ruta de antemano
5. iconv -f EUC-JP -t UTF-8 — como el código fuente COBOL está en EUC-JP, se convierte para poder leer los comentarios de la cabecera en japonés
6. grep -m1 'コンポーネント名' | sed … — recoge una sola vez la línea de la cabecera que contiene el nombre del componente y extrae lo que sigue a los dos puntos (el nombre de la función)

Al ejecutarlo, aparecen cuatro columnas separadas por tabulaciones: «módulo / endpoint / programa / nombre de función». Las primeras seis líneas son las siguientes.

api01rv2	patientgetv2	ORAPI012R1V2	患者基本情報取得
api01rv2	acceptlstv2	ORAPI011R1V2	受付一覧
api01rv2	appointlstv2	ORAPI014R1V2	予約一覧  (xml2）
api01rv2	patientlst1v2	ORAPI012R2V2	患者番号一覧取得処理
api01rv2	patientlst2v2	ORAPI012R3V2	患者情報一覧取得
api01rv2	patientlst3v2	ORAPI012R4V2	患者情報一覧取得（氏名指定）

En total resultan 137 líneas. Que en la tercera línea, «予約一覧　(xml2）» (listado de citas), aparezcan espacios duplicados o que los paréntesis mezclen el ancho completo y el ancho medio se debe a que el texto se extrae tal cual de la cabecera. La tabla del apéndice es este mismo resultado ordenado (capítulo 13); en la tabla en español se ha traducido el significado de cada nombre de función, pero conviene saber que, en el código fuente japonés original, esas mismas cabeceras conservan variaciones de notación —espacios, anchura de los paréntesis e incluso algún posible error tipográfico— que no se han corregido en el original.

El resultado del recuento en esta versión es el siguiente (el detalle completo de las 137 entradas está en el apéndice).

Mientras que en la lectura (api01rv2) se concentra cerca de un 40 %, las operaciones de actualización están repartidas por módulo de negocio (paciente = orca12, recepción = orca11, actos médicos = api21…). La estructura de «versión API de las tareas de pantalla» del capítulo 4 se refleja tal cual en esta distribución.

Otro punto a destacar es que, más que API de negocio, se mezclan API de funciones de infraestructura, como session_start (autenticación de inicio de sesión) del módulo session o print (impresión) de orca00. Por más que se repase el listado de las especificaciones oficiales, no se puede notar la existencia de esta capa.

Los endpoints individuales están en la tabla de correspondencias de las 137 entradas del apéndice. La forma básica de buscar es estimar el módulo objetivo a partir de la cantidad de la tabla anterior y luego recorrer el apéndice por nombre de módulo.

7. Comparación con el listado oficial — ejemplos de API que no aparecen en el listado

A continuación, cotejamos las API que aparecen en la página del listado oficial «Especificación de la API de Nichi-Rece» (unas 50) con las 137 extraídas del código fuente. Al hacerlo, se ve que existen en el código fuente muchos endpoints que no figuran en la página del listado. A continuación se muestran ejemplos por área funcional (todos los nombres de función se han verificado a partir del campo de nombre del componente de la cabecera COBOL).

Es decir, no solo existe una integración diaria como la recepción o la información de pacientes, sino que, como implementación, existe un conjunto de API capaz de impulsar desde fuera el trabajo mensual de facturación (generación → verificación → salida de datos electrónicos del recibo → administración de facturación). Es una capa que no se percibe si solo se conoce la integración con la historia clínica electrónica.

Aquí hay dos advertencias importantes.

1. No concluir de inmediato que «no está en el listado» equivale a «no documentado». Por ejemplo, la obtención de datos de formularios (formdatagetv2) está documentada en la documentación del lado de PushAPI, así que la página del listado no garantiza cubrir todas las API. Solo se debería decir «no se encuentra documentación» después de haber revisado también las páginas de documentación individuales y la búsqueda dentro del sitio (la tabla anterior es el resultado de haber hecho esa revisión, pero aun así no constituye una prueba completa de que «no existe documentación publicada»).
2. Las implementaciones de terceros también sirven como material de contraste. Un proyecto de código abierto como la biblioteca orca-api, que usa la API de Nichi-Rece desde Ruby, resulta útil como catálogo de referencia de los endpoints que se han usado en la práctica.

8. Derivar la especificación de una API no documentada a partir del código fuente — el caso real de findv3

Aunque se sepa que «existen API que no aparecen en el listado», si no se conoce la forma de la solicitud, tampoco se puede investigar. Aquí es donde entra en juego la plantilla del capítulo 5. Probemos con findv3 (consulta de pacientes).

La estructura de la solicitud está en record/xml_findv3req.db (extracto).

xml_findv3req {
  findv3req {
    Request_Number               varchar(2);
    Patient_Information {
      BirthDate    { First varchar(10); Last varchar(10); };
      Sex                        varchar(1);
      LastVisit_Date { First varchar(10); Last varchar(10); };
      Doctor_Code                varchar(05);
      Department_Code            varchar(2);
      Death_Class                varchar(1);
      Patient_ID   { First varchar(20); Last varchar(20); };
      TestPatient_Class          varchar(1);
      WholeName                  varchar(100)[5];
      ...

Solo con leer la definición se entiende que se trata de una API de búsqueda de pacientes bastante avanzada, que permite combinar un rango de fecha de nacimiento, sexo, un rango de fecha de última visita, médico responsable, departamento clínico, categoría de defunción, un rango de números de paciente y nombre (con múltiples valores), entre otros. Las API de búsqueda de pacientes que figuran en el listado oficial (patientlst1v2 y siguientes) se centran sobre todo en búsquedas de una sola función, como el rango de números de paciente o el nombre, así que esta API, capaz de una búsqueda por condiciones combinadas equivalente a la consulta de pacientes en pantalla, es claramente superior en funcionalidad.

La estructura de la respuesta está, del mismo modo, en record/xml_findv3res.db, y si se lee el COBOL correspondiente (ORCGQAPI01.CBL) también se puede verificar el comportamiento detallado (como el límite del número de resultados o el orden). En ORCA, cuyo código fuente es público, una «API no documentada» es, en realidad, «una API para la que se puede redactar documentación por cuenta propia».

Hasta qué punto se puede confiar en producción en la especificación así derivada: ese es el tema del siguiente capítulo.

9. Medir el cambio de la API mediante diff entre versiones — serie 5.1 frente a serie 5.2

Antes de discutir el riesgo de las API no documentadas, conviene medir de forma empírica «cuánto cambia realmente la API». Este es el resultado de aplicar diff a las definiciones bindapi frente a la instantánea de la serie 5.1 publicada el mismo día:

El desglose de las 9 incorporaciones es el siguiente: 6 relacionadas con la confirmación de elegibilidad en línea (onlinequa10, onlinequa11, onlinequaapp1 a 3, onlineaidlstreq1), el registro de notas de paciente (patientmemomodv2), la devolución masiva de códigos de entrada (inputcodelstv3) y la obtención de información de códigos de entrada y de atención médica (medicationgetv2), 9 en total. Se ve con claridad que la adaptación normativa (en torno a la tarjeta MyNumber de seguro médico) se manifiesta como una ampliación de la API.

De esta observación se pueden extraer los dos puntos siguientes.

• La «superficie» de endpoints es estable (cero eliminaciones entre estas dos series). Lo que hay que temer no es tanto la desaparición como la adición de campos y el cambio de comportamiento en cada API concreta (cambios como los del historial de modificaciones que vimos en el capítulo 5).
• Como el código fuente se publica cada mes, este tipo de detección de cambios se puede automatizar. Si se mantiene un sistema de integración, con solo aplicar diff a lddef y record de la instantánea mensual ya se obtiene una red de alerta temprana sobre lo que va a cambiar en la próxima actualización de versión. Es un medio de mantenimiento propio de la publicación del código fuente, difícil de conseguir con otros sistemas de facturación médica.

10. Cómo relacionarse con las API no documentadas — «documentada» no es garantía

Ante todo, dejemos clara la premisa. El contrato de licencia de código abierto de la Asociación Médica Japonesa, en el artículo 5 del capítulo 2, declara sin garantía todo el programa respecto a su funcionamiento sin problemas o a la ausencia de defectos. Esto se aplica por igual a las API documentadas. Tampoco existe, en cuanto a la compatibilidad, ninguna disposición explícita en la documentación oficial que prometa «no cambiar» las API documentadas; de hecho, como vimos en el capítulo 5, incluso patientgetv2, representante de las API documentadas, ha seguido recibiendo campos adicionales cada vez que hubo una adaptación normativa.

Es decir, la diferencia entre «documentada» y «no documentada» no reside en si hay o no garantía. La diferencia real, llevada al extremo, se reduce solo a los dos puntos siguientes.

1. Si el cambio tiende a reflejarse como una actualización de la documentación oficial (el cambio de una API no documentada no se ve a menos que se lea el código fuente)
2. Si es más fácil llevarlo a la conversación con el proveedor de soporte

Y en ORCA el código fuente se publica cada mes. La diferencia del primer punto se puede cubrir con la vigilancia del diff del código fuente. El código fuente es la especificación de primera mano, y la documentación no es más que un extracto de ella: esta es la actitud correcta ante el código abierto. Cuando la documentación y el código fuente no coinciden, lo que realmente se ejecuta es el código fuente.

Dicho esto, dado que se trata de un sistema directamente ligado al dinero, como es la facturación de recibos médicos, con independencia de si está documentada o no, toda API que se incorpore al flujo de producción debería ir acompañada de la siguiente operación.

Hay una advertencia operativa. Como la instantánea publicada refleja el contenido al día 1 del mes anterior, si se aplica primero la actualización del paquete en producción, no se podrá leer el código fuente correspondiente hasta después de haberla aplicado. Para que esta vigilancia funcione como alerta temprana, es necesario invertir el orden: actualizar la versión solo después de esperar la publicación y la verificación del código fuente correspondiente.

Dicho de otro modo, una organización que no pueda sostener esta operación no está a salvo aunque use exclusivamente API documentadas. Adoptar como núcleo del negocio un software de código abierto sin garantía significa precisamente esto.

11. Notas prácticas para cuando se profundiza

Estos son los pequeños tropiezos típicos de la fase en la que se profundiza en una API concreta a partir del código fuente.

• La codificación de caracteres es EUC-JP. El código fuente COBOL y sus comentarios están en EUC-JP, así que hay que pasarlos por iconv -f EUC-JP -t UTF-8 antes de leerlos. El documento de licencia (doc/license.html) está en ISO-2022-JP. Tampoco grep encuentra coincidencias con palabras clave en japonés si no se intercala iconv.
• Aprenderse la convención de nombres de programa acelera el trabajo. La forma básica de las API es ORAPI + número de negocio + R (referencia)/S (actualización) + versión (V2/V3), y la versión API de las de pantalla es ORCG〜API〜. El código fuente COBOL se encuentra, en principio, bajo cobol/<nombre de LD>/, pero hay excepciones (el archivo real de las API de orca51 está en cobol/orca52/), así que ante la duda conviene hacer find por el nombre del programa.
• Hay dos tipos de punto de entrada: GET y POST+XML. Se puede estimar que una API sin un registro de solicitud (~req) en el bloque db "xml2" de la definición LD (por ejemplo, patientgetv2) es de tipo parámetros GET, y que la que sí lo tiene es de tipo POST+XML. La confirmación definitiva se hace en el procesamiento de entrada del lado COBOL.
• El significado de los campos de datos se determina cotejando record/ con el documento oficial de definición de tablas. El «original» de los campos de respuesta es record/*.db, y el significado del lado de la base de datos está en el documento oficial de definición de tablas. Poner ambos uno al lado del otro aumenta la fiabilidad. Además, en algunas definiciones coexiste una versión .db.weborca para WebORCA, cuyos límites de arreglo, entre otras cosas, difieren (por ejemplo, xml_acceptlstv2res pasa de 1.000 a 1.500 registros). En el diseño de una integración con WebORCA hay que revisar esa versión.
• Verificar el funcionamiento en un entorno de pruebas. Usando el servidor de prueba oficial o un entorno Docker de la comunidad, se puede llamar a la API y verificarla sin tocar el sistema de facturación médica real. Está terminantemente prohibido «probar» directamente en la máquina de producción.

12. Resumen

• La arquitectura completa de la API de Nichi-Rece está condensada en las definiciones bindapi de lddef/*.ld, y con un simple grep se pueden enumerar los 137 endpoints (serie 5.2, versión de julio de 2026).
• La verdadera naturaleza de la API de Nichi-Rece es ser «la versión API de las tareas de pantalla». bind (pantalla) y bindapi (API) conviven en la misma definición LD, y el nombre del módulo de la URL proviene del número de negocio de la pantalla.
• Una sola API se puede diseccionar en el orden lddef (despacho) → cabecera COBOL (función e historia) → cláusulas COPY (datos que toca) → record/*.db (el original de la estructura XML). El nombre de la etiqueta XML es exactamente el nombre del campo de la definición record.
• La diferencia entre el listado oficial (unas 50) y el código fuente (137) incluye un conjunto de API capaz de impulsar tareas mensuales como la generación del recibo de facturación, la generación de datos electrónicos del recibo o la verificación de datos. Sin embargo, no hay que concluir de inmediato que «no está en el listado» equivale a «no documentado»; hay que verificarlo caso por caso.
• En la medición del diff con la serie 5.1 se observan 9 incorporaciones (centradas en la confirmación de elegibilidad en línea) y 0 eliminaciones. El diff de la instantánea mensual puede usarse como red de alerta temprana para el mantenimiento de la integración.
• El contrato de licencia de uso declara explícitamente que no hay garantía, incluidas las API documentadas: «documentada» no equivale a «segura». El código fuente es la especificación de primera mano. Con independencia de si está documentada o no, si se va a usar en producción hay que combinar la fijación de versión, la vigilancia mensual del diff, la verificación de regresión y la elaboración de documentación propia.

El orden seguido en este artículo, entrar por el código fuente en lugar de por las especificaciones, es un método de investigación aplicable, más allá de ORCA, a cualquier «sistema de negocio longevo en el que la documentación no ha seguido el ritmo de la implementación». Por fortuna, como el código fuente de ORCA es público, este método se puede practicar de forma legal y, además, siempre con la versión más reciente cada mes.

13. Apéndice: tabla de correspondencias de los 137 endpoints (serie 5.2, versión de julio de 2026)

Estos son todos los endpoints extraídos mecánicamente de las definiciones bindapi de lddef/*.ld. El nombre de función de cada fila se ha traducido a partir del contenido literal del campo de nombre del componente de la cabecera de cada programa COBOL. En el código fuente japonés original, ese campo conserva variaciones de notación, paréntesis de ancho completo y grafías que parecen erratas, todo tal cual (por ejemplo, la palabra japonesa para «simulación» aparece deletreada de forma no estándar, y el nombre de endpoint medicatonmodv2 aparece sin la «i» de medicationmodv2); estas peculiaridades no son errores de transcripción de KomuraSoft, y por eso los nombres de endpoint y de programa se han mantenido literales. Esta tabla es el registro de un hecho de la instantánea de la serie 5.2 al 1 de julio de 2026, y no indica si cada endpoint puede usarse ni cuál es su estado de soporte.

La tabla está ordenada por módulo (el primer segmento de la URL). Para encontrar rápidamente la API buscada, conviene acotar en el siguiente orden. Si se introduce el nombre del módulo en la búsqueda de la página del navegador (Ctrl+F), se salta directamente al principio de ese bloque.

14. Referencias

• Información técnica - Nichi-i Hyōjun Recept Software - ORCA Project (publicación del código fuente)
• Especificación de la API de Nichi-i Hyōjun Recept Software - ORCA Project
• API de Nichi-i Hyōjun Recept Software - ORCA Project
• orca-api: biblioteca Ruby para la API de Nichi-i Hyōjun Recept Software (GitHub)
• Código fuente del núcleo de Nichi-Rece, series 5.2 y 5.1 (ambas instantáneas publicadas en julio de 2026): lddef/api01rv2.ld / lddef/orca13.ld / cobol/api01rv2/ORAPI012R1V2.CBL / record/xml_patientinfov2res.db / record/xml_findv3req.db, entre otros — todas las mediciones y citas del cuerpo del artículo se basan en esta instantánea

Artículos relacionados

Artículos recientes con las mismas etiquetas para profundizar en temas cercanos.

Temas relacionados

Estas páginas sitúan el tema en un contexto más amplio de servicios y decisiones.

Servicios relacionados con este tema

El artículo está directamente relacionado con los siguientes servicios.

Preguntas frecuentes

Preguntas habituales en las consultas sobre el tema del artículo.

¿Cuántos endpoints tiene en total la API de Nichi-Rece?

La página oficial con el listado de especificaciones de la API muestra unos 50, pero si se cuentan los archivos de definición LD del código fuente publicado (serie 5.2, instantánea de julio de 2026), los endpoints agrupados mediante bindapi suman 137. Parte de esa diferencia corresponde a funciones como los formularios impresos, que están documentadas en otra página, así que no se puede concluir de inmediato que «no estar en el listado» equivalga a «no estar documentado». Aun así, contar desde el lado del código fuente permite captar la arquitectura completa de la API como información de primera mano. Este artículo incluye la tabla de correspondencias de los 137 endpoints.

¿Se puede usar en producción una API que no aparece en la documentación oficial?

Sí se puede. El código fuente de ORCA es público, por lo que la propia implementación puede consultarse como especificación de primera mano. De hecho, el contrato de licencia de uso declara explícitamente que todo el programa —incluidas las API documentadas— no tiene garantía, así que la premisa de que «lo documentado es seguro» ya es en sí misma errónea. La diferencia real entre lo documentado y lo no documentado se reduce a dos puntos: si el cambio tiende a reflejarse en la documentación oficial y si es más fácil llevarlo a la conversación con el proveedor de soporte. El primer punto se puede cubrir vigilando el diff del código fuente publicado mensualmente, pero el segundo (que las API no documentadas son menos susceptibles de soporte) sigue presente. Si se va a usar en producción, hay que combinar la fijación de versión, la vigilancia de diffs, la verificación de regresión en un entorno de pruebas, la elaboración de documentación propia y compartir la configuración con el proveedor de soporte. Esto, en rigor, debería hacerse igual aunque se use una API documentada.

¿También se puede conocer desde el código fuente el formato de las solicitudes y respuestas de la API?

Sí. La estructura de las solicitudes y respuestas XML de Nichi-Rece está escrita de forma declarativa en los archivos de definición del directorio record/ (por ejemplo, record/xml_patientinfov2res.db), y los nombres de las etiquetas XML son exactamente los nombres de los campos de esa definición. Incluso en una API no documentada, si se identifica el programa responsable a partir de la definición LD y se lee la definición record correspondiente, se pueden derivar todos los campos de la solicitud y la respuesta.

¿Se puede investigar aunque no se sepa leer COBOL?

Para captar solo la arquitectura completa de los endpoints, la lectura de COBOL es casi innecesaria. Los archivos de definición LD (lddef/*.ld) y las definiciones de estructura de datos (record/*.db) son texto plano, y en ellos está escrita de forma declarativa la correspondencia entre la URL, el programa y la estructura XML. Solo cuando se profundiza en el comportamiento interno de una API concreta hay que empezar a leer COBOL, pero incluso ahí se puede obtener mucha información solo con los comentarios (en japonés) de la cabecera del programa y el historial de modificaciones.

Perfil del autor

Página de presentación del autor del artículo.

Go Komura

Representante de KomuraSoft LLC

Especializado en desarrollo de software para Windows, consultoría técnica e investigación de fallos, sobre todo en proyectos con sistemas existentes y errores difíciles de reproducir.