납부확인서 발급 - 사회보험통합징수포털

1. 사회보험통합징수포털 납부확인서 발급si4n.payment_confirmation.issue

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: real_test

데모입니다. 실제 기관에 접속하며 가입한 날부터 30일 동안 사용자 기준 하루 10 사용 토큰까지 호출할 수 있습니다(KST 0시 초기화).

4대보험 납부확인서를 보험 종류와 기간을 골라 발급하고 문서로 받습니다. 실제 발급이라 되돌릴 수 없고, 다시 호출하면 한 번 더 발급됩니다. 문서에는 기관이 비밀번호를 설정합니다.

이 작업은 샌드박스를 지원하지 않습니다. 샌드박스로 보내면 거절되므로 데모나 정식 환경으로 호출합니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 이 작업은 지원하지 않습니다 `real_test`데모 — 하루 10 사용 토큰 `production`정식 — 스탠다드, PRO 또는 멀티계정 요금제 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `si4n`이 API 고정값 (기본값) 예시 : si4n
action	string	-	Y	호출할 작업입니다. `si4n.payment_confirmation.issue`이 API 고정값 (기본값) 예시 : si4n.payment_confirmation.issue
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	필수	설명
insurance	string	Y	발급할 보험입니다. health - 건강, pension - 국민연금, employment - 고용, industrial_accident - 산재, combined - 4대보험 합산 중 하나이며, combined 는 기관에 합산고지 신청 이력이 있어야 발급되고 employment 와 industrial_accident 는 기관 화면에서 발급 대상으로 확인되는 사업장만 발급됩니다
certificate_kind	string	Y	납부확인서 종류 코드이며 insurance 에 따라 받는 값이 다르고 맞지 않으면 입력 오류로 거절합니다. health 는 21, 23(개인별, 월 범위 최대 석 달이고 기관 화면이 알리는 인원이 50명을 넘거나 기관의 추가 회원 로그인이 필요하면 발급되지 않습니다), pension 은 국문 32(선택한 연도), 33(같은 해 월 범위), 35(연도 범위)와 영문 34(같은 해 월 범위), 36(연도 범위), employment 는 30, industrial_accident 는 40, combined 는 22(연도별), 24(월별)입니다
usage	string	N	발급 용도 코드입니다. health 는 11(납부증명), 12(연말정산), 13 중 하나가 필수이고, pension 은 21(납부증명용), 22(연말정산용) 중 하나가 필수이되 certificate_kind 32 이면 보내지 않으며, employment, industrial_accident, combined 는 11 만 받습니다. health 에서 12 를 고르면 month_from 은 1, month_to 는 12 여야 합니다
language	string	Y	발급 언어입니다. 1 - 국문, 2 - 영문이며 영문은 health 와 pension(34, 36)에서만 받고 employment, industrial_accident, combined 는 1 만 받습니다. 2 이면 firm_english_name 과 english_name 을 함께 보내야 합니다
insu_type	string	N	건강보험 세부 보험 코드입니다. insurance 가 health 일 때만 필수로 받고 다른 보험에서는 보내지 않으며, 00 - 건강보험료와 장기요양보험료, 01 - 건강보험료, 02 - 요양장기보험료 중 하나이고 usage 가 11 이 아니면 00 이어야 합니다
year	number	Y	발급 연도를 네 자리 정수로 보냅니다. 2014년부터 올해(한국 시간 기준)까지 받으며, certificate_kind 35, 36 에서는 연도 범위의 시작 연도이고 그 밖에는 발급할 해(월 범위가 있으면 그 월이 속한 해)입니다
year_to	number	N	연도 범위의 끝 연도입니다. certificate_kind 가 35, 36 일 때만 필수로 받고 year 이상 올해 이하여야 하며, 다른 종류에서는 보내지 않습니다
month_from	number	N	발급 시작 월(1에서 12)입니다. health, pension 33, 34, employment, industrial_accident, combined 24 에서 필수이고 pension 32, 35, 36 과 combined 22 에서는 보내지 않으며, month_to 보다 클 수 없습니다
month_to	number	N	발급 종료 월(1에서 12)입니다. month_from 과 같은 경우에 필수이고 month_from 이상이어야 하며, certificate_kind 23 은 month_from 부터 석 달 이내(차이 2 이하)이고 health 의 usage 12 는 12 여야 합니다
month_sum_item	string	N	발급 유형 선택 값으로 1 또는 2 입니다. health 의 certificate_kind 23 이나 combined 일 때만 받고, 그때 기관 화면이 내놓는 선택지에 없으면 입력 오류로 거절하며, 보내지 않으면 기관 화면에 선택돼 있는 값을 씁니다
firm_english_name	string	N	영문 발급에 보내는 영문 상호입니다. language 가 2 이면 다른 영문 칸과 함께 반드시 보내고(빈 값 불가), 1 이면 보내지 않습니다
english_name	string	N	영문 발급에 함께 보내는 영문 이름입니다. language 가 2 이면 다른 영문 칸과 함께 반드시 보내고(빈 값 불가), 1 이면 보내지 않습니다
confirm	boolean	Y	실제로 발급한다는 확인값으로 true 를 보냅니다. 빠지거나 false 처럼 참이 아닌 값이면 기관에 아무것도 보내지 않고 무엇을 발급할지 보여 주는 미리보기와 함께 확인이 필요하다고 답하므로, 사용자 동의를 받은 뒤 같은 요청에 true 를 넣어 다시 호출합니다. 1 이나 yes, on 처럼 true 로 읽히는 값도 바로 발급되므로 동의를 받기 전에는 이 칸을 보내지 않습니다. 발급을 취소하는 기능은 없고, 다시 실행하면 납부확인서가 한 번 더 발급됩니다

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header 'Idempotency-Key: demo-issue-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "si4n",
  "action": "si4n.payment_confirmation.issue",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "insurance": "<필수>",
    "certificate_kind": "<필수>",
    "language": "<필수>",
    "year": "<필수: number>",
    "confirm": "<필수: boolean>"
  }
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
발급한 증명서 PDF 는 result.data 가 아니라 result.artifacts 로 옵니다. result.data 에는 아래 두 칸만 있습니다.

순번	변수명	타입	설명
	outcome	string	발급이 확인됐다는 판정입니다. 성공 응답에서는 항상 confirmed 입니다. 기관에 요청은 갔지만 결과를 확인하지 못한 경우는 이 응답이 아니라 실패(PROVIDER_OUTCOME_UNCONFIRMED)로 옵니다.
	action	string	실행한 액션의 ID 입니다.

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "si4n",
    "action": "si4n.payment_confirmation.issue",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	VALIDATION_MISSING_FIELD	확인값(confirm)이 빠지거나 참이 아니면 기관에 아무것도 보내지 않고 이 오류로 끝납니다. 납부확인서 발급은 취소할 수 없어 발급 전 확인이 필요합니다. 아래 내용을 사용자에게 보여주고 동의를 받은 뒤 confirm=true 로 다시 호출해 주세요. 같은 요청에 confirm=true 만 추가해 다시 호출하면 발급합니다. 사용자 동의 없이 자동으로 채우지 마세요. error.message 에 신청 내용의 미리보기와 되돌릴 수 없다는 안내가 함께 옵니다.
	PROVIDER_OUTCOME_UNCONFIRMED	요청은 기관에 전송됐지만 처리 결과를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다. 납부확인서가 이미 발급됐을 수 있습니다. 바로 다시 실행하지 말고, 이 작업의 작업 ID를 서비스문의로 알려 발급 여부를 확인해 주세요.
	PROVIDER_BUSINESS_ERROR	기관이 신청을 거절했습니다. error.message 에 기관이 알려 준 거절 사유가 옵니다.
	AUTH_REQUIRED	저장된 기관 세션이 없습니다. 같은 연동 계정으로 si4n.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다.
	VALIDATION_INVALID_FIELD	납부확인서 발급 입력값이 고를 수 없는 조합입니다.