Skip to Content
KPIS DSR API운영자 매뉴얼문제 해결

문제 해결

시스템 운영 중 발생할 수 있는 주요 문제의 원인과 해결 방법을 안내합니다.

엑셀 업로드 실패

파일 형식 오류

증상원인해결
”지원하지 않는 파일 형식”.xls(구버전), .csv 등 업로드.xlsx 형식으로 변환 후 재업로드
”열 수가 맞지 않습니다”갑지가 21열 미만이거나 을지가 3열 미만원본 엑셀의 열 구조 확인 — 헤더 행 없이 첫 행부터 데이터
”날짜를 추출할 수 없습니다”파일명에 날짜 패턴 없음파일명에 YYYY-MM-DD, YYYYMMDD, YY-MM-DD, YYMMDD 중 하나 포함

인코딩 문제

증상원인해결
제품명/거래처명이 깨져 보임엑셀 파일 인코딩 불일치Excel에서 .xlsx로 다시 저장 (UTF-8 기본)
특수문자가 ?로 표시한글 외 특수문자 인코딩 손실원본 데이터에서 특수문자 확인 후 수정

파일 크기 제한

대용량 파일 업로드 시 타임아웃이 발생할 수 있습니다.

항목제한
파일 크기Nginx 설정의 client_max_body_size 확인
행 수제한 없음 (메모리 허용 범위)
동시 업로드같은 날짜 동시 업로드 시 후순위 덮어쓰기

표준코드 매핑 오류

코드매핑이 적용되지 않는 경우

증상원인해결
이전에 매핑한 제품인데 자동 적용 안 됨공급구분(탭)이 다름코드매핑은 탭별 독립 관리 — 해당 탭에서 매핑 등록
제품명이 미세하게 다름띄어쓰기, 괄호, 규격 표기 차이제품명 정확 일치 필요 — 코드매핑 목록에서 확인
매핑을 등록했는데 다른 코드가 적용됨동일 제품에 여러 매핑 존재usage_count가 높은 매핑이 우선 — 불필요한 매핑 삭제

표준코드 조회 실패

증상원인해결
”표준코드를 찾을 수 없습니다”Supabase 마스터 DB에 미등록MA101 API로 KPIS에서 최신 코드 조회 후 마스터 업데이트
검색 결과가 없음마스터 데이터 미적재마스터데이터 재업로드 또는 바코드/엑셀 소스 동기화 확인
만료된 표준코드cancel_date가 설정된 코드MA101로 후속 코드 확인, 해당 코드는 사용 불가

KPIS API 연동 실패

인증서 관련

증상원인해결
전송 버튼이 비활성화인증서 만료 또는 미등록관리자 > 인증서 관리에서 유효한 .pfx 업로드
”인증서 비밀번호가 올바르지 않습니다”업로드 시 비밀번호 오입력인증서 삭제 후 올바른 비밀번호로 재업로드
”인증서 서명 실패”인증서 파일 손상 또는 형식 오류.pfx 파일 유효성 확인 후 재발급
SOAP 호출 시 401 응답JWT 토큰 만료서버 재시작으로 토큰 재발급, 또는 kpis_jwt_tokens 테이블 초기화

인증서 만료 예방

인증서 갱신 권장 일정:

시점조치
D-30갱신 인증서 발급 신청 시작
D-7갱신 인증서 수령 확인, 테스트 환경에서 검증
D-1운영 서버에 새 인증서 업로드 완료

네트워크 관련

증상원인해결
”ECONNREFUSED” 또는 타임아웃KPIS 서버 점검 또는 네트워크 장애KPIS 공지사항 확인, 시간 후 재시도
”ENOTFOUND”DNS 해석 실패Oracle Cloud 서버의 DNS 설정 확인
API 호출은 되지만 응답이 비어있음KPIS 서버 부분 장애다른 API(MA101 등 조회)로 서버 상태 확인
특정 API만 실패IP 화이트리스트 문제Oracle Cloud 서버의 공인 IP가 KPIS에 등록되어 있는지 확인

IP 화이트리스트 확인

KPIS API는 등록된 IP에서만 호출 가능합니다.

# Oracle Cloud 서버에서 외부 IP 확인
curl -s ifconfig.me

표시된 IP가 KPIS에 등록한 IP와 일치하는지 확인합니다. 불일치 시 KPIS 관리자에게 IP 변경 신청이 필요합니다.

API 응답 코드

응답의미대응
200정상 (데이터 내용은 별도 확인)—
401인증 실패API KEY, JWT, 인증서 확인
403권한 없음 (IP 미등록 포함)화이트리스트 확인
429Rate Limit 초과잠시 후 재시도
500KPIS 서버 오류KPIS 관리자 문의
503서비스 일시 중단KPIS 점검 일정 확인

반송 처리 대응 (DC001~DC007)

MA112 결과에서 반송된 건의 코드별 대응 방법입니다.

DC001: 표준코드 불일치

원인: 존재하지 않거나 만료된 표준코드를 사용했습니다.

해결 절차:

  1. MA101 API로 해당 제품의 올바른 표준코드 조회
  2. cancel_date가 설정된 코드인지 확인
  3. 표준코드 수정 후 MA113 반송신청

DC002: 미등록 거래처

원인: KPIS에 등록되지 않은 거래처 사업자번호입니다.

해결 절차:

  1. MA102 API로 거래처 등록여부 확인
  2. 사업자등록번호 오타 확인 (10자리)
  3. 미등록 거래처면 KPIS 포털에서 거래처 등록 선행

DC003: 보고기간 외 공급일자

원인: 공급일자가 해당 분기 보고기간 범위를 벗어났습니다.

해결 절차:

  1. MA116 API로 해당 분기의 보고기간 조회
  2. 공급일자(N열)가 보고기간 내인지 확인
  3. 기간 외 공급건은 해당 분기로 이동하여 재제출

DC004: 중복보고

원인: 이미 등록된 동일 데이터가 존재합니다.

해결 절차:

  1. MA112로 기등록 건의 접수번호 확인
  2. 재제출이 아닌 정정(공급구분 4) 또는 **취소(공급구분 5)**로 처리
  3. MA113 반송신청은 사용하지 않음

DC004는 다른 반송코드와 달리 MA113이 아닌 정정/취소로 처리해야 합니다.

DC005: 수량/금액 오류

원인: 단가 x 수량 ≠ 금액 정합성이 맞지 않습니다.

해결 절차:

  1. 해당 행의 단가(P열), 수량(M열), 금액(O열) 확인
  2. 단가 x 수량 = 금액 (1원 이내 오차 허용) 검증
  3. 불일치 시 단가 또는 수량 수정 (금액은 불변)

DC006: 을지 누락

원인: 일련번호구분(U열)이 0(부착)인데 을지 데이터가 없습니다.

해결 절차:

  1. 해당 연번의 을지 데이터 존재 확인
  2. 을지 파일이 누락되었으면 재업로드
  3. 일련번호가 불필요한 품목이면 일련번호구분을 1(생략)로 변경

DC007: 요양기관기호 오류

원인: 공급형태가 9(요양기관)인데 요양기관기호가 누락되었거나 형식이 다릅니다.

해결 절차:

  1. 공급형태(F열) = 9 확인
  2. 요양기관기호(I열)가 8자리인지 확인
  3. 건강보험심사평가원에서 올바른 요양기관기호 조회 후 수정

서버 장애 대응

서버 상태 확인

# PM2 프로세스 상태 확인
pm2 status

# Express 서버 로그 확인
pm2 logs kpis-dsr-api --lines 50

# 서버 리소스 확인
df -h          # 디스크 용량
free -m        # 메모리

서버 재시작

# PM2로 재시작
pm2 restart kpis-dsr-api

# 재시작 후 상태 확인
pm2 status
curl -s http://localhost:3002/api/health

Supabase 연결 장애

Supabase 셀프호스팅 서버(sb.dvsharp.com)에 접근 불가한 경우:

# Supabase 서버 응답 확인
curl -s https://sb.dvsharp.com/rest/v1/ -H "apikey: YOUR_ANON_KEY"

# Docker 컨테이너 상태 확인 (Supabase 서버에서)
docker ps

로컬 DB (cert_config) 장애

# local.db 파일 존재 확인
ls -lh data/local.db

# 파일 권한 확인
stat data/local.db

Nginx 관련

증상원인해결
502 Bad GatewayExpress 서버 다운pm2 restart kpis-dsr-api
504 Gateway TimeoutExpress 응답 지연대량 데이터 처리 중일 수 있음 — 로그 확인
413 Request Entity Too Large업로드 파일 크기 초과Nginx client_max_body_size 값 증가

Vercel 프론트엔드 장애

증상원인해결
화면은 뜨지만 API 호출 실패Oracle Cloud 서버 다운 또는 Vercel rewrites 문제서버 상태 확인, vercel.json rewrites 설정 확인
빌드 실패코드 오류 또는 환경변수 누락Vercel 대시보드에서 빌드 로그 확인

공통 진단 절차

문제 발생 시 아래 순서로 진단합니다.

  1. PM2 상태 확인: pm2 status — 서버가 실행 중인지 확인
  2. 서버 로그 확인: pm2 logs kpis-dsr-api --lines 100 — 에러 메시지 확인
  3. API 응답 테스트: curl http://localhost:3002/api/health — 서버 정상 동작 확인
  4. Supabase 연결: 브라우저에서 sb.dvsharp.com 접근 가능 여부
  5. 네트워크: curl -s ifconfig.me — 외부 IP 확인, KPIS 연결 테스트

다음 단계

Last updated on
데이터베이스