KPIS API 연계
이 시스템이 쓰는 KPIS OpenAPI 서비스, 인증 방식, 실제 운영에서 확인한 KPIS 동작, 내부 API 묶음을 정리한 참고 문서입니다. 기준은 심평원 「OpenAPI 개발가이드_신규API」(2026-03-30)와 저장소 docs/kpis-report-api.md입니다.
인증
| 방식 | 쓰는 서비스 | 받는 법 |
|---|---|---|
| JWT | 보고·결과 조회(MA111·MA112), 반송신청·결과(MA113·MA114), 입고내역(MA115·MA119), 적기보고율(MA116) | 업체당 한 쌍인 클라이언트 아이디·시크릿으로 토큰을 받습니다. 토큰은 운영 서버 1시간, 개발 서버 2일 유효합니다 |
| API KEY | 표준코드·거래처·바코드 조회(MA101~MA107), 회수의약품(MA109), 공급내역 집계(MA110), 의약품 상세(MA117), 표준코드 전체(MA118) | 업무포털 OPEN API 탭에서 서비스마다 받는 승인키 |
요청의 사업자번호는 토큰을 받은 사업자와 같아야 합니다. 다르면 KPIS가 실패로 답합니다. 신청 절차는 설정과 사용자 관리하기에 있습니다.
공동인증서 서명 방식은 운영에서 쓰지 않아 2026-11-18에 지웠습니다. 서명 없는 SOAP 봉투 처리와 조회계의 WSDL 중계는 남아 있습니다.
서비스 목록
| ID | 서비스 | 이 시스템에서 쓰는 곳 |
|---|---|---|
| MA101 | 표준코드마스터 정보 조회 | KPIS 보고 › 조회 |
| MA102 | 거래처 정보 조회 | 조회 |
| MA103 | RFID 태그 정보 조회 | 조회 |
| MA104 | 바코드번호(최소 묶음번호) 조회 | 조회 |
| MA105 | 바코드번호(일련번호) 조회 | 조회 |
| MA106 | 바코드번호(일련번호 상세) 조회 | 조회 |
| MA107 | 다건 RFID 태그 조회 | 조회 |
| MA109 | 회수의약품 반송마스터(EB) 조회 | 조회 |
| MA110 | 공급내역 집계 조회 | 이미 접수 검사, 빠진 줄 대조, 보고 뒤 대조, 공급 현황 |
| MA111 | 공급내역 보고 저장 | 보고 실행 |
| MA112 | 공급내역 보고 결과 조회 | 보고 실행, 결과 다시 확인 |
| MA113 | 반송신청 저장 | 변경 내용 확인의 반송신청 |
| MA114 | 반송신청 결과 조회 | 하루 세 번 자동 조회, 결과 다시 보기 |
| MA115 | 입고내역 조회(갑지) | 대시보드 참고 › 입고내역 (MA115) |
| MA116 | 분기별 적기보고율 조회 | 대시보드 적기보고율, 하루 한 번 점검 |
| MA117 | 의약품관련 상세정보 조회 | 조회 |
| MA118 | 표준코드 마스터 전체 조회 | 대시보드 표준코드 마스터 갱신(MA118), 사전점검 전 마스터 갱신 |
| MA119 | 입고내역 조회(을지) | 입고내역 줄을 누르면 일련번호 조회 |
보고 흐름
MA111 보고 저장 → API 접수번호
→ MA112 결과 조회
접수완료: 줄을 접수로 기록
점검완료(오류): 오류 줄만 반송으로 빼고 다시 MA111
접수된 줄을 고칠 때
→ 기한(공급월 다음 달 말일) 안의 출고: 정정(4)·취소(5)를 MA111로
→ 그 뒤, 반품·폐기: MA113 반송신청 → MA114 결과 → 승인 뒤 업무포털에서 반송보고
MA112의 처리 상태는 2(처리중), 3(점검완료), 4(접수완료)입니다. MA114의 신청 상태는 0(반려), 1(신청), 2(승인), 3(완료)입니다. 반송 승인은 하루 세 번(09:30, 13:30, 17:30)이고, 승인 뒤 최종 보고(반송보고, 보고안함)는 API가 없어 업무포털에서 합니다.
보고 값 규칙
| 항목 | 규칙 |
|---|---|
| 공급구분 | 1 출고, 2 반품, 3 폐기, 4 정정, 5 취소. 공급구분마다 따로 보냅니다 |
| 정정·취소 | 원 출고 줄의 접수번호와 연번(을지 연번 포함)을 씁니다. 일련번호 부착 줄은 을지를 함께 보내야 접수됩니다 |
| 유효기간 | YYMMDD 6자리. 8자리는 기재 오류입니다 |
| 을지 RFID 칸 | 숫자 13자리만 받습니다. 묶음 바코드(박스·상위포장)는 묶음번호 칸으로 보냅니다 |
| 일련번호 부착 품목 | 을지 일련번호 수가 공급수량과 같아야 합니다 |
| 폐기 | 공급금액·단가 0, 공급받은자는 자사 또는 폐기업체·보건소 |
| 단가 오류(DC·DE·DH) | 반송사유코드를 적어 다시 보내면 접수됩니다 |
| 비고 | 갑지 비고 칸을 보냅니다. 공급일자 예외 코드(ZQ, ZC)가 여기 들어갑니다 |
실제로 확인한 KPIS 동작
개발 서버(2026-10-21, 10-26)와 운영 서버(2026-10-27) 실측입니다.
- 부분 접수가 없습니다. 묶음 안 한 줄만 틀려도 묶음 전체가 성공 0입니다. 기재(형식) 오류면 접수번호도 없고, 전산(마스터 대조) 오류면 접수번호는 나오지만 접수되지 않습니다.
- 중복을 막지 않습니다. 같은 내용을 다시 보내면 새 접수번호로 또 접수됩니다. 이 시스템이 결과 미확인 상태와 이미 접수 검사로 막습니다.
- 오류 항목은 최대 50개까지만 옵니다. 결과의 반송 수는 줄 수가 아니라 오류 항목 수입니다. 오류 항목마다 가이드에 없는 갑지 연번이 붙습니다.
- 을지 2만 개(본문 약 2.6MB)는 접수되고 3만 개(약 3.9MB)부터 HTTP 410으로 거절됩니다.
- MA110 집계 조회는 공급구분 4(정정)를 받지 않습니다. 공급구분을 비우면 출고·반품·폐기만 나옵니다.
- MA110 응답에 목록이 없으면 ‘데이타없음’이라고 답했을 때만 0건으로 봅니다. 그 밖은 조회 오류로 봅니다.
- KPIS는 정정·취소의 원 줄을 접수번호와 연번으로만 찾고 내용은 대조하지 않습니다. 같은 줄을 두 번 취소해도 둘 다 접수되므로 이 시스템이 중복을 막습니다.
참고: MA110 집계가 정정·취소를 어떻게 반영하는지는 운영에서 아직 보지 못했습니다(저장소
docs/kpis-report-api.md기록). 정정은 바뀐 값으로, 취소는 빠진 것으로 가정했습니다.
내부 API 묶음
화면과 KPI.는 웹 서버 API를 씁니다. 모든 API는 로그인이 필요합니다.
| 묶음 | 하는 일 |
|---|---|
| 보고 | 보고 설정, 날짜 요약, 결과 미확인 묶음과 정리, 다시 보낼 반송 줄, 실행 이력, 운영 기록 |
| 날짜 관제 | 날짜 상태, 원천 조회·다시 싣기·새 줄 싣기, 보고 계획, 반송신청 목록, 수기보고 기록, 엑셀 다운로드 발급 |
| 집계·대조 | KPIS 집계 받기, 주문·바코드·KPIS 대조, 주문·KPIS 대조, 폐기 대조, 대조 검토 기록 |
| 공급 분석 | 공급 현황 집계, 적기보고율, 입고내역, 표준코드 마스터 갱신 |
| KPIS 조회 중계 | 조회계 서비스 호출(REST, SOAP, WSDL) |
| 공급내역 수집 | 바코드 서버 조회와 진행 상태 |
| 데이터소스 | 수집 경로 설정, 연결 시험, 수집 활동 로그 |
읽기는 승인 사용자도 씁니다. 데이터를 바꾸거나 KPIS로 보내는 요청은 모두 관리자만 합니다. KPIS로 나가는 요청과 수집 요청에는 호출 한도가 걸립니다.
KPI. 화면 안에서 부를 때는 KPI. 서버가 사용자 토큰과 역할을 확인한 뒤 요청마다 짧은 유효시간의 권한증명을 서명해 붙입니다. 웹 서버는 서명, 사용자, 경로, 본문을 확인하고 같은 증명을 두 번 받지 않습니다.
확인 기준: 2026-11-18, KPIS-DSR-API 저장소(
crates/kpis-server/src/kpis/mod.rs,docs/kpis-report-api.md) 기준.