Grasping the Whole Nichi-Rece API from the Source Code — Reading ORCA's Published Source (with a Mapping Table of All 137 Endpoints)

In the previous article we established that ORCA (the JMA Standard Receipt Software) is a medical billing system, and that its source code has been published continuously for more than twenty years.

This time we actually read that source code. The theme is grasping the whole Nichi-Rece API from primary information. Rather than reading the official API specification top to bottom, we will:

1. enumerate every endpoint that actually exists on the server from the source,
2. follow one API from implementation through to the shape of its response XML,
3. cross-check against the official documentation and verify the differences, and
4. measure API change with a cross-version diff.

At the end of the article you will find a mapping table of all 137 endpoints (URL, COBOL program, function) obtained in this investigation.

The subject of this investigation is the officially published Nichi-Rece 5.2 series source (the snapshot published on 1 July 2026), with the 5.1 series (published the same day) used for comparison. Everything here is based on those two releases, and the commands needed to reproduce the results are given in the text.

Table of Contents

1. The Bottom Line First
2. Prerequisites — Obtaining the Source and Pinning the Version
3. How API Dispatch Works — The URL Is Determined by lddef
4. A Discovery: the APIs Are “the API Editions of Screen-Based Workflows” — bind and bindapi
5. Following One API All the Way — Dissecting patientgetv2
6. Counting Every Endpoint — A One-grep Investigation Procedure
7. Cross-checking Against the Official List — Examples of APIs That Are Not on It
8. Deriving the Specification of an Undocumented API from the Source — The findv3 Case
9. Measuring API Change with a Cross-version Diff — 5.1 Series vs 5.2 Series
10. How to Live with Undocumented APIs — “Documented” Is Not a Guarantee
11. Practical Notes for Digging Deeper
12. Summary
13. Appendix: Mapping Table of All 137 Endpoints (5.2 Series, July 2026)
14. References

1. The Bottom Line First

• The mapping between Nichi-Rece API URLs and server-side programs is declared in the source in lddef/*.ld (the LD definition files). You can enumerate the whole API surface with nothing but a text grep — no COBOL reading required.
• In the 5.2 series snapshot, 27 LD definitions bind a total of 137 endpoints with bindapi. The API specification index page on the official site lists roughly 50, meaning more than twice that number of endpoints actually exist on the source side.
• The structure of the XML requests and responses is declared in record/*.db, and the XML tag names are the item names in those definitions verbatim. So even for an undocumented API, following lddef → cobol → record lets you derive the specification.
• Diffing against the 5.1 series shows 9 endpoints added and 0 removed. The additions are concentrated in online eligibility verification (My Number health insurance card) work, giving a measured demonstration that “APIs grow through regulatory work, and existing ones have not disappeared (at least between these two series)”.
• An undocumented API is not an API you must not use. ORCA is open source, and the source itself can be treated as the primary specification. The question is not whether a promise exists but whether you can operate a practice that detects changes yourself — a framework for that judgement is set out in Section 10.

2. Prerequisites — Obtaining the Source and Pinning the Version

The source can be downloaded as a tarball (zip) from the official technical information page. It is refreshed on the first of every month to a snapshot as of the first of the previous month, so the cardinal rule is to always record investigation results together with the release they came from. This article uses the following.

• Source: https://ftp.orca.med.or.jp/pub/src/jma-receipt.r_5_2_branch.zip (plus r_5_1_branch.zip for comparison)
• Retrieved: 2026-07-17 (both are snapshots as of 1 July 2026)
• VERSION file of the 5.2 series: 5.2.0

Extracted, it comes to about 8,200 files and 237 MB, and this article mainly uses the following three directories.

3. How API Dispatch Works — The URL Is Determined by lddef

Nichi-Rece API URLs are two-segment, of the form “module name/endpoint name”, as in /api01rv2/patientgetv2. That mapping appears directly in the LD definition files under lddef/.

Here is the top of lddef/api01rv2.ld.

name	api01rv2;

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

Reading it is straightforward: the LD name is the first URL segment, the first argument of bindapi is the second segment, and the third argument is the name of the COBOL program that handles the request. So a request to /api01rv2/patientgetv2 is passed to a COBOL program called ORAPI012R1V2.

flowchart LR
    C["Integrating system<br/>e.g. electronic medical record"] -->|"GET /api01rv2/patientgetv2?id=patient number"| M["Nichi-Rece server<br/>MONTSUQI"]
    M -->|"lddef/api01rv2.ld<br/>consults the bindapi definition"| P["ORAPI012R1V2.CBL<br/>get patient master data"]
    P --> D[("PostgreSQL")]
    P -->|"XML response"| C

LD definitions also declare the XML record set used to assemble responses (db "xml2" { ... }) and some settings worth knowing about (array sizes and so on). An LD file can be read as “a table of contents of the screens, APIs, and data structures that module handles”.

4. A Discovery: the APIs Are “the API Editions of Screen-Based Workflows” — bind and bindapi

Look at the LD definitions for a while and something becomes obvious at once: bind (screens) and bindapi (APIs) coexist in the same file. Here is the patient enquiry module, lddef/orca13.ld.

name	orca13;

bind	"Q01"		"OpenCOBOL"	"ORCGQ01";     ← the interactive patient enquiry screen
bind	"Q02"		"OpenCOBOL"	"ORCGQ02";
...
bindapi "findv3"    "OpenCOBOL"	"ORCGQAPI01";  ← its API edition
bindapi "findinfv3" "OpenCOBOL"	"ORCGQAPI02";
bindapi "foundv3"   "OpenCOBOL"	"ORCGQAPI03";

Q01 and its siblings are the programs behind the patient enquiry screens that medical affairs staff operate; findv3 and its siblings are APIs belonging to the very same module. Even the program names follow suit: ORCGQ01 (screen) versus ORCGQAPI01 (API) — the screen-side name with “API” inserted into it.

In other words, the Nichi-Rece API was not designed as a standalone API server. It is an “entry point that converses in XML instead of via a screen”, added module by module on top of the same business program platform as the interactive screens. Once you see this structure, two things follow naturally.

• Why the first URL segment (orca13, orca42, …) derives from the business number of a screen, and looks like a meaningless number from an API point of view.
• Why the search strategy “if you can do it on a screen, an API edition may exist” works — hunting for undocumented APIs is in fact close to enumerating these “API editions of screen-based workflows”.

5. Following One API All the Way — Dissecting patientgetv2

Before counting the whole set, let us follow one API from implementation through to the shape of its response. The subject is the most basic of them all, patient master data retrieval: /api01rv2/patientgetv2.

(1) Dispatch: bindapi "patientgetv2" → ORAPI012R1V2 in lddef/api01rv2.ld. The implementation is cobol/api01rv2/ORAPI012R1V2.CBL (2,163 lines). As a rule COBOL sources sit in a directory named after the LD, so if you can read lddef you can identify the implementation file almost mechanically (there are exceptions — for instance the implementations of the orca51 APIs live in cobol/orca52/; the reliable route is to find by program name).

(2) The program header: at the top it reads “Component name: patient master data retrieval (version 2 support)”, and the revision history that follows lines up, as a chronology, every regulatory revision this single API has absorbed — from regional integration ID support in 2013, through electronic prescription support in 2022, to “returning eligibility validity from the insurance card” in 2024. It is more detailed than the “update history” in the API specification.

(3) What it reads: the COPY clauses in the WORKING-STORAGE SECTION (the shared definitions it pulls in) tell you what data this API touches. An excerpt:

COPY "CPPTINF.INC".          *> patient master data (tbl_ptinf)
COPY "CPPTNUM.INC".          *> patient number
COPY "CPJYURRK.INC".         *> treatment history
COPY "CPPTCARE-HKNINF.INC".  *> long-term care insurance information
COPY "CPPTMYNUMBER.INC".     *> patient My Number
COPY "CPONSHI-KAKU.INC".     *> online eligibility verification result
COPY "CPPATIENTXMLV2RES.INC" *> response formatting

An API that merely returns one patient pulls in close to thirty definitions, reaching as far as long-term care insurance, My Number, and online eligibility verification. It is material evidence that the meaning of “patient master data” has kept expanding alongside the regulations.

(4) The shape of the response: the structure of the response XML is declared in 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);
                ...

If you have used the Nichi-Rece API before, this should look familiar. The XML tag names in API responses (Patient_ID, WholeName, …) are the item names in this record definition verbatim. That is to say, the “original” of the field tables in the official XML specification is right here. Field sizes (digit counts) are written down too, so it also serves as primary information for designing validation on the integrating side.

Steps (1) to (4) are the template for dissecting a single Nichi-Rece API. Identify the program from lddef, get the function and history from the header, learn what data it touches from the COPY clauses, and pin down the message structure from record — without reading the COBOL logic itself, that gets you most of the information you need in practice.

6. Counting Every Endpoint — A One-grep Investigation Procedure

Once you understand the mechanism, enumerating the whole set is mechanical work.

# Enumerate every endpoint → COBOL program mapping
grep -H '^[[:space:]]*bindapi' lddef/*.ld

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

# Mechanically extract the function name of each endpoint from the COBOL header
# (the source is EUC-JP, so pipe it through iconv. There are exceptions where the
#  program's location does not match the LD name, so locate it with 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

The totals for this release are as follows (the individual entries for all 137 are in the appendix).

About 40 per cent cluster in the read operations (api01rv2), while write operations are split by business module (patient = orca12, reception = orca11, medical procedures = api21, …). The “API editions of screen-based workflows” structure from Section 4 shows through directly in this distribution too.

Another thing worth noticing is that APIs that are platform functions rather than business functions are mixed in — session_start (login authentication) in the session module, or print in orca00. You could stare at the official specification index for as long as you like and never notice this layer exists.

7. Cross-checking Against the Official List — Examples of APIs That Are Not on It

Next, cross-check the APIs listed on the official site’s “JMA Standard Receipt Software API specification” index page (roughly 50) against the 137 extracted from the source. What emerges is that a great many endpoints exist on the source side that are not on the index page. Here are examples by functional area (all function names were confirmed from the “component name” in the COBOL header).

In other words, beyond day-to-day integration such as reception and patient information, there exists as implementation a set of APIs that can drive the monthly receipt workflow from outside (creation → checking → electronic receipt data output → billing management). It is a layer you never see if all you know is electronic medical record integration.

Two important cautions here.

1. Do not jump straight from “not on the list” to “undocumented”. Form data retrieval (formdatagetv2), for instance, is documented on the PushAPI side, and the index page does not guarantee exhaustive coverage of all APIs. You should only say “no documentation found” after checking individual documentation pages and searching the site (the table above is the result of doing exactly that, and even so it is not complete proof that no published documentation exists).
2. Third-party implementations are also useful cross-check material. OSS such as the orca-api library, which uses the Nichi-Rece API from Ruby, is a useful catalogue of the endpoints actually used in practice.

8. Deriving the Specification of an Undocumented API from the Source — The findv3 Case

Knowing that “APIs not on the list exist” gets you nowhere if you do not know the shape of the request. This is where the template from Section 5 earns its keep. Let us try it on findv3 (patient enquiry).

The request structure is in record/xml_findv3req.db (excerpt).

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

Simply reading the definition tells you this is a rather capable patient search API that can combine a date-of-birth range, sex, a last-visit-date range, attending doctor, department, deceased flag, a patient number range, and names (multiple values allowed). The patient search APIs on the official list (patientlst1v2 and friends) are mostly single-purpose searches on things like a patient number range or a name, so this API — which offers the same compound-condition search as the patient enquiry screen — is functionally a clear superset.

The response structure is likewise in record/xml_findv3res.db, and reading the corresponding COBOL (ORCGQAPI01.CBL) lets you confirm the finer behaviour (result limits, ordering, and so on). In ORCA, where the source is published, an “undocumented API” is really “an API you can write the documentation for yourself”.

How far you should trust a specification derived this way in production is the subject of the next section but one.

9. Measuring API Change with a Cross-version Diff — 5.1 Series vs 5.2 Series

Before debating the risk of undocumented APIs, let us measure how much APIs actually change. Diffing the bindapi definitions against the 5.1 series snapshot published the same day:

The nine additions break down as six related to online eligibility verification (onlinequa10, onlinequa11, onlinequaapp1 to 3, onlineaidlstreq1), plus patient memo registration (patientmemomodv2), bulk return of input codes (inputcodelstv3), and retrieval of input and procedure code information (medicationgetv2) — nine in total. You can see clearly that regulatory work (around the My Number health insurance card) manifests as new API endpoints.

Two things follow from this observation.

• The “surface” of endpoints is stable (zero removals between these two series). What to fear is not disappearance but the addition of fields to, and behavioural changes in, individual APIs — changes of the kind visible in the revision history we saw in Section 5.
• Because the source is published monthly, this kind of change detection can be automated. If you maintain an integrating system, simply diffing lddef and record between monthly snapshots gives you an early warning network for what next month’s upgrade will change. This is a maintenance capability unique to published source, and hard to come by with other medical billing systems.

10. How to Live with Undocumented APIs — “Documented” Is Not a Guarantee

First, let us get the premise right. Article 5 of Chapter 2 of the JMA OpenSource License disclaims all warranties for the program as a whole, including that it will operate without impediment and that it is free of defects. That applies equally to documented APIs. Nor is there any explicit provision in the official documents promising not to change documented APIs — and indeed, as we saw in Section 5, even patientgetv2, the poster child of documented APIs, has had fields added with every round of regulatory work.

So the difference between “documented” and “undocumented” is not the presence or absence of a guarantee. Pushed to its conclusion, the substantive difference is just these two things.

1. Whether a change is likely to surface as an update to the official documentation (changes to an undocumented API are invisible unless you read the source).
2. Whether it gives you common ground in conversations with your support provider.

And ORCA publishes its source every month. The first difference can be closed by diff monitoring of the source. The source is the primary specification; the documentation is merely an abridged translation of it — that is the correct attitude towards open source. When documentation and source disagree, it is the source that actually runs.

That said, since we are dealing with a system directly tied to money in the form of receipt claims, regardless of whether an API is documented, any API you build into a production flow should be paired with the following operational practices.

One operational caution. The published snapshot reflects the state as of the first of the previous month, so if you apply a package update to production first, you will only be able to read the corresponding source after the fact. For this monitoring to function as an early warning system, you need to bias the ordering the other way: wait for the corresponding source to be published and verified before upgrading.

Put the other way round: an organisation that cannot sustain this practice is not safe even if it only uses documented APIs. That is what it means to put unwarranted open source at the core of your business.

11. Practical Notes for Digging Deeper

Small stumbling blocks you hit at the stage of chasing an individual API through the source.

• The character encoding is EUC-JP. COBOL sources and comments are EUC-JP, so run them through iconv -f EUC-JP -t UTF-8 before reading. The licence document (doc/license.html) is ISO-2022-JP. grep will not match Japanese keywords either unless you pipe through iconv.
• Learning the program naming convention speeds things up. The basic form for API programs is ORAPI + business number + R (read) / S (write) + version (V2/V3); the API editions of screen programs are ORCG…API…. COBOL sources are as a rule under cobol/<LD name>/, but there are exceptions (the orca51 API implementations are in cobol/orca52/), so when in doubt, find by program name.
• There are two kinds of entry point: GET-style and POST + XML-style. An API with no request record (…req) in the db "xml2" block of its LD definition (patientgetv2, for example) is likely a GET-parameter type; one that has a request record is likely POST + XML. Confirm definitively in the input handling on the COBOL side.
• Determine the meaning of data fields by cross-referencing record/ with the official table definition document. The “original” of response fields is record/*.db; the meaning on the DB side is in the officially published table definition document. Laying both side by side raises your confidence. Note also that some definitions have a coexisting WebORCA-specific .db.weborca version in which things like array limits differ (for example xml_acceptlstv2res goes from 1,000 to 1,500 entries). Check those when designing a WebORCA integration.
• Do your functional testing in a verification environment. The official trial server, or a community Docker environment, lets you hit the API and check behaviour without touching a live medical billing system. Never “test-fire” on a production machine.

12. Summary

• The whole Nichi-Rece API surface is concentrated in the bindapi definitions in lddef/*.ld, and grep alone enumerates 137 endpoints (5.2 series, July 2026 release).
• What the Nichi-Rece API really is, is “the API edition of screen-based workflows”. bind (screens) and bindapi (APIs) coexist in the same LD definition, and the module name in the URL derives from the business number of a screen.
• A single API can be dissected in the order lddef (dispatch) → COBOL header (function and history) → COPY clauses (data touched) → record/*.db (the original of the XML structure). The XML tag names are exactly the item names in the record definition.
• The gap between the official list (roughly 50) and the source (137) includes a set of APIs capable of driving the monthly workflow — receipt creation, electronic receipt data creation, data checking. But do not jump from “not on the list” to “undocumented”; verify case by case.
• The measured diff against the 5.1 series shows 9 additions (mostly online eligibility verification work) and 0 removals. Diffing the monthly snapshots is usable as an early warning network for integration maintenance.
• The licence agreement explicitly disclaims all warranties, documented APIs included, so “documented” does not mean “safe”. The source is the primary specification. Documented or not, if you are using it in production, pair it with version pinning, monthly diff monitoring, regression testing, and your own documentation.

Starting from the source rather than the specification, as we have done here, is an investigative technique that works well beyond ORCA — for any long-lived line-of-business system whose documentation has fallen behind its implementation. Fortunately, ORCA’s source is published, so you can practise the technique legally and against the latest state every month.

13. Appendix: Mapping Table of All 137 Endpoints (5.2 Series, July 2026)

These are all the endpoints mechanically extracted from the bindapi definitions in lddef/*.ld. The function names are English renderings of the “component name” field in each COBOL program’s header (the Japanese originals are transcribed verbatim in the Japanese edition of this article, inconsistencies and full-width parentheses included). This table is a record of the facts of the 5.2 series snapshot as of 1 July 2026; it does not indicate whether any endpoint may be used or is supported.

14. References

• Technical Information - JMA Standard Receipt Software - ORCA Project (source code releases)
• JMA Standard Receipt Software API Specification - ORCA Project
• JMA Standard Receipt Software API - ORCA Project
• orca-api: a Ruby library for the JMA Standard Receipt Software API (GitHub)
• Nichi-Rece 5.2 series and 5.1 series source code (both snapshots published July 2026) lddef/api01rv2.ld / lddef/orca13.ld / cobol/api01rv2/ORAPI012R1V2.CBL / record/xml_patientinfov2res.db / record/xml_findv3req.db and others — all measured figures and quotations in this article are based on these snapshots

Related Articles

Recent articles sharing the same tags. Deepen your understanding with closely related topics.

Related Topics

These topic pages place the article in a broader service and decision context.

Where This Topic Connects

This article connects naturally to the following service pages.

Frequently Asked Questions

Common questions about the topic of this article.

How many endpoints does the Nichi-Rece API have in total?

The API specification index page on the official site lists roughly 50, but counting the LD definition files in the published source code (5.2 series, July 2026 snapshot) gives 137 endpoints bound with bindapi. Some of the difference is documented on separate pages — form-related APIs, for example — so you cannot immediately conclude that "not on the list" means "undocumented". Still, counting on the source side lets you grasp the whole API surface as primary information. This article includes a mapping table of all 137.

Is it acceptable to use an API that is not in the official documentation in production?

Yes. ORCA's source code is published, so you can verify the implementation itself as the primary specification. In any case the licence agreement explicitly disclaims all warranties for the program as a whole, including documented APIs, so the assumption that "documented means safe" is the more mistaken position. The substantive difference from documentation is twofold: whether changes are likely to surface in the official documentation, and whether the API gives you common ground in conversations with your support provider. The first can be closed by diffing the monthly source releases; the second (undocumented APIs are less likely to be supported) remains. If you are going to use one in production, pair it with version pinning, diff monitoring, regression testing in a verification environment, your own documentation, and sharing your configuration with your support provider. That is what you ought to be doing for documented APIs too.

Can you also work out the request and response formats from the source?

Yes. The structure of Nichi-Rece's XML requests and responses is declared in definition files in the record/ directory (for example record/xml_patientinfov2res.db), and the XML tag names are the item names in those definitions verbatim. Even for an undocumented API, you can identify the responsible program from the LD definition, read the corresponding record definition, and derive every field of the request and response.

Can I investigate this without being able to read COBOL?

Reading COBOL is almost entirely unnecessary if all you want is the overall endpoint picture. The LD definition files (lddef/*.ld) and the data structure definitions (record/*.db) are plain text, and they declare the mapping between URL, program, and XML structure. You only start reading COBOL when you go on to chase the internal behaviour of an individual API — and even then, the comments in the program header (in Japanese) and the revision history alone yield a great deal of information.

Author Profile

Profile page for the article author.

Go Komura

Representative of KomuraSoft LLC

Focused on Windows software development, technical consulting, and investigations into failures that are difficult to reproduce.