Das Gesamtbild der Nichi-Rece-API aus dem Quellcode erschließen ── ORCAs veröffentlichten Quellcode lesen (mit Zuordnungstabelle aller 137 Endpunkte)

Im vorigen Artikel haben wir festgestellt, dass ORCA (die JMA Standard Receipt Software) ein medizinisches Abrechnungssystem ist und dass sein Quellcode seit über zwanzig Jahren fortlaufend veröffentlicht wird.

Diesmal lesen wir diesen Quellcode tatsächlich. Das Thema: das Gesamtbild der Nichi-Rece-API aus Primärinformation erschließen. Statt die offizielle API-Spezifikation von oben nach unten durchzulesen, gehen wir wie folgt vor:

1. alle tatsächlich auf dem Server existierenden Endpunkte aus dem Quellcode auszählen,
2. eine einzelne API von der Implementierung bis zur Form der Antwort-XML verfolgen,
3. mit der offiziellen Dokumentation abgleichen und die Unterschiede verifizieren, sowie
4. den Wandel der API mit einem versionsübergreifenden Diff messen.

Am Ende des Artikels finden Sie eine Zuordnungstabelle aller 137 in dieser Untersuchung ermittelten Endpunkte (URL, COBOL-Programm, Funktion).

Gegenstand dieser Untersuchung ist der offiziell veröffentlichte Nichi-Rece-Quellcode der 5.2er-Serie (Snapshot vom 1. Juli 2026), wobei zum Vergleich die 5.1er-Serie (am selben Tag veröffentlicht) herangezogen wird. Alles hier Beschriebene beruht auf diesen beiden Veröffentlichungen, und die zur Reproduktion nötigen Befehle sind im Text angegeben.

Inhaltsverzeichnis

1. Zunächst das Fazit
2. Voraussetzungen ── Quellcode beschaffen und die Version fixieren
3. Wie das API-Dispatching funktioniert ── die URL wird durch lddef bestimmt
4. Eine Entdeckung: Die APIs sind „die API-Ausgaben bildschirmbasierter Arbeitsabläufe“ ── bind und bindapi
5. Eine einzelne API bis zum Ende verfolgen ── patientgetv2 seziert
6. Alle Endpunkte auszählen ── ein Untersuchungsverfahren mit einem einzigen grep
7. Abgleich mit der offiziellen Liste ── Beispiele für APIs, die dort nicht stehen
8. Die Spezifikation einer nicht dokumentierten API aus dem Quellcode ableiten ── der Fall findv3
9. Den API-Wandel mit einem versionsübergreifenden Diff messen ── 5.1er-Serie vs. 5.2er-Serie
10. Der Umgang mit nicht dokumentierten APIs ── „dokumentiert“ ist keine Garantie
11. Praktische Hinweise beim tieferen Nachforschen
12. Zusammenfassung
13. Anhang: Zuordnungstabelle aller 137 Endpunkte (5.2er-Serie, Juli 2026)
14. Quellen

1. Zunächst das Fazit

• Die Zuordnung zwischen den URLs der Nichi-Rece-API und den serverseitigen Programmen ist im Quellcode deklarativ in lddef/*.ld (den LD-Definitionsdateien) festgelegt. Ohne COBOL zu lesen, lässt sich das gesamte API-Bild allein mit einem Text-grep auflisten.
• Im Snapshot der 5.2er-Serie sind über 27 LD-Definitionen insgesamt 137 Endpunkte mit bindapi gebunden. Auf der Übersichtsseite der API-Spezifikation der offiziellen Website stehen rund 50 – im Quellcode existieren also mehr als doppelt so viele Endpunkte.
• Die Struktur der XML-Anfragen und -Antworten ist in record/*.db deklariert, und die XML-Tag-Namen sind die Feldnamen der Definitionen wortwörtlich. Auch bei einer nicht dokumentierten API lässt sich die Spezifikation also über lddef → cobol → record ableiten.
• Ein versionsübergreifender Diff gegenüber der 5.1er-Serie zeigt 9 hinzugekommene und 0 entfernte Endpunkte. Die Ergänzungen konzentrieren sich auf die Online-Anspruchsprüfung (My-Number-Versichertenkarte), was den messbaren Nachweis liefert, dass „APIs durch regulatorische Arbeit wachsen, und bestehende (zumindest zwischen diesen beiden Serien) nicht verschwinden“.
• Eine nicht dokumentierte API ist keine API, die man nicht verwenden darf. ORCA ist Open Source, und der Quellcode selbst kann als Primärspezifikation behandelt werden. Die Frage ist nicht, ob ein Versprechen existiert, sondern ob Sie eine Praxis betreiben können, die Änderungen selbst erkennt – ein Rahmen für diese Beurteilung wird in Kapitel 10 dargelegt.

2. Voraussetzungen ── Quellcode beschaffen und die Version fixieren

Der Quellcode lässt sich von der offiziellen technischen Informationsseite als Tarball (Zip) herunterladen. Er wird am Ersten jedes Monats auf einen Snapshot zum Stand des Ersten des Vormonats aktualisiert, weshalb die eiserne Regel lautet, Untersuchungsergebnisse stets zusammen mit der Version zu dokumentieren, aus der sie stammen. Dieser Artikel verwendet Folgendes.

• Quelle: https://ftp.orca.med.or.jp/pub/src/jma-receipt.r_5_2_branch.zip (zum Vergleich zusätzlich r_5_1_branch.zip)
• Abgerufen: 2026-07-17 (beide sind Snapshots zum Stand 1. Juli 2026)
• VERSION-Datei der 5.2er-Serie: 5.2.0

Entpackt sind es rund 8.200 Dateien und 237 MB, und dieser Artikel nutzt hauptsächlich die folgenden drei Verzeichnisse.

3. Wie das API-Dispatching funktioniert ── die URL wird durch lddef bestimmt

Nichi-Rece-API-URLs bestehen aus zwei Segmenten der Form „Modulname/Endpunktname“, wie etwa /api01rv2/patientgetv2. Diese Zuordnung erscheint direkt in den LD-Definitionsdateien unter lddef/.

Hier der Beginn von lddef/api01rv2.ld.

name	api01rv2;

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

Das Lesen ist unkompliziert: Der LD-Name ist das erste URL-Segment, das erste Argument von bindapi ist das zweite Segment, und das dritte Argument ist der Name des COBOL-Programms, das die Anfrage verarbeitet. Eine Anfrage an /api01rv2/patientgetv2 wird also an ein COBOL-Programm namens ORAPI012R1V2 weitergeleitet.

flowchart LR
    C["Integrierendes System<br/>z. B. elektronische Patientenakte"] -->|"GET /api01rv2/patientgetv2?id=Patientennummer"| M["Nichi-Rece-Server<br/>MONTSUQI"]
    M -->|"lddef/api01rv2.ld<br/>zieht die bindapi-Definition heran"| P["ORAPI012R1V2.CBL<br/>Patientenstammdaten abrufen"]
    P --> D[("PostgreSQL")]
    P -->|"XML-Antwort"| C

LD-Definitionen deklarieren daneben auch das für die Zusammenstellung von Antworten verwendete XML-Datensatzset (db "xml2" { ... }) sowie einige nützliche Einstellungen (Array-Größen und Ähnliches). Eine LD-Datei lässt sich als „Inhaltsverzeichnis der Bildschirme, APIs und Datenstrukturen, die dieses Modul behandelt“ lesen.

4. Eine Entdeckung: Die APIs sind „die API-Ausgaben bildschirmbasierter Arbeitsabläufe“ ── bind und bindapi

Betrachtet man die LD-Definitionen eine Weile, fällt sofort etwas auf: bind (Bildschirme) und bindapi (APIs) koexistieren in derselben Datei. Hier das Patientenanfragemodul, lddef/orca13.ld.

name	orca13;

bind	"Q01"		"OpenCOBOL"	"ORCGQ01";     ← der interaktive Patientenanfrage-Bildschirm
bind	"Q02"		"OpenCOBOL"	"ORCGQ02";
...
bindapi "findv3"    "OpenCOBOL"	"ORCGQAPI01";  ← dessen API-Ausgabe
bindapi "findinfv3" "OpenCOBOL"	"ORCGQAPI02";
bindapi "foundv3"   "OpenCOBOL"	"ORCGQAPI03";

Q01 und seine Geschwister sind die Programme hinter den Patientenanfrage-Bildschirmen, die das Verwaltungspersonal bedient; findv3 und seine Geschwister sind APIs, die zu genau diesem Modul gehören. Selbst die Programmnamen folgen diesem Muster: ORCGQ01 (Bildschirm) gegenüber ORCGQAPI01 (API) – der Bildschirmname mit eingefügtem „API“.

Mit anderen Worten: Die Nichi-Rece-API wurde nicht als eigenständiger API-Server entworfen. Sie ist ein „Eingangspunkt, der statt über einen Bildschirm per XML kommuniziert“, der modulweise auf derselben Fachprogrammplattform aufgesetzt wurde wie die interaktiven Bildschirme. Hat man diese Struktur einmal erkannt, ergeben sich zwei Dinge von selbst.

• Warum das erste URL-Segment (orca13, orca42, …) sich von der Geschäftsnummer eines Bildschirms herleitet und aus API-Sicht wie eine bedeutungslose Zahl wirkt.
• Warum die Suchstrategie „was auf einem Bildschirm geht, hat vielleicht auch eine API-Ausgabe“ funktioniert – die Suche nach nicht dokumentierten APIs kommt in Wirklichkeit dem Auflisten dieser „API-Ausgaben bildschirmbasierter Arbeitsabläufe“ ziemlich nahe.

5. Eine einzelne API bis zum Ende verfolgen ── patientgetv2 seziert

Bevor wir das Gesamtbild auszählen, verfolgen wir eine einzelne API von der Implementierung bis zur Form ihrer Antwort. Gegenstand ist die grundlegendste von allen, der Abruf der Patientenstammdaten: /api01rv2/patientgetv2.

(1) Dispatching: bindapi "patientgetv2" → ORAPI012R1V2 in lddef/api01rv2.ld. Die Implementierung ist cobol/api01rv2/ORAPI012R1V2.CBL (2.163 Zeilen). Da COBOL-Quellen grundsätzlich in einem nach der LD benannten Verzeichnis liegen, lässt sich die Implementierungsdatei fast mechanisch identifizieren, sobald man lddef lesen kann (es gibt Ausnahmen – zum Beispiel liegen die Implementierungen der orca51-APIs in cobol/orca52/; verlässlich ist die Suche mit find nach dem Programmnamen).

(2) Der Programmkopf: Oben steht „Komponentenname: Abruf der Patientenstammdaten (Unterstützung für Version 2)“, und das anschließende Änderungsprotokoll reiht jede regulatorische Reform auf, die diese eine API absorbiert hat – als Chronologie, von der Unterstützung für regionale Integrations-IDs 2013 über die Unterstützung elektronischer Verschreibungen 2022 bis hin zur „Rückgabe der Anspruchsgültigkeit aus der Versichertenkarte“ 2024. Das ist detaillierter als der „Änderungsverlauf“ in der API-Spezifikation.

(3) Was gelesen wird: Die COPY-Klauseln in der WORKING-STORAGE SECTION (die eingebundenen gemeinsamen Definitionen) verraten, welche Daten diese API berührt. Ein Auszug:

COPY "CPPTINF.INC".          *> Patientenstammdaten (tbl_ptinf)
COPY "CPPTNUM.INC".          *> Patientennummer
COPY "CPJYURRK.INC".         *> Behandlungshistorie
COPY "CPPTCARE-HKNINF.INC".  *> Pflegeversicherungsinformationen
COPY "CPPTMYNUMBER.INC".     *> My Number der Patientin/des Patienten
COPY "CPONSHI-KAKU.INC".     *> Ergebnis der Online-Anspruchsprüfung
COPY "CPPATIENTXMLV2RES.INC" *> Formatierung der Antwort

Eine API, die lediglich eine Patientin oder einen Patienten zurückgibt, zieht fast dreißig Definitionen heran, die bis zur Pflegeversicherung, My Number und Online-Anspruchsprüfung reichen. Das ist ein handfester Beleg dafür, dass die Bedeutung von „Patientenstammdaten“ mit den Regularien stetig gewachsen ist.

(4) Die Form der Antwort: Die Struktur der Antwort-XML ist in record/xml_patientinfov2res.db deklariert.

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);
                ...

Wer die Nichi-Rece-API bereits verwendet hat, wird das wiedererkennen. Die XML-Tag-Namen in API-Antworten (Patient_ID, WholeName, …) sind die Feldnamen dieser record-Definition wortwörtlich. Anders gesagt: Das „Original“ der Feldtabellen in der offiziellen XML-Spezifikation liegt genau hier. Auch die Feldgrößen (Stellenzahlen) sind angegeben, sodass sich das Ganze auch als Primärinformation für den Validierungsentwurf auf integrierender Seite nutzen lässt.

Die Schritte (1) bis (4) sind die Vorlage für die Sezierung einer einzelnen Nichi-Rece-API. Das Programm über lddef identifizieren, Funktion und Historie aus dem Kopf ableiten, über die COPY-Klauseln erfahren, welche Daten berührt werden, und über record die Nachrichtenstruktur festlegen – ohne die COBOL-Logik selbst zu lesen, erhalten Sie damit den Großteil der in der Praxis benötigten Information.

6. Alle Endpunkte auszählen ── ein Untersuchungsverfahren mit einem einzigen grep

Ist der Mechanismus einmal verstanden, ist die vollständige Auflistung mechanische Arbeit.

# Die Zuordnung Endpunkt → COBOL-Programm vollständig auflisten
grep -H '^[[:space:]]*bindapi' lddef/*.ld

# Anzahl je Modul
for f in lddef/*.ld; do
  n=$(grep -c '^[[:space:]]*bindapi' "$f"); [ "$n" -gt 0 ] && echo "$f: $n"
done

# Den Funktionsnamen jedes Endpunkts mechanisch aus dem COBOL-Kopf extrahieren
# (der Quellcode ist EUC-JP, daher iconv zwischenschalten. Der Ablageort des
#  Programms stimmt mit Ausnahmen nicht mit dem LD-Namen überein, daher mit find ermitteln)
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

Die Zusammenfassung für diese Version lautet wie folgt (die einzelnen Einträge aller 137 stehen im Anhang).

Während sich rund 40 Prozent auf die lesenden Operationen (api01rv2) konzentrieren, sind die schreibenden Operationen nach Fachmodul aufgeteilt (Patient = orca12, Empfang = orca11, medizinische Leistungen = api21, …). Die in Kapitel 4 beschriebene Struktur „API-Ausgaben bildschirmbasierter Arbeitsabläufe“ zeigt sich unmittelbar auch in dieser Verteilung.

Bemerkenswert ist außerdem, dass APIs beigemischt sind, die eher Plattformfunktionen als Geschäftsfunktionen darstellen – session_start (Login-Authentifizierung) im Modul session oder print in orca00. Egal wie lange man die offizielle Spezifikationsübersicht betrachtet, diese Ebene fällt dabei nie auf.

7. Abgleich mit der offiziellen Liste ── Beispiele für APIs, die dort nicht stehen

Als Nächstes gleichen wir die auf der Übersichtsseite „JMA Standard Receipt Software API Specification“ der offiziellen Website gelisteten APIs (rund 50) mit den aus dem Quellcode extrahierten 137 ab. Dabei zeigt sich, dass auf der Quellcodeseite zahlreiche Endpunkte existieren, die auf der Übersichtsseite nicht auftauchen. Hier Beispiele nach Funktionsbereich (alle Funktionsnamen wurden jeweils dem „Komponentenname“-Feld im COBOL-Kopf entnommen).

Anders gesagt: Neben alltäglichen Integrationen wie Empfang und Patientendaten existiert als Implementierung ein Satz von APIs, mit denen sich die monatliche Abrechnungsarbeit (Erstellung → Prüfung → Ausgabe elektronischer Abrechnungsdaten → Forderungsverwaltung) von außen steuern lässt. Diese Ebene bleibt unsichtbar, wenn man nur die Integration über die elektronische Patientenakte kennt.

Zwei wichtige Hinweise dazu.

1. Nicht sofort von „nicht auf der Liste“ auf „nicht dokumentiert“ schließen. Der Abruf von Formulardaten (formdatagetv2) etwa ist auf der PushAPI-Seite dokumentiert, und die Übersichtsseite garantiert keine vollständige Abdeckung aller APIs. Erst nach Prüfung einzelner Dokumentationsseiten und einer Suche auf der Website sollte man „keine Dokumentation gefunden“ sagen (die obige Tabelle ist das Ergebnis genau dieser Prüfung, doch auch das ist kein vollständiger Beweis dafür, dass keine veröffentlichte Dokumentation existiert).
2. Auch Drittanbieter-Implementierungen taugen als Abgleichmaterial. Open-Source-Software wie die orca-api-Bibliothek, die die Nichi-Rece-API aus Ruby heraus nutzt, ist als Katalog der in der Praxis tatsächlich verwendeten Endpunkte hilfreich.

8. Die Spezifikation einer nicht dokumentierten API aus dem Quellcode ableiten ── der Fall findv3

Zu wissen, dass „APIs existieren, die nicht auf der Liste stehen“, bringt nichts, solange man die Form der Anfrage nicht kennt. Hier zahlt sich die Vorlage aus Kapitel 5 aus. Probieren wir es mit findv3 (Patientenanfrage).

Die Anfragestruktur steht in record/xml_findv3req.db (Auszug).

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];
      ...

Allein das Lesen der Definition verrät, dass dies eine ziemlich leistungsfähige Patientensuch-API ist, die einen Geburtsdatumsbereich, das Geschlecht, einen Bereich für das letzte Besuchsdatum, die behandelnde Ärztin oder den behandelnden Arzt, die Abteilung, den Verstorbenenstatus, einen Patientennummernbereich sowie Namen (Mehrfachangabe möglich) kombinieren kann. Die auf der offiziellen Liste stehenden Patientensuch-APIs (patientlst1v2 und Verwandte) sind überwiegend einzweckige Suchen etwa nach einem Patientennummernbereich oder einem Namen, sodass diese API – die eine mit dem Patientenanfrage-Bildschirm vergleichbare Verbundsuche bietet – funktional klar überlegen ist.

Auch die Antwortstruktur liegt entsprechend in record/xml_findv3res.db, und liest man das zugehörige COBOL (ORCGQAPI01.CBL), lassen sich auch feinere Verhaltensweisen (Höchstgrenzen der Anzahl, Sortierreihenfolge und Ähnliches) bestätigen. Eine „nicht dokumentierte API“ ist bei ORCA, dessen Quellcode veröffentlicht ist, in Wirklichkeit „eine API, für die Sie sich die Dokumentation selbst schreiben können“.

Wie weit man einer so abgeleiteten Spezifikation in der Produktion vertrauen sollte, ist das Thema des übernächsten Kapitels.

9. Den API-Wandel mit einem versionsübergreifenden Diff messen ── 5.1er-Serie vs. 5.2er-Serie

Bevor wir das Risiko nicht dokumentierter APIs diskutieren, messen wir, wie stark sich APIs überhaupt verändern. Ein Diff der bindapi-Definitionen gegenüber dem am selben Tag veröffentlichten 5.1er-Serien-Snapshot:

Die neun Ergänzungen gliedern sich in sechs Endpunkte im Zusammenhang mit der Online-Anspruchsprüfung (onlinequa10, onlinequa11, onlinequaapp1 bis 3, onlineaidlstreq1) sowie die Patientenmemo-Registrierung (patientmemomodv2), die Massenrückgabe von Eingabecodes (inputcodelstv3) und den Abruf von Eingabe- und Leistungscodeinformationen (medicationgetv2) – neun insgesamt. Es zeigt sich deutlich, dass regulatorische Arbeit (rund um die My-Number-Versichertenkarte) sich als neue API-Endpunkte niederschlägt.

Zwei Dinge lassen sich aus dieser Beobachtung ableiten.

• Die „Fläche“ der Endpunkte ist stabil (null Entfernungen zwischen diesen beiden Serien). Zu befürchten ist nicht ein Verschwinden, sondern das Hinzufügen von Feldern zu einzelnen APIs und Verhaltensänderungen – Änderungen der Art, wie wir sie in Kapitel 5 im Änderungsprotokoll gesehen haben.
• Da der Quellcode monatlich veröffentlicht wird, lässt sich diese Art der Änderungserkennung automatisieren. Wer ein integrierendes System wartet, erhält allein durch das Diffen von lddef und record zwischen den monatlichen Snapshots ein Frühwarnnetz dafür, was das nächste monatliche Update ändern wird. Das ist eine Wartungsfähigkeit, die einzig durch die Quellcode-Veröffentlichung möglich wird und bei anderen medizinischen Abrechnungssystemen kaum zu erreichen ist.

10. Der Umgang mit nicht dokumentierten APIs ── „dokumentiert“ ist keine Garantie

Zunächst zur Klärung der Grundlage. Art. 5 in Kapitel 2 der JMA-OpenSource-Lizenz schließt jegliche Gewährleistung für das gesamte Programm aus, einschließlich des störungsfreien Betriebs und des Fehlens von Mängeln. Das gilt gleichermaßen für dokumentierte APIs. Auch zur Kompatibilität gibt es in den offiziellen Dokumenten keine ausdrückliche Regelung, die verspricht, dokumentierte APIs „nicht zu ändern“ – tatsächlich hat, wie wir in Kapitel 5 gesehen haben, selbst patientgetv2, das Aushängeschild der dokumentierten APIs, bei jeder regulatorischen Reform Felder hinzugewonnen.

Der Unterschied zwischen „dokumentiert“ und „nicht dokumentiert“ liegt also nicht im Vorhandensein einer Garantie. Auf den Punkt gebracht, sind es nur diese beiden Punkte.

1. Ob eine Änderung wahrscheinlich als Aktualisierung der offiziellen Dokumentation sichtbar wird (Änderungen an einer nicht dokumentierten API bleiben unsichtbar, sofern man den Quellcode nicht liest)
2. Ob sie eine gemeinsame Gesprächsgrundlage mit dem Support-Anbieter bietet

Und ORCA veröffentlicht seinen Quellcode jeden Monat. Der erste Unterschied lässt sich durch Diff-Überwachung des Quellcodes schließen. Der Quellcode ist die Primärspezifikation, die Dokumentation lediglich eine gekürzte Übersetzung davon – das ist die korrekte Haltung gegenüber Open Source. Widersprechen sich Dokumentation und Quellcode, läuft in Wirklichkeit der Quellcode.

Da es sich bei der Abrechnung um ein System handelt, das unmittelbar mit Geld verknüpft ist, sollten Sie unabhängig davon, ob eine API dokumentiert ist, jede API, die Sie in einen Produktionsablauf einbauen, mit folgender Betriebspraxis kombinieren.

Ein betrieblicher Hinweis. Der veröffentlichte Snapshot spiegelt den Stand des Ersten des Vormonats wider, sodass Sie, wenden Sie ein Paket-Update zuerst auf die Produktion an, den entsprechenden Quellcode erst im Nachhinein lesen können. Damit diese Überwachung als Frühwarnsystem funktioniert, müssen Sie die Reihenfolge umkehren: erst warten, bis der entsprechende Quellcode veröffentlicht und verifiziert ist, und erst dann das Upgrade durchführen.

Umgekehrt gilt: Eine Organisation, die diese Praxis nicht durchhalten kann, ist auch dann nicht sicher, wenn sie nur dokumentierte APIs verwendet. Genau das bedeutet es, nicht gewährleistete Open Source ins Zentrum des Geschäftsbetriebs zu stellen.

11. Praktische Hinweise beim tieferen Nachforschen

Kleine Stolperfallen in dem Stadium, in dem Sie einer einzelnen API im Quellcode weiter nachgehen.

• Die Zeichenkodierung ist EUC-JP. COBOL-Quellen und -Kommentare sind EUC-JP, führen Sie sie also vor dem Lesen durch iconv -f EUC-JP -t UTF-8. Das Lizenzdokument (doc/license.html) ist ISO-2022-JP. Auch grep findet japanische Schlüsselwörter nur, wenn Sie iconv zwischenschalten.
• Die Namenskonvention der Programme zu kennen, beschleunigt vieles. Die Grundform für API-Programme lautet ORAPI + Geschäftsnummer + R (lesen)/S (schreiben) + Version (V2/V3); die API-Ausgaben von Bildschirmprogrammen heißen ORCG…API…. COBOL-Quellen liegen grundsätzlich unter cobol/<LD-Name>/, es gibt jedoch Ausnahmen (die API-Implementierungen von orca51 liegen in cobol/orca52/), suchen Sie im Zweifel also mit find nach dem Programmnamen.
• Es gibt zwei Arten von Eingangspunkten: GET-artig und POST+XML-artig. Eine API ohne Anfrage-Datensatz (…req) im db "xml2"-Block ihrer LD-Definition (etwa patientgetv2) ist vermutlich vom Typ GET-Parameter; eine mit Anfrage-Datensatz vermutlich vom Typ POST+XML. Endgültig bestätigen Sie das in der Eingabeverarbeitung auf COBOL-Seite.
• Die Bedeutung von Datenfeldern durch Abgleich von record/ mit dem offiziellen Tabellendefinitionsdokument klären. Das „Original“ der Antwortfelder ist record/*.db, die Bedeutung auf DB-Seite steht im offiziell veröffentlichten Tabellendefinitionsdokument. Beides nebeneinanderzulegen erhöht die Sicherheit. Beachten Sie außerdem, dass manche Definitionen eine koexistierende WebORCA-spezifische .db.weborca-Version besitzen, in der sich etwa Array-Obergrenzen unterscheiden (zum Beispiel geht xml_acceptlstv2res von 1.000 auf 1.500 Einträge). Prüfen Sie diese beim Entwurf einer WebORCA-Integration.
• Funktionstests in einer Testumgebung durchführen. Der offizielle Testserver oder eine Community-Docker-Umgebung erlauben es, die API anzusprechen und das Verhalten zu prüfen, ohne ein produktives medizinisches Abrechnungssystem anzufassen. „Ausprobieren“ auf einer Produktionsmaschine ist tabu.

12. Zusammenfassung

• Das gesamte Bild der Nichi-Rece-API konzentriert sich auf die bindapi-Definitionen in lddef/*.ld, und grep allein listet 137 Endpunkte auf (5.2er-Serie, Veröffentlichung Juli 2026).
• Was die Nichi-Rece-API eigentlich ist, ist „die API-Ausgabe bildschirmbasierter Arbeitsabläufe“. bind (Bildschirme) und bindapi (APIs) koexistieren in derselben LD-Definition, und der Modulname in der URL leitet sich von der Geschäftsnummer eines Bildschirms ab.
• Eine einzelne API lässt sich in der Reihenfolge lddef (Dispatching) → COBOL-Kopf (Funktion und Historie) → COPY-Klauseln (berührte Daten) → record/*.db (das Original der XML-Struktur) sezieren. Die XML-Tag-Namen sind exakt die Feldnamen der record-Definition.
• Die Lücke zwischen der offiziellen Liste (rund 50) und dem Quellcode (137) umfasst einen Satz von APIs, mit denen sich der monatliche Arbeitsablauf steuern lässt – Erstellung der Abrechnung, Erstellung elektronischer Abrechnungsdaten, Datenprüfung. Schließen Sie aber nicht sofort von „nicht auf der Liste“ auf „nicht dokumentiert“; prüfen Sie fallweise.
• Der gemessene Diff gegenüber der 5.1er-Serie zeigt 9 Ergänzungen (überwiegend im Bereich Online-Anspruchsprüfung) und 0 Entfernungen. Das Diffen der monatlichen Snapshots lässt sich als Frühwarnnetz für die Integrationswartung nutzen.
• Die Lizenzvereinbarung schließt ausdrücklich jegliche Gewährleistung aus, auch für dokumentierte APIs, sodass „dokumentiert“ nicht „sicher“ bedeutet. Der Quellcode ist die Primärspezifikation. Ob dokumentiert oder nicht – setzen Sie es in der Produktion ein, kombinieren Sie es mit Versionsfixierung, monatlicher Diff-Überwachung, Regressionstests und eigener Dokumentation.

Nicht bei der Spezifikation, sondern beim Quellcode anzufangen, wie wir es hier getan haben, ist eine Untersuchungstechnik, die weit über ORCA hinaus funktioniert – für jedes langlebige Fachanwendungssystem, dessen Dokumentation hinter seiner Implementierung zurückgeblieben ist. Glücklicherweise ist der Quellcode von ORCA veröffentlicht, sodass Sie diese Technik legal und jeden Monat gegen den aktuellsten Stand praktizieren können.

13. Anhang: Zuordnungstabelle aller 137 Endpunkte (5.2er-Serie, Juli 2026)

Dies sind alle Endpunkte, die mechanisch aus den bindapi-Definitionen in lddef/*.ld extrahiert wurden. Die Funktionsnamen sind deutsche Übertragungen des Felds „Komponentenname“ im Kopf jedes COBOL-Programms (die japanischen Originale sind in der japanischen Ausgabe dieses Artikels wortwörtlich übernommen, einschließlich Schreibvarianten und Vollbreitenklammern). Diese Tabelle ist eine Bestandsaufnahme des 5.2er-Serien-Snapshots zum Stand des 1. Juli 2026; sie sagt nichts über Nutzbarkeit oder Support-Status der einzelnen Endpunkte aus.

14. Quellen

• Technische Informationen - JMA Standard Receipt Software - ORCA Project (Quellcode-Veröffentlichungen)
• JMA Standard Receipt Software API Specification - ORCA Project
• JMA Standard Receipt Software API - ORCA Project
• orca-api: eine Ruby-Bibliothek für die JMA Standard Receipt Software API (GitHub)
• Quellcode der Nichi-Rece-5.2er- und 5.1er-Serie (beide Snapshots veröffentlicht im Juli 2026) lddef/api01rv2.ld / lddef/orca13.ld / cobol/api01rv2/ORAPI012R1V2.CBL / record/xml_patientinfov2res.db / record/xml_findv3req.db und weitere ── alle Messwerte und Zitate im Artikel beruhen auf diesen Snapshots

Verwandte Artikel

Aktuelle Artikel mit denselben Schlagwörtern führen zu verwandten Themen weiter.

Verwandte Themen

Diese Seiten ordnen den Artikel in einen größeren Leistungs- und Entscheidungskontext ein.

Leistungen zu diesem Thema

Dieser Artikel ist direkt mit den folgenden Leistungen verbunden.

Häufige Fragen

Fragen, die in Beratungen zu diesem Artikelthema häufig gestellt werden.

Wie viele Endpunkte hat die Nichi-Rece-API insgesamt?

Die Übersichtsseite der API-Spezifikation auf der offiziellen Website listet rund 50 auf, doch zählt man die LD-Definitionsdateien im veröffentlichten Quellcode (5.2er-Serie, Snapshot vom Juli 2026), ergeben sich 137 mit bindapi gebundene Endpunkte. Ein Teil der Differenz ist auf separaten Seiten dokumentiert – etwa formularbezogene APIs –, sodass man nicht sofort schließen kann, „nicht auf der Liste“ bedeute „nicht dokumentiert“. Dennoch lässt sich durch das Zählen auf der Quellcodeseite das gesamte API-Bild als Primärinformation erschließen. Dieser Artikel enthält eine Zuordnungstabelle aller 137.

Ist es zulässig, eine API zu verwenden, die nicht in der offiziellen Dokumentation steht?

Ja. Der Quellcode von ORCA ist veröffentlicht, sodass Sie die Implementierung selbst als Primärspezifikation überprüfen können. Ohnehin schließt die Lizenzvereinbarung jegliche Gewährleistung für das gesamte Programm ausdrücklich aus, einschließlich dokumentierter APIs, sodass die Annahme „dokumentiert bedeutet sicher“ die eigentlich falsche Position ist. Der substanzielle Unterschied zur Dokumentation liegt in zwei Punkten: ob eine Änderung wahrscheinlich in der offiziellen Dokumentation auftaucht, und ob sie eine gemeinsame Gesprächsgrundlage mit dem Support-Anbieter bietet. Der erste Punkt lässt sich durch das Diffen der monatlichen Quellcode-Veröffentlichungen schließen; der zweite (nicht dokumentierte APIs werden seltener unterstützt) bleibt bestehen. Setzen Sie eine solche API in der Produktion ein, kombinieren Sie sie mit Versionsfixierung, Diff-Überwachung, Regressionstests in einer Testumgebung, eigener Dokumentation und dem Teilen Ihrer Konfiguration mit dem Support-Anbieter. Das sollten Sie eigentlich auch bei dokumentierten APIs tun.

Lassen sich auch Anfrage- und Antwortformate der API aus dem Quellcode ablesen?

Ja. Die Struktur von Nichi-Reces XML-Anfragen und -Antworten ist in Definitionsdateien im Verzeichnis record/ deklariert (zum Beispiel record/xml_patientinfov2res.db), und die XML-Tag-Namen sind die Feldnamen dieser Definitionen wortwörtlich. Auch bei einer nicht dokumentierten API lässt sich das zuständige Programm anhand der LD-Definition identifizieren, die passende record-Definition lesen und daraus jedes Feld von Anfrage und Antwort ableiten.

Kann ich das auch untersuchen, wenn ich kein COBOL lesen kann?

Das Lesen von COBOL ist so gut wie unnötig, wenn Sie nur das Gesamtbild der Endpunkte erfassen wollen. Die LD-Definitionsdateien (lddef/*.ld) und die Datenstrukturdefinitionen (record/*.db) sind reiner Text und deklarieren die Zuordnung zwischen URL, Programm und XML-Struktur. Erst wenn Sie dem internen Verhalten einer einzelnen API weiter nachgehen wollen, beginnen Sie mit dem Lesen von COBOL – und selbst dann liefern allein die Kommentare im Programmkopf (auf Japanisch) und das Änderungsprotokoll eine große Menge an Information.

Autorenprofil

Profilseite des Artikelautors.

Go Komura

Geschäftsführer von KomuraSoft LLC

Spezialisiert auf Windows-Softwareentwicklung, technische Beratung und Fehleranalyse, insbesondere bei bestehenden Systemen und schwer reproduzierbaren Störungen.