닛레세 API의 전체 구조를 소스코드로 파악한다 ── ORCA의 공개 소스를 읽다(전 137개 엔드포인트 대응표 포함)

지난 글에서는 ORCA(일본의사회 표준 레셉트 소프트웨어)가 레세콘이라는 점, 그리고 20년 넘게 소스코드가 공개되어 왔다는 점을 정리했습니다.

이번에는 그 소스코드를 실제로 읽습니다. 주제는 닛레세 API의 전체 구조를 1차 정보에서 파악하는 것입니다. 공식 API 사양서를 위에서부터 읽는 대신,

1. 서버에 실제로 있는 엔드포인트를 소스에서 모두 세고,
2. API 하나를 구현부터 응답 XML 형태까지 따라가고,
3. 공식 문서와 대조해 차이를 검증하고,
4. 버전 간 diff로 API 변화를 실제로 측정한다

는 순서로 진행합니다. 글 끝에, 이 조사에서 얻은 전 137개 엔드포인트 대응표(URL·COBOL 프로그램·기능)를 실었습니다.

이 글의 조사 대상은 공식 공개된 닛레세 본체 5.2 계열 소스(2026년 7월 1일 공개 스냅샷)이며, 비교용으로 5.1 계열(같은 날 공개)도 사용합니다. 서술은 모두 이 두 버전에 근거하며, 재현에 필요한 명령은 본문에 적습니다.

대상 독자는 닛레세 API 연동을 앞으로 설계·구현할 개발자입니다. COBOL을 읽을 필요는 없습니다. 전체 구조를 파악할 때는 텍스트 grep과 iconv만 쓰고, 개별 API를 깊게 볼 때도 헤더 주석과 수정 이력이 중심입니다. 의료 사무 실무 지식도 전제로 하지 않습니다.

목차

1. 먼저 결론
2. 전제 ── 소스 입수와 버전 고정
3. API 디스패치 구조 ── URL은 lddef로 정해진다
4. 발견: API는 ‘화면 업무의 API 판’이다 ── bind와 bindapi
5. API 하나를 끝까지 따라간다 ── patientgetv2 해부
6. 엔드포인트를 모두 센다 ── grep 한 번의 조사 절차
7. 공식 목록과 대조한다 ── 목록에 없는 API의 예
8. 문서화되지 않은 API의 사양을 소스에서 도출한다 ── findv3 예
9. 버전 간 diff로 API 변화를 실측한다 ── 5.1 계열 vs 5.2 계열
10. 문서화되지 않은 API를 다루는 법 ── ‘문서화’는 보증이 아니다
11. 깊게 따라갈 때의 실무 메모
12. 정리
13. 부록: 전 137개 엔드포인트 대응표(5.2 계열·2026년 7월판)
14. 참고 자료

그림의 실선은 항상 성립하는 관계, 점선은 조건이 붙는 관계입니다(성립 조건은 상세 페이지의 관계별 설명에 적혀 있습니다). 관계 전체 목록(총 20건, 근거와 확신도 포함)과 주요 개념의 정의는 지식 맵 상세 페이지에 정리되어 있습니다(일본어). 데이터: JSON-LD / Turtle

1. 먼저 결론

• 닛레세 API의 URL과 서버 측 프로그램의 대응은 소스의 lddef/*.ld(LD 정의 파일)에 선언적으로 적혀 있다. COBOL을 읽지 않아도 텍스트 grep만으로 API 전체를 나열할 수 있다.
• 5.2 계열 스냅샷에서는 LD 정의 27개에 엔드포인트 137개가 bindapi로 묶여 있다. 공식 사이트의 API 사양 목록 페이지에 실린 것은 약 50건이며, 소스 쪽에는 그 두 배가 넘는 엔드포인트가 실제로 존재한다.
• XML 요청·응답 구조는 record/*.db에 선언되어 있고, XML 태그 이름은 정의의 항목 이름이 그대로 쓰인다. 즉 문서화되지 않은 API라도 lddef→cobol→record를 따라가면 사양을 도출할 수 있다.
• 5.1 계열과 버전 간 diff를 내면 엔드포인트는 9건 추가·삭제 0건이다. 추가분은 온라인 자격 확인(마이나 보험증) 관련에 몰려 있어, “API는 제도 대응으로 늘어난다. 기존 것은(적어도 이 두 계열 사이에서는) 사라지지 않았다”는 점을 실측할 수 있다.
• 문서화되지 않은 API는 “쓰면 안 되는 API”가 아니다. ORCA는 오픈소스이며, 소스 자체를 1차 사양으로 다룰 수 있다. 문제는 약속의 유무가 아니라 “변경을 스스로 감지하는 운영을 갖출 수 있는가”이며, 그 판단의 틀을 10장에서 정리한다.

2. 전제 ── 소스 입수와 버전 고정

소스는 공식 기술 정보 페이지에서 tarball(zip)로 내려받을 수 있습니다. 매월 1일에 전월 1일 시점의 스냅샷으로 갱신되므로, 조사 결과는 반드시 버전과 세트로 기록하는 것이 철칙입니다. 이 글에서는 다음 버전을 사용합니다.

• 입수처: https://ftp.orca.med.or.jp/pub/src/jma-receipt.r_5_2_branch.zip(비교용으로 r_5_1_branch.zip도)
• 취득일: 2026-07-17(모두 2026년 7월 1일 시점의 스냅샷)
• 5.2 계열의 VERSION 파일: 5.2.0

직접 따라 할 때의 최소 절차는 다음과 같습니다. 이후 장의 명령은 모두 압축을 푼 디렉터리를 기점으로 실행합니다.

# 작업 디렉터리를 정한 뒤 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

# 버전 기록. 이 둘은 조사 메모에 반드시 남긴다
sha256sum jma-receipt.r_5_2_branch.zip
cat jma-receipt.r_5_2_branch/VERSION      # → 5.2.0

# 이후 명령은 이 디렉터리 안에서 실행한다
cd jma-receipt.r_5_2_branch
ls lddef/ | head

비교용 5.1 계열도 URL의 r_5_2_branch를 r_5_1_branch로 바꿔 같은 절차로 풀어 두면, 9장의 diff를 그대로 실행할 수 있습니다.

압축을 풀면 약 8,200개 파일·237MB이며, 이 글에서 쓰는 것은 주로 다음 세 디렉터리입니다.

3. API 디스패치 구조 ── URL은 lddef로 정해진다

본론에 들어가기 전에, 이 장부터 쓰는 말을 정리해 둡니다. ORCA 고유의 표현이 대부분이지만, 외울 것은 다섯 개면 충분합니다.

닛레세 API의 URL은 /api01rv2/patientgetv2처럼 “모듈 이름/엔드포인트 이름”의 두 단 구성입니다. 이 대응은 lddef/의 LD 정의 파일에 그대로 나타납니다.

lddef/api01rv2.ld의 앞부분을 봅니다.

name	api01rv2;

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

읽는 법은 단순합니다. LD 이름이 URL의 첫 번째 세그먼트, bindapi의 첫 번째 인수가 두 번째 세그먼트, 세 번째 인수가 처리를 담당하는 COBOL 프로그램 이름입니다. 즉 /api01rv2/patientgetv2로의 요청은 ORAPI012R1V2라는 COBOL 프로그램으로 넘어갑니다.

flowchart LR
    C["연동 시스템<br/>전자 차트 등"] -->|"GET /api01rv2/patientgetv2?id=환자번호"| M["닛레세 서버<br/>MONTSUQI"]
    M -->|"lddef/api01rv2.ld<br/>bindapi 정의를 참조"| P["ORAPI012R1V2.CBL<br/>환자 기본 정보 조회"]
    P --> D[("PostgreSQL")]
    P -->|"XML 응답"| C

LD 정의에는 이 밖에도, 응답을 조립할 때 쓰는 XML 레코드 군(db "xml2" { ... })이나, 알아 두면 편한 설정(배열 크기 등)도 선언되어 있습니다. LD 파일은 “그 모듈이 다루는 화면·API·데이터 구조의 목차”로 읽을 수 있습니다.

4. 발견: API는 ‘화면 업무의 API 판’이다 ── bind와 bindapi

LD 정의를 보다 보면 바로 눈에 들어오는 점이 있습니다. 같은 파일에 bind(화면)와 bindapi(API)가 함께 있다는 것입니다. 환자 조회 모듈 lddef/orca13.ld를 봅니다.

name	orca13;

bind	"Q01"		"OpenCOBOL"	"ORCGQ01";     ← 환자 조회의 대화 화면
bind	"Q02"		"OpenCOBOL"	"ORCGQ02";
...
bindapi "findv3"    "OpenCOBOL"	"ORCGQAPI01";  ← 그 API 판
bindapi "findinfv3" "OpenCOBOL"	"ORCGQAPI02";
bindapi "foundv3"   "OpenCOBOL"	"ORCGQAPI03";

Q01 이하는 원무 직원이 조작하는 환자 조회 화면 프로그램이고, findv3 이하는 같은 모듈에 속한 API입니다. 프로그램 이름도 ORCGQ01(화면)에 대해 ORCGQAPI01(API)처럼, 화면 쪽 이름 안에 API를 끼운 형태입니다.

즉 닛레세 API는 독립 API 서버로 설계된 것이 아니라, 대화 화면과 같은 업무 프로그램 기반 위에 “화면 대신 XML로 대화하는 입구”를 업무 모듈마다 더해 온 것입니다. 이 구조를 알면 다음 두 가지가 자연스럽게 이해됩니다.

• URL의 첫 번째 세그먼트(orca13, orca42…)가 화면의 업무 번호에서 왔기 때문에, API만 보면 의미 없는 숫자처럼 보이는 이유
• “화면에서 되는 업무에는 API 판이 있을 수 있다”는 찾는 법이 성립하는 이유 ── 문서화되지 않은 API를 찾는다는 것은, 실은 이 “화면 업무의 API 판”을 나열하는 작업에 가깝습니다

5. API 하나를 끝까지 따라간다 ── patientgetv2 해부

전체를 세기 전에, API 하나를 구현부터 응답 형태까지 따라가 봅니다. 소재는 가장 기본적인 환자 기본 정보 조회 /api01rv2/patientgetv2입니다.

(1) 디스패치: lddef/api01rv2.ld의 bindapi "patientgetv2" → ORAPI012R1V2. 실체는 cobol/api01rv2/ORAPI012R1V2.CBL(2,163행)입니다. COBOL 소스는 원칙적으로 LD 이름과 같은 디렉터리에 두므로, lddef를 읽으면 구현 파일은 거의 기계적으로 특정할 수 있습니다(예외도 있습니다. 예를 들어 orca51의 API 군 실체는 cobol/orca52/에 있습니다. 확실한 방법은 프로그램 이름으로 find하는 것입니다).

(2) 프로그램 헤더: 맨 앞에 “コンポーネント名 : 患者基本情報取得(version2対応)”라고 있고, 이어지는 수정 이력에는 2013년의 지역 연계 ID 대응부터 2022년의 전자 처방전 대응, 2024년의 “보험증에 의한 자격 유효성 반환 대응”까지, 이 API 하나가 받아 온 제도 개정이 연표로 늘어서 있습니다. API 사양서의 “갱신 이력”보다 자세합니다.

(3) 무엇을 읽는가: WORKING-STORAGE SECTION의 COPY 구(가져오는 공통 정의)를 보면, 이 API가 건드리는 데이터가 보입니다. 발췌하면 다음과 같습니다.

COPY "CPPTINF.INC".          *> 患者基本情報(tbl_ptinf)
COPY "CPPTNUM.INC".          *> 患者番号
COPY "CPJYURRK.INC".         *> 受療履歴
COPY "CPPTCARE-HKNINF.INC".  *> 介護保険情報
COPY "CPPTMYNUMBER.INC".     *> 患者個人番号
COPY "CPONSHI-KAKU.INC".     *> オンライン資格確認結果
COPY "CPPATIENTXMLV2RES.INC" *> レスポンス編集用

환자 한 명만 반환하는 API가 개호보험·마이넘버·온라인 자격 확인까지 정의 30개 가까이를 가져옵니다. “환자 기본 정보”의 의미가 제도와 함께 계속 부풀어 온 물증입니다.

(4) 응답의 형태: 응답 XML 구조는 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);
                ...

닛레세 API를 써 본 분이라면 낯익을 것입니다. API 응답의 XML 태그 이름(Patient_ID, WholeName…)은 이 record 정의의 항목 이름이 그대로 쓰입니다. 즉 공식 XML 사양서에 적힌 항목 표의 “원본”이 여기에 있다는 뜻입니다. 항목 크기(자릿수)까지 적혀 있으므로, 연동 측 밸리데이션 설계의 1차 정보로도 쓸 수 있습니다.

이 (1)→(4)가 닛레세 API 하나를 해부하는 절차의 템플릿입니다. lddef로 프로그램을 특정하고, 헤더로 기능과 역사를 잡고, COPY 구로 건드리는 데이터를 파악하고, record로 메시지 구조를 확정합니다. COBOL 본체의 로직을 읽지 않아도, 여기까지면 실무에 필요한 정보의 대부분이 모입니다.

6. 엔드포인트를 모두 센다 ── grep 한 번의 조사 절차

구조를 알면 전체 나열은 기계 작업입니다.

# 엔드포인트 → COBOL 프로그램 대응을 모두 나열
grep -H '^[[:space:]]*bindapi' lddef/*.ld

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

# 각 엔드포인트의 기능 이름을 COBOL 헤더에서 기계 추출
# (소스는 EUC-JP이므로 iconv를 끼운다. 프로그램 위치는
#  LD 이름과 일치하지 않는 예외가 있으므로 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

세 번째 스크립트는 길어서, 파이프 각 단이 하는 일을 나눠 둡니다.

1. grep '^[[:space:]]*bindapi' "$ld" ── LD 정의에서 API 선언 행만 꺼낸다
2. sed 's/"//g; s/;//' ── 큰따옴표와 행 끝 세미콜론을 떼고, 공백으로 나뉜 네 단어(bindapi / 엔드포인트 이름 / OpenCOBOL / 프로그램 이름)로 만든다
3. while read -r _ ep _ prog ── 첫째·셋째 단어는 버리고, 엔드포인트 이름과 프로그램 이름만 받는다
4. find cobol -name "$prog.CBL" ── 프로그램 실체를 찾는다. LD 이름과 디렉터리 이름이 일치하지 않는 예외가 있으므로 경로를 고정하지 않는다
5. iconv -f EUC-JP -t UTF-8 ── COBOL 소스는 EUC-JP이므로, 일본어 헤더 주석을 읽으려면 변환한다
6. grep -m1 'コンポーネント名' | sed … ── 헤더의 “コンポーネント名” 행을 한 건만 집어, 콜론 뒤(기능 이름)를 꺼낸다

실행하면 탭 구분으로 “모듈 / 엔드포인트 / 프로그램 / 기능 이름” 네 열이 나옵니다. 앞 6행은 다음과 같습니다.

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

전체는 137행입니다. 3행째의 “予約一覧 (xml2）”처럼 공백이 겹치거나, 괄호가 전각·반각이 섞인 것은 헤더 기재를 그대로 꺼냈기 때문입니다. 이 출력을 다듬은 것이 부록의 대응표이며, 거기에서도 표기는 원문 그대로입니다(13장).

이 버전에서의 집계는 다음과 같습니다(137건 전체의 개별 항목은 부록에 실었습니다).

조회계(api01rv2)에 약 40%가 모이는 한편, 갱신계는 업무 모듈 단위(환자=orca12, 접수=orca11, 진료 행위=api21…)로 나뉩니다. 4장의 “화면 업무의 API 판”이라는 구조가 이 분포에도 그대로 나타납니다.

하나 더 눈에 띄는 것은 session 모듈의 session_start(로그인 인증)나 orca00의 print(인쇄)처럼, 업무 API라기보다 기반 기능 API가 섞여 있다는 점입니다. 공식 사양서 목록만 아무리 봐도 이 계층의 존재에는 깨닫지 못합니다.

개별 엔드포인트는 부록의 전 137건 대응표에 있습니다. 위 표의 건수로 목적 모듈의 감을 잡고, 부록을 모듈 이름으로 집어 가는 것이 찾는 법의 기본입니다.

7. 공식 목록과 대조한다 ── 목록에 없는 API의 예

다음으로, 공식 사이트의 “日医標準レセプトソフトAPI仕様” 목록 페이지에 실린 API(약 50건)와 소스에서 뽑은 137건을 대조합니다. 그러면 목록 페이지에 없는 엔드포인트가 소스 쪽에 다수 실제로 존재한다는 것을 알 수 있습니다. 기능 영역별로 예를 듭니다(기능 이름은 모두 COBOL 헤더의 “コンポーネント名”에서 확인한 것입니다).

즉 접수나 환자 정보 같은 일상 연동뿐 아니라, 월차 레셉트 업무(작성→점검→레세덴 데이터 출력→청구 관리)를 외부에서 구동할 수 있는 API 군이 구현으로 존재한다는 것입니다. 전자 차트 연동만 알면 보이지 않는 계층입니다.

여기서 중요한 주의가 두 가지 있습니다.

1. “목록에 없다 = 문서화되지 않았다”고 바로 단정하지 말 것. 예를 들어 서식 데이터 취득(formdatagetv2)처럼 PushAPI 쪽 문서에서 문서화된 API도 있고, 목록 페이지는 전 API의 망라를 보장하지 않습니다. 개별 문서 페이지나 사이트 내 검색까지 확인한 뒤에 “문서를 찾지 못했다”고 말해야 합니다(위 표는 그 확인을 한 결과이지만, 그래도 “공개된 문서가 존재하지 않는다”는 완전한 증명은 되지 않습니다).
2. 서드파티 구현도 대조 재료가 된다. 닛레세 API를 Ruby에서 쓰는 orca-api 라이브러리 같은 OSS는, 실무에서 써 온 엔드포인트 카탈로그로 참고가 됩니다.

8. 문서화되지 않은 API의 사양을 소스에서 도출한다 ── findv3 예

“목록에 없는 API가 있다”는 것을 알아도, 요청 형태를 모르면 조사도 할 수 없습니다. 여기서 5장의 템플릿이 먹힙니다. findv3(환자 조회)로 해 봅니다.

요청 구조는 record/xml_findv3req.db에 있습니다(발췌).

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

정의만 읽어도, 이것이 생년월일 범위·성별·최종 내원일 범위·담당의·진료과·사망 구분·환자 번호 범위·성명(복수 지정 가능) 등을 조합할 수 있는, 꽤 고기능의 환자 검색 API라는 것을 알 수 있습니다. 공식 목록에 실린 환자 검색 계열 API(patientlst1v2〜)는 환자 번호 범위나 성명 등 단기능 검색이 중심이므로, 화면의 환자 조회와 같은 복합 조건 검색이 되는 이 API는 기능 면에서는 분명히 상위 호환입니다.

응답 구조도 마찬가지로 record/xml_findv3res.db에 있고, 대응하는 COBOL(ORCGQAPI01.CBL)을 읽으면 세부 동작(건수 상한이나 정렬 순서 등)도 확인할 수 있습니다. “문서화되지 않은 API”는, 소스가 공개된 ORCA에서는 “스스로 문서를 만들 수 있는 API”입니다.

이렇게 도출한 사양을 프로덕션에서 어디까지 신뢰하고 쓸지 ── 그것이 다음 장의 주제입니다.

9. 버전 간 diff로 API 변화를 실측한다 ── 5.1 계열 vs 5.2 계열

문서화되지 않은 API의 위험을 논하기 전에, “API는 얼마나 바뀌는가”를 실측해 둡니다. 같은 날 공개된 5.1 계열 스냅샷과 bindapi 정의를 diff한 결과입니다.

추가된 9건의 내역은 온라인 자격 확인 관련이 6건(onlinequa10·onlinequa11·onlinequaapp1〜3·onlineaidlstreq1), 환자 메모 등록(patientmemomodv2), 입력 코드 일괄 반환(inputcodelstv3), 입력·진료 코드 정보 조회(medicationgetv2)로 합계 9건입니다. 제도 대응(마이나 보험증 주변)이 API 증설로 나타나 있다는 점이 분명합니다.

이 관찰에서 말할 수 있는 것은 다음 두 가지입니다.

• 엔드포인트의 “면”은 안정적이다(이 두 계열 사이에서 삭제 제로). 두려워할 것은 소멸보다 개별 API의 항목 추가·동작 변경(5장에서 본 수정 이력 같은 변화)이다.
• 소스가 매월 공개되므로 이런 변경 감지는 자동화할 수 있다. 연동 시스템을 보수하고 있다면, 월차 스냅샷의 lddef와 record를 diff하는 것만으로 다음 달 버전 업에서 무엇이 바뀌는지의 조기 경보망이 됩니다. 소스 공개가 아니면 얻기 어려운, 다른 레세콘에서는 갖기 힘든 보수 수단입니다.

10. 문서화되지 않은 API를 다루는 법 ── ‘문서화’는 보증이 아니다

먼저 전제를 바로잡습니다. 일본의사회 오픈소스 사용 허락 계약은 제2장 제5조에서, 지장 없이 동작한다거나 하자가 없다는 점에 대해 프로그램 전체를 무보증으로 두고 있습니다. 이는 문서화된 API에도 똑같이 적용됩니다. 호환성에 대해서도, 문서화 API를 “바꾸지 않는다”고 약속하는 명문의 규정이 공식 문서에 있는 것은 아니며, 실제로 5장에서 본 대로 문서화 API의 대표인 patientgetv2조차 제도 대응마다 항목이 계속 추가되어 왔습니다.

즉 “문서화 여부”의 차이는 보증의 유무가 아닙니다. 실질적 차이를 압축하면 다음 두 가지뿐입니다.

1. 변경이 공식 문서 갱신으로 나타나기 쉬운가(문서화되지 않은 API의 변경은 소스를 읽지 않으면 보이지 않는다)
2. 지원 사업자와 대화할 때 안건으로 올리기 쉬운가

그리고 ORCA는 소스가 매월 공개됩니다. 1번 차이는 소스 diff 감시로 메울 수 있습니다. 소스야말로 1차 사양이고, 문서는 그 발췌 번역에 지나지 않는다 ── 오픈소스에 대한 올바른 태도는 이쪽입니다. 문서와 소스가 어긋날 때, 실제로 움직이는 것은 소스 쪽입니다.

그 위에서, 레셉트 청구라는 금전에 직결되는 시스템을 다루는 이상, 문서화 여부와 관계없이 프로덕션 흐름에 넣는 API에는 다음 운영을 세트로 두어야 합니다.

운영상의 주의가 하나 있습니다. 공개 스냅샷은 전월 1일 시점의 내용이므로, 패키지 갱신을 먼저 프로덕션에 적용해 버리면 대응하는 소스를 읽을 수 있는 것은 적용 후가 됩니다. 이 감시를 조기 경보로 쓰려면 대응하는 소스의 공개와 검증을 기다린 뒤에 버전 업한다는 순서로 맞춰야 합니다.

거꾸로 말하면, 이 운영을 갖추지 못한 체제에서는 문서화 API만 써도 안전하지 않습니다. 무보증 오픈소스를 업무의 기간에 둔다는 것은 그런 뜻입니다.

11. 깊게 따라갈 때의 실무 메모

개별 API를 소스로 깊게 따라가는 단계의, 자잘한 함정입니다.

• 문자 코드는 EUC-JP. COBOL 소스나 주석은 EUC-JP이므로 iconv -f EUC-JP -t UTF-8을 통과시킨 뒤에 읽는다. 라이선스 문서(doc/license.html)는 ISO-2022-JP. grep도 iconv를 끼우지 않으면 일본어 키워드로는 잡히지 않는다.
• 프로그램 이름 규칙을 외우면 빠르다. API 계열은 ORAPI+업무 번호+R(참조)/S(갱신)+판(V2/V3)이 기본형이고, 화면 계열의 API 판은 ORCG〜API〜. COBOL 소스는 원칙 cobol/<LD명>/ 아래이지만 예외가 있다(orca51의 API 실체는 cobol/orca52/)므로, 헤매면 프로그램 이름으로 find한다.
• 입구는 GET 계열과 POST+XML 계열 두 종류. LD 정의의 db "xml2" 블록에 요청용 레코드(〜req)가 없는 API(예: patientgetv2)는 GET 파라미터형, 있는 것은 POST+XML형으로 가늠이 선다. 최종 확인은 COBOL 쪽 입력 처리로.
• 데이터 항목의 의미는 record/+공식 테이블 정의서의 대조로. 응답 항목의 “원본”은 record/*.db, DB 쪽 의미는 공식 공개의 테이블 정의서. 둘을 나란히 두면 확실도가 올라간다. 일부 정의에는 WebORCA용 .db.weborca 판이 함께 있고, 배열 상한 등이 다르다(예: xml_acceptlstv2res는 1,000건→1,500건). WebORCA 연동 설계에서는 그쪽을 확인한다.
• 동작 확인은 검증 환경에서. 공식 체험 서버나 커뮤니티의 Docker 환경을 쓰면, 실기 레세콘에 손대지 않고 API를 호출해 확인할 수 있다. 프로덕션 기기에서의 “시험 호출”은 금지.

12. 정리

• 닛레세 API의 전체 구조는 lddef/*.ld의 bindapi 정의에 모여 있으며, grep만으로 엔드포인트 137개(5.2 계열·2026년 7월판)를 나열할 수 있다.
• 닛레세 API의 정체는 “화면 업무의 API 판”이다. bind(화면)와 bindapi(API)가 같은 LD 정의에 함께 있고, URL의 모듈 이름은 화면의 업무 번호에서 온다.
• API 하나는 lddef(디스패치)→COBOL 헤더(기능·역사)→COPY 구(건드리는 데이터)→record/*.db(XML 구조의 원본) 순으로 해부할 수 있다. XML 태그 이름은 record 정의의 항목 이름 그 자체이다.
• 공식 목록(약 50건)과 소스(137건)의 차분에는 레셉트 작성·레세덴 데이터 작성·데이터 체크 같은 월차 업무를 구동할 수 있는 API 군이 포함된다. 다만 “목록에 없다 = 문서화되지 않았다”고 바로 단정하지 말고, 한 건씩 검증한다.
• 5.1 계열과의 diff 실측에서는 추가 9건(온라인 자격 확인 관련이 중심)·삭제 0건. 월차 스냅샷의 diff는 연동 보수의 조기 경보망으로 쓸 수 있다.
• 사용 허락 계약은 문서화 API를 포함해 무보증을 명시하고 있으며, “문서화 = 안전”이 아니다. 소스야말로 1차 사양이다. 문서화 여부를 가리지 않고, 프로덕션에서 쓴다면 버전 고정·월차 diff 감시·회귀 확인·자체 문서 정비를 세트로 둔다.

사양서부터 들어가지 않고 소스부터 들어간다는 이번 순서는, ORCA에 한정하지 않고 “문서가 구현을 따라가지 못하는 장수 업무 시스템” 전반에서 쓸 수 있는 조사 기법입니다. 다행히 ORCA는 소스가 공개되어 있어, 이 기법을 합법적으로, 게다가 매월 최신 상태로 실천할 수 있습니다.

13. 부록: 전 137개 엔드포인트 대응표(5.2 계열·2026년 7월판)

lddef/*.ld의 bindapi 정의에서 기계 추출한 전체 엔드포인트입니다. 기능 이름은 각 COBOL 프로그램 헤더의 “コンポーネント名” 란을 그대로 옮겼습니다(표기 흔들림·전각 괄호·오기로 보이는 철자도 모두 원문 그대로입니다. “請求額シュミレーション”, “medicatonmodv2” 등은 당사가 옮겨 적으며 틀린 것이 아닙니다). 이 표는 2026년 7월 1일 시점 5.2 계열 스냅샷의 사실 기록이며, 각 엔드포인트의 이용 가능 여부·지원 상황을 나타내는 것이 아닙니다.

표는 모듈(URL의 첫 번째 세그먼트) 순으로 늘어놓았습니다. 목적 API를 찾을 때는 다음 순으로 좁히면 빨리 도착합니다. 브라우저의 페이지 내 검색(Ctrl+F)에 모듈 이름을 넣으면 그 덩어리의 선두로 건너뜁니다.

14. 참고 자료

• 기술 정보 - 日医標準レセプトソフト - ORCA Project(소스코드 공개)
• 日医標準レセプトソフトAPI仕様 - ORCA Project
• 日医標準レセプトソフトAPI - ORCA Project
• orca-api: 日医標準レセプトソフトAPI의 Ruby 라이브러리(GitHub)
• 닛레세 본체 5.2 계열·5.1 계열 소스코드(모두 2026년 7월 공개 스냅샷) lddef/api01rv2.ld / lddef/orca13.ld / cobol/api01rv2/ORAPI012R1V2.CBL / record/xml_patientinfov2res.db / record/xml_findv3req.db 외 ── 본문의 실측값·인용은 모두 이 스냅샷에 근거한다

관련 기사

같은 태그를 공유하는 최신 기사입니다. 더 가까운 주제로 지식을 넓힐 수 있습니다.

관련 토픽

이 기사와 가까운 토픽 페이지입니다. 기사를 출발점 삼아 관련 서비스와 다른 기사로 이어집니다.

이 주제와 연결되는 서비스

이 기사는 다음 서비스 페이지로 이어집니다. 가까운 입구부터 확인해 주세요.

자주 묻는 질문

이 기사 주제에 대해 상담 시 자주 나오는 질문을 모았습니다.

닛레세 API 엔드포인트는 모두 몇 개인가요?

공식 사이트의 API 사양 목록 페이지에는 약 50건이 실려 있습니다. 다만 공개 소스코드(5.2 계열·2026년 7월 스냅샷)의 LD 정의 파일을 세면, bindapi로 묶인 엔드포인트는 137건입니다. 차분의 일부는 서식 계열처럼 다른 페이지에 문서화된 것도 있으므로 '목록에 없다 = 문서화되지 않았다'고 바로 단정할 수는 없습니다. 그래도 소스 쪽에서 세면 API 전체 구조를 1차 정보로 파악할 수 있습니다. 이 글에 137건 전체 대응표를 실었습니다.

공식 문서에 없는 API를 프로덕션에서 사용해도 되나요?

사용할 수 있습니다. ORCA는 소스코드가 공개되어 있어, 구현 자체를 1차 사양으로 확인할 수 있기 때문입니다. 애초에 사용 허락 계약은 문서화된 API를 포함한 프로그램 전체에 대해 무보증을 명시하고 있습니다. 따라서 '문서화되어 있으면 안전하다'는 전제 쪽이 잘못입니다. 문서화 여부의 실질적 차이는 '변경이 공식 문서에 나타나기 쉬운가'와 '지원 사업자와 대화할 때 안건으로 올리기 쉬운가' 두 가지입니다. 전자는 매월 공개되는 소스의 diff 감시로 메울 수 있지만, 후자(문서화되지 않은 API는 지원 대상이 되기 어렵다는 점)는 남습니다. 프로덕션에서 쓴다면 버전 고정, diff 감시, 검증 환경에서의 회귀 확인, 자체 문서 정비, 지원 사업자에 구성 공유를 세트로 갖추십시오. 문서화된 API를 쓸 때도 본래는 같습니다.

API의 요청·응답 형식도 소스에서 알 수 있나요?

알 수 있습니다. 닛레세의 XML 요청·응답 구조는 record/ 디렉터리의 정의 파일(예: record/xml_patientinfov2res.db)에 선언적으로 적혀 있고, XML 태그 이름은 이 정의의 항목 이름이 그대로 쓰입니다. 문서화되지 않은 API라도 LD 정의에서 담당 프로그램을 찾고, 대응하는 record 정의를 읽으면 요청·응답의 모든 항목을 도출할 수 있습니다.

COBOL을 읽지 못해도 조사할 수 있나요?

엔드포인트 전체 구조만 파악한다면 COBOL 독해는 거의 필요 없습니다. LD 정의 파일(lddef/*.ld)과 데이터 구조 정의(record/*.db)는 텍스트이며, URL·프로그램·XML 구조의 대응이 선언적으로 적혀 있습니다. 개별 API의 내부 동작을 깊게 따라가는 단계에서야 COBOL을 읽게 되지만, 프로그램 헤더의 주석(일본어)과 수정 이력만으로도 많은 정보를 얻을 수 있습니다.

저자 프로필

기사 저자의 프로필 페이지입니다.

Go Komura

합동회사 코무라소프트 대표

Windows 소프트웨어 개발, 기술 상담, 장애 조사를 중심으로 재현이 어려운 장애 조사와 기존 자산이 남아 있는 프로젝트에 강점이 있습니다.