API 레퍼런스

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

KPIS API 분류

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

조회 API (MA101MA110, MA117MA118)

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

등록 API (MA111~MA116, MA119)

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

핵심 업무 흐름

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

인증 이원화

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

API KEY 인증 (조회)

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

JWT + 공동인증서 (등록)

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

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)에 저장합니다.

인증서 정보 확인

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

만료 알림

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

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

주요 내부 엔드포인트

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

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

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

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

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

사용자 관리 (/api/users)

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

Rate Limiting 정책

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

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

테넌트별 API 키 관리

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

API 설정 변경

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

KPIS API 환경

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

다음 단계

• 데이터베이스 — SQLite 테이블 구조 및 동기화
• 문제 해결 — API 연동 실패 대응