인증 - 사회보험통합징수포털

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

순번	변수명	타입	필수	설명
	business_registration_no	string	Y	로그인할 사업장의 사업자등록번호입니다. 붙임표 없이 숫자 10자리만 받고 그 밖의 모양은 거절합니다. 공동인증서와 비밀번호는 이 칸이 아니라 연동에 등록한 인증서에서 가져옵니다

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

Response

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

변수명	타입	설명
provider	string	기관 상품의 식별자입니다. 이 상품에서는 항상 si4n 입니다.
env_scope	string	로그인을 실행한 환경입니다. 요청에 지정한 환경이고, 지정하지 않았으면 기본 환경입니다.
account_link_id	string	로그인에 쓴 연동 계정의 ID 입니다.
session_saved	boolean	기관 세션을 저장했는지 여부입니다. 저장하지 못하면 작업이 실패하므로 성공 응답에서는 항상 true 입니다.
login_confirmed_at	string	기관 로그인을 확인한 시각입니다. UTC 기준 ISO 8601 문자열이고 응답의 finished_at(KST)과 시간대가 다릅니다.

json

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

순번	오류 코드	발생 조건
	PROVIDER_AUTH_FAILED	연결된 공동인증서를 확인하지 못했습니다. 인증서를 다시 연결해 주세요.
	INTERNAL_ERROR	지금은 이 상품을 처리할 수 없습니다. 서버 구성 문제로 요청을 실행하지 못했습니다. 서비스문의로 알려 주세요.
	VALIDATION_INVALID_FIELD	사업자등록번호(business_registration_no)는 숫자 열 자리로 보내 주세요.
	VALIDATION_INVALID_FIELD	연결된 공동인증서 정보를 불러오지 못했습니다. 인증서를 다시 연결해 주세요.
	VALIDATION_INVALID_FIELD	공동인증서 서명에 필요한 입력이 비어 있습니다. 인증서 연결 정보를 확인해 주세요.
	PROVIDER_UNAVAILABLE	보안 프로그램이 이 사이트 주소를 인식하지 못했습니다. 잠시 후 다시 시도해 주세요. 반복되면 서비스문의로 알려 주세요. (서버 설정 문제이며 사용하시는 PC 문제가 아닙니다.)
	PROVIDER_UNAVAILABLE	보안 프로그램에 전달한 값의 형식이 올바르지 않습니다. 잠시 후 다시 시도해 주세요. 반복되면 서비스문의로 알려 주세요.
	PROVIDER_UNAVAILABLE	보안 프로그램이 요청한 기능을 제공하지 않습니다. 잠시 후 다시 시도해 주세요. 반복되면 서비스문의로 알려 주세요. (서버 설정 문제이며 사용하시는 PC 문제가 아닙니다.)
	PROVIDER_UNAVAILABLE	설치된 보안 프로그램 버전이 이 기능을 지원하지 않습니다. 잠시 후 다시 시도해 주세요. 반복되면 서비스문의로 알려 주세요. (서버 설정 문제이며 사용하시는 PC 문제가 아닙니다.)
	PROVIDER_AUTH_FAILED	등록하신 공동인증서를 찾지 못했습니다. 인증서 유효기간이 지나지 않았는지, 등록하신 인증서 파일이 손상되지 않았는지 확인해 주세요. 문제가 없다면 콘솔에서 인증서를 다시 등록한 뒤 시도해 주세요.
	PROVIDER_AUTH_FAILED	등록하신 공동인증서 목록을 가져오지 못했습니다. 콘솔에서 인증서가 정상적으로 등록되어 있는지 확인해 주세요. 등록되어 있지 않다면 발급기관에서 재발급받은 인증서를 다시 등록해 주세요.
	PROVIDER_AUTH_FAILED	인증서 비밀번호 확인 요청이 거부되었습니다. 인증서 비밀번호를 다시 확인해 주세요. 비밀번호가 맞는데도 반복되면 서비스문의로 알려 주세요.
	PROVIDER_UNAVAILABLE	보안 프로그램에서 알 수 없는 오류가 발생했습니다. 잠시 후 다시 시도해 주세요. 반복되면 오류 코드와 함께 서비스문의로 알려 주세요. (서버 설정 문제이며 사용하시는 PC 문제가 아닙니다.)
	PROVIDER_UNAVAILABLE	공동인증서 서명 처리(AnySign) 중 일시적인 서비스 오류가 발생했습니다. 잠시 후 다시 시도해 주세요. 반복되면 서비스문의로 알려 주세요.
	PROVIDER_UNAVAILABLE	공동인증서 서명 중 알 수 없는 오류가 발생했습니다. 잠시 후 다시 시도해 주세요. 반복되면 서비스문의로 알려 주세요.
	PROVIDER_UNAVAILABLE	공동인증서 서명 결과가 올바르지 않습니다. 인증서를 다시 연결한 뒤 시도해 주세요.
	PROVIDER_UPSTREAM_ERROR	공동인증서 보안 프로그램 설정을 확인하지 못했습니다. 잠시 후 다시 시도해 주시고, 계속되면 서비스문의로 알려 주세요.
	PROVIDER_UPSTREAM_ERROR	지금은 로그인을 진행할 수 없습니다. 잠시 후 다시 시도해 주시고, 계속되면 서비스문의로 알려 주세요.
	PROVIDER_BUSINESS_ERROR	개인사업장 회원이 아니어서 사업장 공동인증서로 로그인할 수 없습니다. 연동한 인증서와 회원 유형이 맞는지 확인해 주세요.
	PROVIDER_BUSINESS_ERROR	가입된 사업장 회원을 찾을 수 없습니다. 사회보험통합징수포털에 사업장 회원으로 가입한 뒤 다시 시도해 주세요.
	PROVIDER_BUSINESS_ERROR	이 사업장에 회원 아이디가 여러 개여서 지원하지 않습니다. 작업 ID와 함께 서비스문의로 알려 주세요.
	PROVIDER_UPSTREAM_ERROR	로그인 처리가 끝나지 않았습니다. 잠시 후 다시 시도해 주세요.
	PROVIDER_UPSTREAM_ERROR	로그인 세션 정보를 받지 못했습니다. 잠시 후 다시 시도해 주세요.
	PROVIDER_UNAVAILABLE	로그인은 됐지만 세션을 저장하지 못했습니다. 잠시 후 다시 시도해 주세요.
	PROVIDER_UPSTREAM_ERROR	로그인 처리 중 오류가 발생했습니다. 잠시 후 다시 시도해 주시고, 계속되면 서비스문의로 알려 주세요.

인증 - 사회보험통합징수포털

1. 사회보험통합징수포털 로그인si4n.session.login

Request

Response