조회 - 사회보험통합징수포털

이 쪽의 모든 작업에 해당

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

1. 사회보험통합징수포털 보험료 조회si4n.premium.inquiry

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

변수명	타입	필수	설명
view	string	Y	조회 방식입니다. by_insurance - 보험 하나를 골라 보는 보험별 조회(insurance_type 필수)이고, regular_batch 와 batch 는 보험을 고르지 않는 기관 화면의 다른 두 조회 구분이며 insurance_type 을 보내지 않습니다
insurance_type	string	N	보험별 조회에서 볼 보험입니다. view 가 by_insurance 일 때만 필수로 받고 다른 view 에서는 보내지 않으며(null 도 불가), health - 건강보험, pension - 연금보험, employment - 고용보험, industrial_accident - 산재보험 중 하나입니다
output_formats	array	N	이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다

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-inquiry-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "si4n",
  "action": "si4n.premium.inquiry",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "view": "<필수>"
  }
}'

Response

아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.

변수명	타입	설명
view	string	조회 방식입니다. 요청한 view 와 같습니다.
insurance_type	string \| null	view 가 by_insurance 일 때는 요청한 보험 종류이고, 그 밖에는 null 입니다.
summary	array	정기고지 표입니다. 건강보험, 연금보험, 고용보험, 산재보험 순서로 항상 네 행이 옵니다.
summary[].insurance	string	「보험구분」 값입니다. 값은 health(건강보험), pension(연금보험), employment(고용보험), industrial_accident(산재보험) 중 하나입니다.
summary[].regular_notice_year_month	string	「정기고지년월」 값입니다. YYYY-MM 형식의 문자열입니다.
summary[].regular_notice_amount_krw	number	「정기고지금액」 값입니다. 원 단위 정수입니다.
summary[].regular_notice_paid	boolean	「납부여부」 값입니다. true 는 기관 화면의 Y 이고 false 는 N 입니다.
arrears	array	미납내역 표입니다. summary 와 같은 순서로 항상 네 행이 옵니다.
arrears[].insurance	string	「보험구분」 값입니다. 값은 health(건강보험), pension(연금보험), employment(고용보험), industrial_accident(산재보험) 중 하나입니다. 기관 미납내역 표에는 보험 칸이 없어 summary 의 같은 순서 행과 같은 값이 옵니다.
arrears[].period_from	string \| null	「미납시작년월」 값입니다. YYYY-MM 형식의 문자열입니다. 미납이 없으면 null 입니다.
arrears[].period_to	string \| null	「미납종료년월」 값입니다. YYYY-MM 형식의 문자열입니다. 미납이 없으면 null 입니다.
arrears[].amount_krw	number	「미납금액」 값입니다. 원 단위 정수입니다. 미납이 없으면 0 입니다.
auto_debit	array	자동이체 표입니다. 보험마다 한 행씩 네 행이 오고 순서는 기관 화면을 따릅니다.
auto_debit[].insurance	string	「보험구분」 값입니다. 값은 health(건강보험), pension(연금보험), employment(고용보험), industrial_accident(산재보험) 중 하나입니다.
auto_debit[].enabled	boolean	「자동이체여부」 값입니다. true 는 기관 화면의 Y 이고 false 는 N 입니다.
amount_schema	string	고지내역(items)의 금액 구성입니다. abc 는 보험료(A), 연체금(B), 체납처분비등(C)과 그 합계이고, abcd 는 보험료(A), 연체금(B), 급여징수금등(C), 체납처분비(D)와 그 합계입니다. view 가 by_insurance 이면 insurance_type 이 health, pension 일 때 abc 이고 employment, industrial_accident 일 때 abcd 이며, view 가 regular_batch 나 batch 이면 abcd 입니다.
items	array	고지내역 표의 행 목록입니다. 한 행 이상 옵니다.
items[].insurance	string	「보험구분」 값입니다. 값은 health(건강보험), pension(연금보험), employment(고용보험), industrial_accident(산재보험) 중 하나입니다. view 가 by_insurance 이면 모든 행이 요청한 보험입니다.
items[].notice_year_month	string	「고지년월」 값입니다. YYYY-MM 형식의 문자열입니다.
items[].notice_kind	string	「고지종류」 값입니다. 값은 regular(정기분), arrears(미납분) 중 하나입니다.
items[].total_amount_krw	number	「합계」 값입니다. 원 단위 정수이고 보험료, 연체금, 나머지 금액 칸의 합과 같습니다.
items[].premium_amount_krw	number	「보험료」 값입니다. 원 단위 정수입니다.
items[].late_fee_amount_krw	number	「연체금」 값입니다. 원 단위 정수입니다.
items[].delinquency_disposition_fee_etc_amount_krw	number \| null	「체납처분비등」 값입니다. 원 단위 정수입니다. 금액 구성이 abc 일 때만 값이 오고 abcd 이면 null 입니다. 기관 칸이 비어 있어도 null 입니다.
items[].wage_collection_etc_amount_krw	number \| null	「급여징수금등」 값입니다. 원 단위 정수입니다. 금액 구성이 abcd 일 때만 값이 오고 abc 이면 null 입니다. 기관 칸이 비어 있어도 null 입니다.
items[].delinquency_disposition_fee_amount_krw	number \| null	「체납처분비」 값입니다. 원 단위 정수입니다. 금액 구성이 abcd 일 때만 값이 오고 abc 이면 null 입니다.
installment_plans	array \| null	분할 납부 신청 내역입니다. view 가 by_insurance 일 때는 항상 빈 배열이고, 그 밖에는 null 입니다.

json

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

순번	오류 코드	발생 조건
	AUTH_REQUIRED	저장된 기관 세션이 없습니다. 같은 연동 계정으로 si4n.session.login 을 먼저 실행해 세션을 연 뒤 다시 보냅니다.
	PROVIDER_SESSION_EXPIRED	기관 세션이 만료됐습니다. 같은 연동 계정으로 si4n.session.login 을 다시 실행해 세션을 연 뒤 다시 보냅니다.
	VALIDATION_INVALID_FIELD	보험료 조회 입력값이 올바르지 않습니다. view는 by_insurance, regular_batch, batch 중 하나여야 하며, insurance_type은 view가 by_insurance일 때만 health, pension, employment, industrial_accident 중 하나로 입력합니다. 값을 확인한 뒤 다시 요청해 주세요.
	PROVIDER_UPSTREAM_ERROR	보험료 조회 화면이 지원하는 형식과 달라 결과를 확인하지 못했습니다. 잠시 후 다시 시도해 주시고, 계속되면 서비스문의로 알려 주세요.
	PROVIDER_BUSINESS_ERROR	조회 요청이 처리되지 못했습니다. 잠시 후 다시 시도해 주시고, 계속되면 서비스문의로 알려 주세요.

2. 사회보험통합징수포털 보험료 산출내역 조회si4n.premium_calculation.inquiry