Skip to Content
권대환매뉴얼

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거래처 정보 조회조회
MA103RFID 태그 정보 조회조회
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) 기준.