Skip to Content
KPIS DSR API운영자 매뉴얼API 레퍼런스

API 레퍼런스

시스템 내부 REST API와 KPIS OpenAPI 연동 구조, 인증 방식, 공동인증서 관리를 설명합니다.

KPIS API 분류

KPIS OpenAPI는 기능에 따라 조회와 등록 두 그룹으로 나뉘며, 인증 방식이 다릅니다.

조회 API (MA101MA110, MA117MA118)

마스터 데이터와 등록 결과를 조회하는 읽기 전용 API입니다.

ID엔드포인트설명
MA101getMsupStdCdInfo.do표준코드마스터 정보 조회
MA102getMsupBscqInfo.do거래처 정보 조회
MA103getMsupRfidInfo.doRFID Tag 정보 조회
MA104getMsupBnoInfo.do바코드번호(최소번호) 조회
MA105getMsupSnoInfo.do바코드번호(일련번호) 조회
MA106getMsupSnoDtlInfo.do바코드번호(일련번호 상세) 조회
MA107getMsupRfidMultiInfo.do다건 RFID tag 정보 조회
MA109getRiskMsupInfo.do회수의약품 반송마스터(EB) 정보 조회
MA110getMsupBriefSummary01Info.do공급내역 정보 조회
MA117getMsupNtfcItemInq.do의약품관련 상세정보 조회
MA118getMsupStdCdChgHstInfo.do표준코드 변경이력 조회(전체)

등록 API (MA111~MA116, MA119)

공급내역 제출, 반송신청, 입고내역 조회 등 업무 처리 API입니다.

ID엔드포인트설명
MA111regMsupSplyDtlDrt공급내역 정보 직접 등록
MA112getMsupSplyDtlRgstResult공급내역 등록 결과 조회
MA113regRpayMsupCmmDrt반송신청 직접 등록
MA114getRpayMsupCmmRgstResult반송요청 등록 결과 조회
MA115getMsupWrhsDtlInfo입고내역 정보 조회(페이지)
MA116getMsupQrtrRptPrdInfo분기별 보고기간 조회
MA119getMsupWrhsDtlListInfo입고내역 정보 조회(목록)

핵심 업무 흐름

MA116 보고기간 조회
  → MA101 표준코드 검증
    → MA111 공급내역 등록
      → MA112 결과 조회
        → (반송 시) MA113 반송신청
          → MA114 결과 조회

인증 이원화

KPIS API는 호출 유형에 따라 인증 방식이 완전히 다릅니다.

API KEY 인증 (조회)

조회 API는 요청 파라미터에 apiKey와 aplHbin(사업자등록번호)을 포함하여 호출합니다.

항목설명
대상 APIMA101MA110, MA117MA118
인증 방식REST 요청 파라미터 (apiKey + aplHbin)
프록시 경로server/routes/kpisProxy.ts
설정 위치관리자 > API 설정 패널

JWT + 공동인증서 (등록)

등록 API는 서버에서 JWT 토큰을 발급받고, 공동인증서로 SOAP 메시지에 전자서명하여 호출합니다.

항목설명
대상 APIMA111~MA116, MA119
인증 방식JWT(Authorization: Bearer) + WS-Security 전자서명
프록시 경로server/routes/kpisJwtProxy.ts
서명 라이브러리node-forge (RSA-SHA256)

JWT 발급 과정

  1. 서버 환경변수의 CLIENT_ID/CLIENT_SECRET으로 KPIS 인증 서버에 토큰 요청
  2. 발급된 JWT를 Authorization: Bearer {jwt} 헤더에 포함
  3. 토큰은 DB(jwt_tokens 테이블)에 캐싱하여 재사용
  4. 만료 시 자동 재발급

JWT 자격 증명은 서버 환경변수로만 관리합니다. 클라이언트에 절대 노출되지 않습니다.

공동인증서 관리

MA111~MA116 등록 API 호출 시 필수인 공동인증서(.pfx)의 관리 절차입니다.

인증서 업로드

관리자(admin 역할)만 인증서를 업로드할 수 있습니다.

  1. 관리자 > 인증서 관리 메뉴에 접속합니다.
  2. .pfx 파일을 선택하고 비밀번호를 입력합니다.
  3. 업로드 버튼을 클릭합니다.
  4. 서버가 인증서를 AES-256-CBC로 암호화하여 DB(cert_config)에 저장합니다.

인증서 정보 확인

업로드된 인증서의 메타 정보를 확인할 수 있습니다.

항목설명
주체(Subject CN)인증서 소유자
발급자(Issuer CN)인증기관
유효기간(Valid From ~ To)인증서 사용 가능 기간
일련번호(Serial)인증서 고유 식별자
업로드 일시서버에 등록한 시각

만료 알림

인증서 만료 임박 시 단계별로 알림을 제공합니다.

상태조건UI 표시
ok만료일 31일 이상 남음초록색 배지
warn-30만료 30일 이하노란색 배지
warn-7만료 7일 이하주황색 배지 + toast 경고
warn-1만료 1일 이하빨간색 배지 + toast 긴급
expired만료됨빨간색 배지 + 전송 버튼 비활성화

인증서 만료는 KPIS 자동보고 기능의 즉시 중단으로 이어집니다. D-30부터 갱신을 시작하는 것을 권장합니다.

주요 내부 엔드포인트

시스템 내부에서 사용하는 REST API 목록입니다.

날짜별 보고 관리 (/api/gap-data)

Method엔드포인트설명
GET/api/gap-data/calendar보고 상태 달력 (?from=YYYY-MM-DD&to=YYYY-MM-DD)
GET/api/gap-data/:date날짜별 갑지/을지 데이터 조회
POST/api/gap-data/upload갑지/을지 파일 업로드 (multipart)
PUT/api/gap-data/:date/flush메모리 데이터를 DB에 동기화
PUT/api/gap-data/:date/receipt접수번호 배치 업데이트
PUT/api/gap-data/:date/error제출 실패 기록
POST/api/gap-data/ignore날짜별 미보고 무시 등록
DELETE/api/gap-data/ignore/:date미보고 무시 해제

표준코드 (/api/standard-codes)

Method엔드포인트설명
GET/api/standard-codes/count마스터 건수 (바코드/엑셀별 구분)
GET/api/standard-codes/search표준코드 검색 (?keyword=..., 최대 10건)
GET/api/standard-codes/:stdCd13자리 코드로 정확 조회

검색 3단계: 정확 일치 → LIKE → FTS5 전문 검색 순서로 수행됩니다.

코드매핑 (/api/code-mappings)

Method엔드포인트설명
GET/api/code-mappings전체 또는 탭별 조회 (?supplyType=1)
POST/api/code-mappings제품명-표준코드 매핑 저장
DELETE/api/code-mappings/:productName/:standardCode매핑 삭제
GET/api/code-mappings/:productName특정 제품의 최근 매핑 조회

사용자 관리 (/api/users)

Method엔드포인트권한설명
GET/api/usersadmin전체 사용자 목록
PATCH/api/users/:userId/approveadmin사용자 승인
PATCH/api/users/:userId/roleadmin역할 변경 (admin / user)

인증서 관리 (/api/cert-config)

Method엔드포인트권한설명
GET/api/cert-config/meta로그인인증서 주체/만료일/상태
POST/api/cert-config/uploadadmin.pfx + 비밀번호 업로드
DELETE/api/cert-configadmin인증서 삭제
POST/api/kpis/soap로그인SOAP 프록시 (서명 후 전송)

Rate Limiting 정책

KPIS API 과도한 호출을 방지하기 위해 서버에 Rate Limiting이 적용되어 있습니다.

항목설명
적용 범위모든 /api/* 엔드포인트
제한 방식express-rate-limit (IP 기반)
테넌트 단위특정 테넌트의 과도한 호출이 전체 시스템에 영향을 주지 않도록 격리
재시도호출 간격과 재시도 횟수를 제한하여 KPIS 서버 부하 방지

Rate Limit 초과 시 429 Too Many Requests 응답이 반환됩니다. 잠시 후 다시 시도하세요.

테넌트별 API 키 관리

고객사(테넌트)마다 별도의 KPIS API 키를 사용합니다.

항목설명
API KEY테넌트 설정에서 관리, 하드코딩 금지
사업자등록번호 (aplHbin)테넌트별 사업자 정보
JWT 자격 증명CLIENT_ID/CLIENT_SECRET — 서버 환경변수
인증서테넌트별 .pfx 파일 — DB 암호화 저장

API 설정 변경

  1. 관리자 > API 설정 메뉴에 접속합니다.
  2. 사업자등록번호와 API KEY를 입력합니다.
  3. API KEY는 BASE64 암호화되어 DB(api_config)에 저장됩니다.
  4. 저장 후 조회 API(MA101 등)가 즉시 동작합니다.

KPIS API 환경

환경URL용도
개발http://devopenapi.kpis.or.kr테스트/개발
운영https://newopenapi.kpis.or.kr실제 보고

운영 환경은 Oracle Cloud 서버의 Floating IP가 KPIS 화이트리스트에 등록되어 있어야 호출 가능합니다.

다음 단계

Last updated on
배포데이터베이스