의약품 공급내역보고 (KPIS-DSR-API)
제약사가 매일 출고·반품·폐기한 의약품 공급내역을 심평원 의약품관리종합정보센터(KPIS)에 보고하는 사내 업무 시스템입니다. 바코드 서버에서 공급내역(갑지·을지)을 받아 주문 내역과 맞춘 뒤 KPIS OpenAPI로 보고하고, 보고한 뒤에도 주문 내역과 KPIS 집계를 다시 견줘 바뀐 줄을 기한 안에 정정합니다. 영업관리 담당자가 공급내역보고 업무에 씁니다.
현재 상태: 운영 중입니다. 2026-10-27부터 KPIS 보고 API로 운영 보고를 하고 있고(첫 운영 보고는 그날 출고 126줄, 접수됨), 2026-11-17부터 Rust로 다시 만든 서버가 화면과 API를 냅니다. 근거는 저장소 AGENTS.md의 보고 API 운영 시작 기록, PR #242(서버 Rust 전환), 2026-11-18에 확인한 서버 서비스 상태입니다.
주요 기능
이 시스템이 하는 일은 다음과 같습니다.
- 공급 자료 적재: KPI.(사내 영업관리 시스템)가 물류 마감을 알리면 마감일과 앞 14일을 바코드 서버 원천과 대조해 달라진 날만 다시 싣습니다. 사람이 고쳤거나 보고한 날은 덮지 않습니다.
- 보내기 전 주문 대조: 보고할 줄을 주문 내역(ERP)과 공급구분·거래처·표준코드 묶음별로 견주고, 다르면 주문 값으로 고치거나 빼 둡니다.
- API 보고: 공급구분별로 보고 계획을 만들어 KPIS에 보내고 접수 결과를 확인합니다. 물류 마감 적재 직후와 밤 11시에 자동으로 보고할 수 있습니다.
- 보낸 뒤 대조와 정정: 보고 1분 뒤 KPIS 집계를 다시 받아 주문과 견주고, 판매 마감 뒤에는 최근 30일을 다시 검사해 바뀐 줄을 정정·취소로 보냅니다.
- 반송 처리: 반송된 줄의 사유와 해결 방법을 보여 주고, 고친 줄만 다시 보고합니다. 기한이 지난 줄은 반송신청으로 고칩니다.
- 현황판: 날짜별 보고 상태, 분기 적기보고율, 주문·바코드·KPIS 날짜별 대조, 공급 현황을 한 화면에서 봅니다.
하루 흐름
자동으로 도는 단계와 사람이 확인하는 단계가 나뉩니다.
| 단계 | 하는 일 | 누가 |
|---|---|---|
| 원본 수집 | 물류 마감 뒤 바코드 서버 원천을 대조해 싣기 | 자동 |
| 보내기 전 주문 대조 | 주문 값으로 수량·금액을 맞추고, 못 맞추는 줄은 빼 두기 | 자동 |
| 보고 계획·보내기 | 사전점검과 이미 접수 검사를 거쳐 KPIS로 보내기 | 자동 또는 관리자 |
| 접수 확인 | 접수·반송·결과 미확인 기록 | 자동. 결과 미확인 정리는 관리자 |
| 반송·정정 | 반송 줄을 고쳐 다시 보고하고, 기한 지난 줄은 반송신청 | 사람이 고치고 자동 또는 관리자가 보냄 |
| 보낸 뒤 대조 | 최근 30일 주문과 KPIS 집계를 대조하고 바뀐 줄을 정정·취소 | 자동 |
| 적기보고율 | 분기 적기보고율이 목표 95% 아래로 내려가면 기록 | 자동 |

위 그림은 KPI.의 KPIS 메뉴에 있는 보고 흐름 안내 화면입니다. 각 단계가 실제로 어떻게 도는지는 자동 보고 흐름에 정리했습니다.
구성
| 영역 | 사용 기술 |
|---|---|
| 화면 | React 19, Vite 7, TypeScript, Tailwind CSS 4, TanStack Table |
| 서버 | Rust(axum 0.8, tokio). 화면 정적 파일과 API를 함께 냅니다 |
| 데이터베이스 | Supabase(PostgreSQL). KPI.와 같은 데이터베이스를 씁니다 |
| 공급내역 원천 | 바코드 서버(MSSQL). 읽기만 합니다 |
| 주문 내역 | KPI.의 판매 상세 자료 |
| 외부 연계 | KPIS OpenAPI. 보고는 JWT, 조회는 서비스별 API KEY |
| 운영 | 사내 Linux 서버의 systemd 서비스 두 개(웹 서버, 물류 마감 적재기) |
KPI.와의 연결
KPI.의 KPIS 메뉴는 이 시스템을 화면 안에 열어 씁니다. 이때는 KPI.의 로그인과 권한을 이어받습니다. KPI. 영업지원 홈은 이 시스템이 내는 날짜 상태(보고 상태, 마지막 검사 결과, 주문·KPIS 대조)를 받아 최근 3개월의 확인할 날을 모아 보여 줍니다.

사례 설명은 포트폴리오의 공급내역보고 사례에 있습니다.
어디서부터 읽을까
| 하려는 일 | 읽을 쪽 |
|---|---|
| 처음 로그인하고 화면 구성을 익히기 | 시작하기 |
| 아침에 전날 보고가 잘 됐는지 보기 | 매일 보고 상태 확인하기 |
| 날짜를 골라 직접 보고하기 | KPIS에 보고하기 |
| 반송된 줄을 고쳐 다시 보내기 | 반송 줄 고쳐 다시 보고하기 |
| 주문과 KPIS가 다른 거래처 찾기 | 주문·KPIS 대조 확인하기 |
| 공급 자료를 다시 받거나 엑셀로 올리기 | 공급 자료 가져오기 |
| 갑지·을지 칸을 직접 고치기 | 갑지·을지 고치기 |
| KPIS 연동 키·자동 보고·사용자 설정 | 설정과 사용자 관리하기 |
| 자동 보고가 언제 무엇을 하는지 알기 | 자동 보고 흐름 |
| 서버 구성과 배포 순서 | 구성과 배포 |
| 장애가 났을 때 | 문제 해결 |
변경 이력
처음에는 엑셀로 공급내역을 수작업 보정했습니다. 매일 보고가 주사제 8개 품목의 표준코드·포장내수량 불일치로 반송된 적이 있었고, 규격수량·공급수량·단가를 고치던 기존 업무 기준을 먼저 엑셀 자동화로, 다음에 이 웹 시스템의 검증·보정 기능으로 옮겼습니다. 새 보고 기준을 만든 것이 아니라 있던 기준을 자동화한 것입니다.
이후 ERP와 공급내역보고 프로그램이 함께 바뀌었는데, 새 보고 프로그램의 오류가 3개월 넘게 이어졌습니다. 그동안 이 웹 시스템으로 보고 업무를 이어 갔고, 이어서 보고 API 연계를 만들었습니다.
2026-10에 보내기 전 주문 대조, KPIS 보고 API(10-27 운영 시작), 보고 뒤 대조와 자동 정정으로 넓혔습니다. 자동으로 판정하기 어려운 예외는 사람이 확인해 승인합니다. 2026-11에는 폐기를 바코드 원천과 대조하고(11-04), 표준코드가 틀린 줄에 정정 안을 제시하며(11-13), 서버를 Express에서 Rust로 옮겼습니다(11-17). 화면은 예전에 Vercel에서 따로 냈지만 지금은 같은 서버가 냅니다. 쓰지 않던 공동인증서 기능은 2026-11-18에 지웠습니다.
확인 기준: 2026-11-18, KPIS-DSR-API 저장소 기준.