닛레세(日レセ) API의 전체상을 소스코드로 파악하다 ── ORCA의 공개 소스를 읽다(전 137개 엔드포인트 대응표 첨부)

지난 글에서는 ORCA(일본의사회 표준 레셉트 소프트웨어)가 레셉트 컴퓨터(레세콘)임을, 그리고 20년 이상 소스코드가 계속 공개되어 왔음을 정리했습니다.

이번에는 그 소스코드를 실제로 읽어 봅니다. 주제는 닛레세 API의 전체상을 1차 정보로부터 파악하는 것입니다. 공식 API 사양서를 처음부터 읽어 나가는 것이 아니라,

1. 서버 측에 실재하는 모든 엔드포인트를 소스로부터 세어 올리고,
2. API 1개를 구현부터 응답 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 1개를 끝까지 추적한다 ── 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. 참고 자료

1. 먼저 결론

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

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

소스는 공식 기술 정보 페이지에서 tar볼(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개 디렉터리입니다.

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

본론에 들어가기 전에, 이 장부터 사용할 용어를 정리해 둡니다. ORCA 특유의 표현뿐이지만, 외워야 할 것은 5개면 충분합니다.

닛레세 API의 URL은 /api01rv2/patientgetv2처럼 ‘모듈명/엔드포인트명’의 2단 구성입니다. 이 대응은 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 1개를 끝까지 추적한다 ── patientgetv2의 해부

전체상을 세어 보기 전에, API 1개를 구현부터 응답의 형태까지 추적해 봅니다. 소재는 가장 기본적인 환자 기본정보 취득 /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 1개가 받아 온 제도 개정이 연표처럼 나열되어 있습니다. 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" *> 응답 편집용

환자 1명을 반환할 뿐인 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 1개를 해부하는 절차의 템플릿입니다. 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/;//' ── 이중따옴표와 행 끝의 세미콜론을 없애고, 공백으로 구분된 4개의 단어(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 … ── 헤더의 “コンポーネント名”(컴포넌트명) 행을 1건만 뽑아, 콜론 뒤(기능명)를 추출한다

실행하면, 탭으로 구분되어 ‘모듈 / 엔드포인트 / 프로그램 / 기능명’의 4개 열이 나열됩니다. 앞의 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)에 약 4할이 몰려 있는 한편, 갱신 계열은 업무 모듈 단위(환자=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 증설로 나타나고 있음을 분명히 확인할 수 있습니다.

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

• 엔드포인트의 ‘면’은 안정적이다(이 두 계열 사이에서 삭제 0건). 두려워해야 할 것은 소멸보다 개별 API의 항목 추가·동작 변경(5장에서 본 수정 이력과 같은 변화)이다.
• 소스가 매월 공개되므로, 이런 종류의 변경 감지는 자동화할 수 있다. 연동 시스템을 유지보수하고 있다면, 월차 스냅샷의 lddef와 record를 diff하는 것만으로 다음 달 버전업에서 무엇이 바뀌는지에 대한 조기경보망이 된다. 이는 소스 공개이기에 가능한, 다른 레셉트 컴퓨터에서는 얻기 어려운 유지보수 수단입니다.

10. 미문서화 API와의 관계 맺는 법 ── ‘문서화’는 보증이 아니다

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

즉 ‘문서화/미문서화’의 차이는 보증의 유무가 아닙니다. 실질적인 차이는 파고들어 보면 다음 두 가지뿐입니다.

1. 변경이 공식 문서의 갱신으로 나타나기 쉬운가(미문서화 API의 변경은 소스를 읽지 않는 한 보이지 않는다)
2. 지원 사업자와의 대화 테이블에 오르기 쉬운가

그리고 ORCA는 소스가 매월 공개됩니다. 첫 번째 차이는 소스의 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 계열의 2종류. 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 1개는 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 소프트웨어 개발, 기술 상담, 장애 조사를 중심으로 재현이 어려운 장애 조사와 기존 자산이 남아 있는 프로젝트에 강점이 있습니다.