Comprendre le panorama complet de l'API 日レセ à partir du code source ── Lire les sources publiques d'ORCA (avec un tableau de correspondance des 137 points de terminaison)

L’article précédent a passé en revue le fait qu’ORCA (日医標準レセプトソフト) est un système de facturation médicale (レセコン), et que son code source est publié en continu depuis plus de vingt ans.

Cette fois, nous allons réellement lire ce code source. Le thème est de comprendre le panorama complet de l’API 日レセ à partir de l’information de première main. Plutôt que de lire la spécification officielle de l’API de haut en bas, nous procédons dans cet ordre :

1. dénombrer à partir du code source l’ensemble des points de terminaison réellement présents côté serveur,
2. suivre une API, de son implémentation jusqu’à la forme de sa réponse XML,
3. confronter ce résultat à la documentation officielle pour en vérifier les écarts,
4. mesurer concrètement l’évolution de l’API par un diff entre versions.

À la fin de l’article se trouve le tableau de correspondance des 137 points de terminaison (URL, programme COBOL, fonctionnalité) issu de cette investigation.

L’objet de cette investigation est le code source officiellement public du 日レセ, branche 5.2 (instantané publié le 1er juillet 2026), avec, à titre de comparaison, la branche 5.1 (publiée le même jour). Tout ce qui est décrit repose sur ces deux versions, et les commandes nécessaires à la reproduction sont indiquées dans le corps du texte.

Le public visé est celui des développeurs qui vont concevoir ou implémenter une intégration avec l’API 日レセ. Savoir lire le COBOL n’est pas nécessaire. Pour appréhender le panorama global, seuls grep et iconv sur du texte suffisent, et même au stade où l’on approfondit une API donnée, ce qu’on lit est surtout les commentaires d’en-tête et l’historique des modifications. Aucune connaissance métier de l’administration médicale n’est présupposée non plus.

Sommaire

1. La conclusion, d’abord
2. Prérequis ── obtenir les sources et figer la version
3. Le mécanisme de dispatch de l’API ── l’URL est déterminée par lddef
4. Découverte : l’API est « la version API des écrans métier » ── bind et bindapi
5. Suivre une API jusqu’au bout ── anatomie de patientgetv2
6. Dénombrer tous les points de terminaison ── la procédure d’investigation en un grep
7. Confronter avec la liste officielle ── des exemples d’API absentes de la liste
8. Dériver la spécification d’une API non documentée à partir du code source ── l’exemple de findv3
9. Mesurer l’évolution de l’API par un diff entre versions ── branche 5.1 contre branche 5.2
10. Comment traiter les API non documentées ── la « documentation » n’est pas une garantie
11. Notes pratiques pour l’investigation approfondie
12. Conclusion
13. Annexe : tableau de correspondance des 137 points de terminaison (édition 5.2, juillet 2026)
14. Références

1. La conclusion, d’abord

• La correspondance entre les URL de l’API 日レセ et les programmes côté serveur est écrite de façon déclarative dans les fichiers lddef/*.ld (fichiers de définition LD) du code source. Sans même lire le COBOL, un simple grep sur du texte suffit à dresser le panorama complet de l’API.
• Dans l’instantané de la branche 5.2, 27 définitions LD regroupent au total 137 points de terminaison via bindapi. La page officielle listant les spécifications de l’API n’en présente qu’environ 50, ce qui signifie que le code source contient plus de deux fois plus de points de terminaison réels que la liste officielle.
• La structure des requêtes et réponses XML est déclarée dans record/*.db, et les noms de balises XML reprennent directement les noms de champs de la définition. Autrement dit, même pour une API non documentée, il est possible de dériver la spécification en suivant le chemin lddef → cobol → record.
• En prenant le diff avec la branche 5.1, on observe 9 points de terminaison ajoutés, 0 supprimé. Les ajouts se concentrent autour de la vérification d’éligibilité en ligne (マイナ保険証), ce qui permet de constater concrètement que « l’API grandit avec les évolutions réglementaires, et l’existant ne disparaît pas (du moins entre ces deux branches) ».
• Une API non documentée n’est pas une « API qu’il ne faut pas utiliser ». ORCA étant open source, le code source lui-même peut être traité comme spécification de première main. La question n’est pas l’existence ou non d’un engagement contractuel, mais « peut-on se doter d’une organisation capable de détecter soi-même les changements ? » ── le cadre pour poser ce jugement est développé au chapitre 10.

2. Prérequis ── obtenir les sources et figer la version

Les sources peuvent être téléchargées sous forme d’archive tar (zip) depuis la page officielle d’information technique. Elles sont mises à jour le 1er de chaque mois avec l’instantané au 1er du mois précédent, si bien que toute constatation issue de l’investigation doit impérativement être consignée avec sa version ── c’est une règle absolue. Cet article utilise les versions suivantes.

• Source : https://ftp.orca.med.or.jp/pub/src/jma-receipt.r_5_2_branch.zip (ainsi que r_5_1_branch.zip à titre de comparaison)
• Date d’obtention : 17 juillet 2026 (les deux sont des instantanés au 1er juillet 2026)
• Fichier VERSION de la branche 5.2 : 5.2.0

Si vous voulez mettre la main à la pâte, voici la procédure minimale. Les commandes des chapitres suivants s’exécutent toutes depuis le répertoire d’extraction.

# Choisir un répertoire de travail et récupérer/extraire l'instantané de la branche 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

# Enregistrement de la version. Ces deux éléments doivent toujours figurer dans les notes d'investigation
sha256sum jma-receipt.r_5_2_branch.zip
cat jma-receipt.r_5_2_branch/VERSION      # → 5.2.0

# Les commandes suivantes s'exécutent à l'intérieur de ce répertoire
cd jma-receipt.r_5_2_branch
ls lddef/ | head

En remplaçant r_5_2_branch par r_5_1_branch dans l’URL, vous pouvez extraire la branche 5.1 de comparaison selon la même procédure, ce qui permettra d’exécuter directement le diff du chapitre 9.

Une fois extraites, les sources comptent environ 8 200 fichiers pour 237 Mo. Cet article utilise principalement les trois répertoires suivants.

3. Le mécanisme de dispatch de l’API ── l’URL est déterminée par lddef

Avant d’entrer dans le vif du sujet, récapitulons le vocabulaire utilisé à partir de ce chapitre. Ce sont tous des termes propres à ORCA, mais il suffit d’en retenir cinq.

L’URL de l’API 日レセ suit une structure à deux niveaux, « nom du module / nom du point de terminaison », comme dans /api01rv2/patientgetv2. Cette correspondance apparaît directement dans les fichiers de définition LD de lddef/.

Regardons le début de lddef/api01rv2.ld.

name	api01rv2;

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

La lecture est directe : le nom LD est le premier segment de l’URL, le premier argument de bindapi est le second segment, et le troisième argument est le nom du programme COBOL responsable du traitement. Autrement dit, une requête vers /api01rv2/patientgetv2 est transmise au programme COBOL ORAPI012R1V2.

flowchart LR
    C["Système partenaire<br/>dossier médical électronique, etc."] -->|"GET /api01rv2/patientgetv2?id=numéro de patient"| M["Serveur 日レセ<br/>MONTSUQI"]
    M -->|"lddef/api01rv2.ld<br/>consultation de la définition bindapi"| P["ORAPI012R1V2.CBL<br/>Récupération des informations de base du patient"]
    P --> D[("PostgreSQL")]
    P -->|"Réponse XML"| C

Une définition LD déclare aussi, entre autres, l’ensemble des enregistrements XML utilisés pour construire la réponse (db "xml2" { ... }), ainsi que des réglages pratiques à connaître (comme les tailles de tableau). Un fichier LD peut se lire comme « le sommaire des écrans, API et structures de données que gère ce module ».

4. Découverte : l’API est « la version API des écrans métier » ── bind et bindapi

En parcourant les définitions LD, on remarque tout de suite quelque chose : bind (écran) et bindapi (API) cohabitent dans le même fichier. Regardons le module de consultation patient lddef/orca13.ld.

name	orca13;

bind	"Q01"		"OpenCOBOL"	"ORCGQ01";     ← écran interactif de consultation patient
bind	"Q02"		"OpenCOBOL"	"ORCGQ02";
...
bindapi "findv3"    "OpenCOBOL"	"ORCGQAPI01";  ← sa version API
bindapi "findinfv3" "OpenCOBOL"	"ORCGQAPI02";
bindapi "foundv3"   "OpenCOBOL"	"ORCGQAPI03";

Q01 et suivants sont les programmes de l’écran de consultation patient manipulé par le personnel administratif, tandis que findv3 et suivants sont les API appartenant au même module. Même les noms de programme reflètent cette relation : au nom de l’écran ORCGQ01 répond le nom ORCGQAPI01 de l’API, où « API » vient s’insérer dans le nom de la version écran.

Autrement dit, l’API 日レセ n’a pas été conçue comme un serveur d’API indépendant, mais comme une addition, module métier par module métier, d’une « porte d’entrée qui dialogue en XML à la place de l’écran », sur la même base de programmes métier interactifs. Une fois cette structure comprise, deux choses deviennent naturelles :

• pourquoi le premier segment de l’URL (orca13, orca42…) provient du numéro de business de l’écran, et paraît à première vue un chiffre sans signification pour une API ;
• pourquoi la démarche de recherche « un travail réalisable à l’écran a peut-être une version API » est valide ── chercher des API non documentées revient en réalité à énumérer ces « versions API des écrans métier ».

5. Suivre une API jusqu’au bout ── anatomie de patientgetv2

Avant de dénombrer le panorama global, suivons une API de son implémentation jusqu’à la forme de sa réponse. Le sujet est l’API la plus élémentaire, la récupération des informations de base du patient, /api01rv2/patientgetv2.

(1) Dispatch : dans lddef/api01rv2.ld, bindapi "patientgetv2" → ORAPI012R1V2. L’implémentation se trouve dans cobol/api01rv2/ORAPI012R1V2.CBL (2 163 lignes). En principe, le code source COBOL est placé dans le répertoire portant le même nom que la définition LD, si bien que, une fois lddef lu, le fichier d’implémentation peut se retrouver de façon quasi mécanique (il existe des exceptions ; par exemple, l’implémentation des API du groupe orca51 se trouve dans cobol/orca52/. Le moyen sûr reste un find sur le nom du programme).

(2) En-tête du programme : au début figure « Nom du composant : Récupération des informations de base du patient (compatible version2) », et l’historique des modifications qui suit fait défiler comme une frise chronologique les évolutions réglementaires subies par cette seule API, depuis la prise en charge des identifiants de coopération régionale en 2013, jusqu’au support de l’ordonnance électronique en 2022, en passant par le « retour de la validité de l’assurance via carte d’assurance » en 2024. C’est plus détaillé que la section « historique des mises à jour » d’une spécification d’API.

(3) Ce qui est lu : en regardant les clauses COPY (définitions communes importées) de la WORKING-STORAGE SECTION, on voit quelles données cette API manipule. Extrait :

COPY "CPPTINF.INC".          *> Informations de base du patient (tbl_ptinf)
COPY "CPPTNUM.INC".          *> Numéro de patient
COPY "CPJYURRK.INC".         *> Historique des soins reçus
COPY "CPPTCARE-HKNINF.INC".  *> Informations d'assurance dépendance
COPY "CPPTMYNUMBER.INC".     *> Numéro personnel du patient (My Number)
COPY "CPONSHI-KAKU.INC".     *> Résultat de vérification d'éligibilité en ligne
COPY "CPPATIENTXMLV2RES.INC" *> Édition de la réponse

Une API qui se contente de renvoyer un patient importe près de trente définitions, jusqu’à l’assurance dépendance, le My Number et la vérification d’éligibilité en ligne. C’est la preuve matérielle que la notion d’« informations de base du patient » n’a cessé de s’étoffer au fil des évolutions réglementaires.

(4) La forme de la réponse : la structure de la réponse XML est déclarée dans 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);
                ...

Quiconque a déjà utilisé l’API 日レセ y reconnaîtra quelque chose. Les noms de balises XML de la réponse d’API (Patient_ID, WholeName…) reprennent directement les noms de champs de cette définition record. Autrement dit, l’« original » du tableau des champs figurant dans la spécification XML officielle se trouve ici. La taille (nombre de chiffres) des champs y est même indiquée, ce qui en fait aussi une source de première main pour la conception de la validation côté intégration.

Cette séquence (1) → (4) constitue le gabarit d’anatomie d’une API 日レセ : identifier le programme via lddef, saisir la fonctionnalité et l’historique via l’en-tête, comprendre les données manipulées via les clauses COPY, et fixer la structure du message via record/*.db ── sans même avoir à lire la logique du corps COBOL, on obtient déjà la majeure partie de l’information nécessaire à un usage pratique.

6. Dénombrer tous les points de terminaison ── la procédure d’investigation en un grep

Une fois le mécanisme compris, l’énumération complète devient un travail mécanique.

# Énumérer toute la correspondance point de terminaison → programme COBOL
grep -H '^[[:space:]]*bindapi' lddef/*.ld

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

# Extraire mécaniquement le nom de fonctionnalité de chaque point de terminaison depuis l'en-tête COBOL
# (les sources sont en EUC-JP, d'où le passage par iconv ; l'emplacement du programme
#  connaît des exceptions par rapport au nom LD, d'où l'identification par 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

Le troisième script étant long, décomposons ce que fait chaque étage du pipeline.

1. grep '^[[:space:]]*bindapi' "$ld" ── extrait uniquement les lignes de déclaration d’API de la définition LD
2. sed 's/"//g; s/;//' ── retire les guillemets et le point-virgule final, pour obtenir 4 mots séparés par des espaces (bindapi / nom de point de terminaison / OpenCOBOL / nom de programme)
3. while read -r _ ep _ prog ── ignore le 1er et le 3ᵉ mot, ne récupère que le nom de point de terminaison et le nom de programme
4. find cobol -name "$prog.CBL" ── recherche l’implémentation réelle du programme. Comme le nom LD et le nom de répertoire ne coïncident pas toujours, on évite de fixer le chemin en dur
5. iconv -f EUC-JP -t UTF-8 ── les sources COBOL étant en EUC-JP, cette conversion est nécessaire pour lire les commentaires d’en-tête en japonais
6. grep -m1 'コンポーネント名' | sed … ── récupère la seule première ligne « nom du composant » de l’en-tête, et en extrait ce qui suit les deux-points (le nom de fonctionnalité)

Une fois exécuté, le résultat s’affiche en 4 colonnes séparées par des tabulations : « module / point de terminaison / programme / nom de fonctionnalité ». Les 6 premières lignes sont les suivantes.

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

Au total, on obtient 137 lignes. Les espaces doublés, comme dans « 予約一覧 (xml2）» à la 3ᵉ ligne, ou le mélange de parenthèses pleine chasse et demi-chasse, sont dus au fait que le contenu de l’en-tête est extrait tel quel. Le tableau de correspondance de l’annexe, qui présente ce résultat mis en forme, conserve lui aussi la transcription à l’identique (chapitre 13).

Voici le résultat de ce dénombrement pour cette version (le détail des 137 entrées figure en annexe) :

Alors qu’environ 40 % des API sont concentrées dans la lecture (api01rv2), les API de mise à jour se répartissent par module métier (patient = orca12, accueil = orca11, actes médicaux = api21…). La structure de « version API des écrans métier » vue au chapitre 4 se retrouve directement dans cette distribution.

Un autre point à noter : on trouve mêlées des fonctions de socle plutôt qu’à proprement parler métier, comme session_start (authentification de connexion) du module session, ou print (impression) du module orca00. Aussi longtemps qu’on parcourt la liste des spécifications officielles, on ne peut pas percevoir l’existence de cette couche.

Les points de terminaison individuels figurent dans le tableau de correspondance des 137 entrées en annexe. En repérant, à partir du tableau ci-dessus, le module visé selon le nombre d’entrées, puis en cherchant par nom de module dans l’annexe, on suit la démarche de recherche de base.

7. Confronter avec la liste officielle ── des exemples d’API absentes de la liste

Confrontons maintenant les API listées sur la page officielle « Spécification de l’API 日医標準レセプトソフト » (environ 50 entrées) aux 137 extraites du code source. On constate alors que de nombreux points de terminaison absents de la liste officielle existent réellement côté source. Voici des exemples par domaine fonctionnel (les noms de fonctionnalité sont tous confirmés à partir du « nom du composant » de l’en-tête COBOL).

Autrement dit, il existe, en tant qu’implémentation, un ensemble d’API capables de piloter depuis l’extérieur le traitement mensuel des feuilles de soins (création → vérification → production des données électroniques → gestion de facturation), et pas seulement l’accueil ou l’information patient au quotidien. C’est une couche invisible si l’on ne connaît que l’intégration au dossier médical électronique.

Deux mises en garde importantes s’imposent ici.

1. Ne pas conclure hâtivement qu’« absent de la liste » signifie « non documenté ». Par exemple, la récupération de données de formulaire (formdatagetv2) est documentée côté documentation de l’API Push, et la page de liste ne garantit pas l’exhaustivité de toutes les API. Il convient de vérifier aussi les pages de documentation individuelles et la recherche sur le site avant d’affirmer qu’« aucune documentation n’a été trouvée » (le tableau ci-dessus est le résultat de cette vérification, mais cela ne constitue pas pour autant une preuve complète de l’absence de toute documentation publiée).
2. Les implémentations tierces peuvent aussi servir de matériau de comparaison. Un projet open source comme la bibliothèque orca-api, qui permet d’utiliser l’API 日レセ depuis Ruby, constitue une référence utile en tant que catalogue de points de terminaison réellement utilisés en pratique.

8. Dériver la spécification d’une API non documentée à partir du code source ── l’exemple de findv3

Savoir qu’« il existe des API absentes de la liste » ne permet pas d’enquêter tant qu’on ignore la forme de la requête. C’est là que le gabarit du chapitre 5 devient efficace. Essayons avec findv3 (consultation patient).

La structure de la requête se trouve dans record/xml_findv3req.db (extrait).

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

Rien qu’en lisant cette définition, on comprend qu’il s’agit d’une API de recherche de patient assez sophistiquée, permettant de combiner plage de date de naissance, sexe, plage de dernière date de visite, médecin traitant, service, catégorie de décès, plage de numéro de patient, plusieurs noms possibles, etc. Les API de recherche patient listées officiellement (patientlst1v2 et suivants) sont surtout centrées sur des recherches à critère unique comme la plage de numéro de patient ou le nom, si bien que cette API, capable d’une recherche multicritère équivalente à l’écran de consultation patient, en est fonctionnellement une évolution nettement supérieure.

La structure de la réponse se trouve de la même façon dans record/xml_findv3res.db, et en lisant le COBOL correspondant (ORCGQAPI01.CBL), on peut aussi vérifier des comportements fins (limite du nombre de résultats, ordre de tri, etc.). Une « API non documentée » est, pour ORCA dont le code source est public, une « API dont on peut rédiger soi-même la documentation ».

Jusqu’où faire confiance, en production, à une spécification ainsi dérivée ── c’est le thème du chapitre suivant.

9. Mesurer l’évolution de l’API par un diff entre versions ── branche 5.1 contre branche 5.2

Avant de discuter du risque des API non documentées, mesurons concrètement « à quel point une API change ». Voici le résultat du diff des définitions bindapi entre l’instantané de la branche 5.1 publié le même jour et la branche 5.2 :

Le détail des 9 ajouts se compose de 6 points liés à la vérification d’éligibilité en ligne (onlinequa10, onlinequa11, onlinequaapp1 à 3, onlineaidlstreq1), de l’enregistrement de note patient (patientmemomodv2), du retour groupé des codes de saisie (inputcodelstv3), et de la récupération des informations de code de saisie et de consultation (medicationgetv2), soit 9 entrées en tout. On voit clairement que les évolutions réglementaires (autour de マイナ保険証) se traduisent par des ajouts d’API.

Cette observation permet deux constats :

• la « surface » des points de terminaison est stable (zéro suppression entre ces deux branches) ; ce qu’il faut craindre n’est pas tant leur disparition que l’ajout de champs et le changement de comportement d’une API donnée (des changements du type de ceux observés dans l’historique de modifications au chapitre 5) ;
• comme les sources sont publiées chaque mois, ce type de détection de changement peut être automatisé. Pour quiconque maintient un système d’intégration, un simple diff mensuel des lddef et record de l’instantané suffit à constituer un réseau d’alerte précoce sur ce qui va changer à la prochaine mise à jour de version. C’est un moyen de maintenance rare, propre à la publication du code source, difficile à obtenir avec d’autres logiciels de facturation médicale.

10. Comment traiter les API non documentées ── la « documentation » n’est pas une garantie

Commençons par établir le bon cadre. Le contrat de licence d’utilisation open source de 日医 (l’Association médicale du Japon, éditrice d’ORCA) stipule, à l’article 5 du chapitre 2, une absence de garantie pour l’ensemble du programme, concernant le bon fonctionnement ou l’absence de défaut. Cela s’applique de manière égale aux API documentées. Il n’existe pas non plus, dans les documents officiels, de clause explicite promettant de « ne pas changer » les API documentées en matière de compatibilité ; d’ailleurs, comme on l’a vu au chapitre 5, même patientgetv2, pourtant représentative des API documentées, a continué de voir ses champs s’ajouter à chaque évolution réglementaire.

Autrement dit, la différence entre « documenté » et « non documenté » ne porte pas sur l’existence d’une garantie. La différence réelle se résume, en creusant, à ces deux points seulement :

1. la probabilité que le changement apparaisse comme une mise à jour de la documentation officielle (un changement sur une API non documentée reste invisible tant qu’on ne lit pas le code source) ;
2. la facilité à en discuter avec le prestataire de support.

Or, chez ORCA, le code source est publié chaque mois. Le premier écart peut être comblé par une surveillance des diffs du code source. C’est le code source qui constitue la spécification de première main ; la documentation n’en est qu’une traduction abrégée ── c’est la bonne posture à adopter face à l’open source. Quand la documentation et le code source se contredisent, c’est le code source qui s’exécute réellement.

Cela étant posé, dès lors qu’on manipule un système de facturation médicale directement lié à de l’argent, qu’une API soit documentée ou non, il faut associer les pratiques opérationnelles suivantes à toute API intégrée dans un flux de production.

Une précaution opérationnelle : l’instantané public correspond au 1er du mois précédent, si bien que si l’on applique d’abord la mise à jour du paquet en production, on ne peut lire le code source correspondant qu’après coup. Pour que cette surveillance fonctionne comme une véritable alerte précoce, il faut inverser l’ordre : attendre la publication et la validation du code source correspondant avant de procéder à la mise à jour de version.

Inversement, une organisation incapable de mettre en place ce type de pratique n’est pas plus en sécurité en n’utilisant que des API documentées. Confier un socle métier à un logiciel open source sans garantie, c’est précisément cela.

11. Notes pratiques pour l’investigation approfondie

Voici quelques écueils fins qu’on rencontre au stade où l’on approfondit une API donnée dans le code source.

• L’encodage des caractères est l’EUC-JP. Les sources et commentaires COBOL étant en EUC-JP, il faut passer par iconv -f EUC-JP -t UTF-8 avant de les lire. Le document de licence (doc/license.html) est en ISO-2022-JP. Même grep ne trouvera aucun mot-clé japonais sans passer par iconv.
• Retenir la convention de nommage des programmes accélère la lecture. Pour les API, la forme de base est ORAPI + numéro de business + R (lecture)/S (mise à jour) + version (V2/V3) ; pour la version API des écrans, c’est ORCG〜API〜. Le code source COBOL se trouve en principe dans cobol/<nom LD>/, mais il existe des exceptions (l’implémentation des API de orca51 se trouve dans cobol/orca52/), donc en cas de doute, faites un find sur le nom du programme.
• Le sens des champs de données se confirme en croisant record/ et le tableau officiel de définition des tables. L’« original » des champs de réponse se trouve dans record/*.db, et le sens côté base de données dans le tableau de définition des tables publié officiellement. Croiser les deux augmente la fiabilité. Notez qu’une partie des définitions coexiste avec une version .db.weborca pour WebORCA, dont les limites de tableau diffèrent (par exemple, xml_acceptlstv2res passe de 1 000 à 1 500 entrées). Pour une conception d’intégration WebORCA, vérifiez cette version.
• Vérifiez le fonctionnement en environnement de test. Le serveur d’essai officiel ou un environnement Docker communautaire permettent d’interroger l’API et de vérifier son comportement sans toucher à la machine de production. « Tester en direct » sur la machine de production est à proscrire absolument.

12. Conclusion

• Le panorama complet de l’API 日レセ est concentré dans les définitions bindapi de lddef/*.ld : un simple grep suffit à énumérer 137 points de terminaison (branche 5.2, édition juillet 2026).
• La véritable nature de l’API 日レセ est celle d’une « version API des écrans métier ». bind (écran) et bindapi (API) cohabitent dans la même définition LD, et le nom de module de l’URL provient du numéro de business de l’écran.
• Une API se dissèque dans l’ordre lddef (dispatch) → en-tête COBOL (fonctionnalité, historique) → clauses COPY (données manipulées) → record/*.db (original de la structure XML). Le nom de balise XML est exactement le nom de champ de la définition record.
• L’écart entre la liste officielle (environ 50 entrées) et le code source (137 entrées) inclut un ensemble d’API capables de piloter le traitement mensuel ── création de feuille de soins, production de données électroniques, vérification des données. Mais il ne faut pas conclure hâtivement qu’« absent de la liste » équivaut à « non documenté » : chaque cas doit être vérifié individuellement.
• La mesure réelle du diff avec la branche 5.1 montre 9 ajouts (majoritairement liés à la vérification d’éligibilité en ligne), 0 suppression. Le diff de l’instantané mensuel peut servir de réseau d’alerte précoce pour la maintenance d’une intégration.
• Le contrat de licence d’utilisation stipule explicitement une absence de garantie, y compris pour les API documentées : « documenté » ne signifie pas « sûr ». C’est le code source qui constitue la spécification de première main. Que l’API soit documentée ou non, un usage en production doit associer figeage de version, surveillance mensuelle des diffs, validation de non-régression, et tenue d’une documentation maison.

Cet ordre consistant à entrer par le code source plutôt que par la spécification est une méthode d’investigation qui, au-delà d’ORCA, s’applique à tout « système métier de longue durée dont la documentation n’a pas suivi l’implémentation ». Par chance, le code source d’ORCA est public, ce qui permet de pratiquer cette méthode en toute légalité, et qui plus est, avec un état à jour chaque mois.

13. Annexe : tableau de correspondance des 137 points de terminaison (édition 5.2, juillet 2026)

Voici l’ensemble des points de terminaison extraits mécaniquement des définitions bindapi de lddef/*.ld. Les noms de fonctionnalité sont notre traduction française du champ « nom du composant » de l’en-tête de chaque programme COBOL. Le texte japonais source transcrit ce champ tel quel, y compris ses variations orthographiques, ses parenthèses pleine chasse et ses fautes de frappe apparentes (des éléments comme « 請求額シュミレーション » au lieu de シミュレーション, ou medicatonmodv2 au lieu de medicationmodv2, ne sont pas des erreurs de notre part mais des particularités du code source d’origine). Ce tableau est un relevé factuel de l’instantané de la branche 5.2 au 1ᵉʳ juillet 2026 ; il n’indique ni la possibilité d’utilisation ni le statut de support de chaque point de terminaison.

Le tableau est trié par module (premier segment de l’URL). Pour retrouver rapidement une API donnée, affinez la recherche dans cet ordre. La recherche dans la page du navigateur (Ctrl+F) sur le nom de module vous amène directement au début du bloc correspondant.

14. Références

• Informations techniques - 日医標準レセプトソフト - ORCA Project (publication du code source)
• Spécification de l’API 日医標準レセプトソフト - ORCA Project
• API 日医標準レセプトソフト - ORCA Project
• orca-api : bibliothèque Ruby pour l’API 日医標準レセプトソフト (GitHub)
• Code source du 日レセ, branches 5.2 et 5.1 (instantanés publiés en juillet 2026) lddef/api01rv2.ld / lddef/orca13.ld / cobol/api01rv2/ORAPI012R1V2.CBL / record/xml_patientinfov2res.db / record/xml_findv3req.db et autres ── toutes les valeurs mesurées et citations du corps de l’article reposent sur cet instantané

Articles associés

Articles récents partageant les mêmes étiquettes, pour approfondir des sujets proches.

Sujets associés

Ces pages replacent le sujet dans un contexte plus large de services et de décisions.

Services liés à ce sujet

Cet article est directement lié aux services suivants.

Questions fréquentes

Questions souvent posées lors d’une consultation sur le sujet de cet article.

Combien de points de terminaison compte au total l'API 日レセ ?

La page officielle listant les spécifications de l'API en recense environ 50, mais si l'on compte les fichiers de définition LD du code source public (branche 5.2, instantané de juillet 2026), le nombre de points de terminaison regroupés sous bindapi s'élève à 137. Cet écart inclut des cas comme les API de formulaires imprimés, qui sont documentées ailleurs, si bien qu'on ne peut pas conclure hâtivement qu'« absent de la liste » équivaut à « non documenté ». Mais en comptant directement dans le code source, on obtient un panorama complet de l'API en tant qu'information de première main. Cet article présente le tableau de correspondance des 137 points de terminaison.

Peut-on utiliser en production une API absente de la documentation officielle ?

Oui. Le code source d'ORCA est public, ce qui permet de consulter l'implémentation elle-même comme spécification de première main. Le contrat de licence d'utilisation stipule d'ailleurs explicitement une absence de garantie pour l'ensemble du programme, y compris les API documentées : le postulat selon lequel « documenté = sûr » est donc erroné en soi. L'écart réel entre documenté et non documenté se résume à deux points : la probabilité que les changements apparaissent dans la documentation officielle, et la facilité à en discuter avec le prestataire de support. Le premier point peut être comblé par une surveillance des diffs sur les sources publiées mensuellement, mais le second (les API non documentées entrent difficilement dans le périmètre du support) subsiste. Pour un usage en production, associez toujours le figeage de version, la surveillance des diffs, la validation de non-régression en environnement de test, la tenue d'une documentation maison et le partage de la configuration avec le prestataire de support. Ceci vaut d'ailleurs tout autant pour les API documentées.

Le format des requêtes et réponses de l'API est-il lui aussi lisible dans le code source ?

Oui. La structure des requêtes et réponses XML de 日レセ est écrite de façon déclarative dans les fichiers de définition du répertoire record/ (par exemple record/xml_patientinfov2res.db), et les noms de balises XML reprennent directement les noms de champs de cette définition. Même pour une API non documentée, il suffit d'identifier le programme responsable à partir de la définition LD, puis de lire la définition record correspondante, pour dériver l'ensemble des champs de la requête et de la réponse.

Peut-on mener cette investigation sans savoir lire le COBOL ?

Pour se contenter d'appréhender le panorama global des points de terminaison, la lecture du COBOL n'est quasiment pas nécessaire. Les fichiers de définition LD (lddef/*.ld) et les définitions de structure de données (record/*.db) sont du texte, et la correspondance entre URL, programme et structure XML y est écrite de façon déclarative. Ce n'est qu'au stade où l'on veut approfondir le comportement interne d'une API donnée que la lecture du COBOL devient nécessaire, mais même à ce stade, les commentaires d'en-tête de programme (en japonais) et l'historique des modifications suffisent à obtenir une grande partie de l'information.

Profil de l’auteur

Page de présentation de l’auteur de l’article.

Go Komura

Représentant de KomuraSoft LLC

Spécialisé dans le développement de logiciels Windows, le conseil technique et l’analyse de pannes, notamment pour les systèmes existants et les incidents difficiles à reproduire.