개발자 문서
서비스 소개키 관리자격증명 등록OpenAPI콘솔
API 레퍼런스

자격

1. 자격취득 신고 입력 초안 검증fourinsure.b1.member_qualification.acqs_draft_validate

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

가입자 자격취득 신고 입력 초안을 저장과 제출 없이 검증하고 보험별 필수 입력 상태를 반환합니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstring-Y호출할 작업입니다.
  • fourinsure.b1.member_qualification.acqs_draft_validate이 API 고정값 (기본값)

예시 : fourinsure.b1.member_qualification.acqs_draft_validate

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
selected_insurancesarrayN신청 보험
applicant_namestringN성명(한글)
resident_registration_numberstringN주민(외국인) 등록번호·국내거소신고번호
rrno_frontstringN주민등록번호 앞자리
rrno_backstringN주민등록번호 뒷자리
common_acquisition_datestringN공통 자격취득일
common_monthly_amountstring | numberN공통 월 소득액
nationality_codestringN국적 코드
nationality_namestringN국적
stay_qualification_codestringN체류자격 코드
stay_qualification_namestringN체류자격
representative_ynstring | booleanN대표자 여부
national_pensionobjectN국민연금
health_insuranceobjectN건강보험
employment_insuranceobjectN고용보험
workers_compensationobjectN산재보험
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-acqs_draft_validate-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.member_qualification.acqs_draft_validate",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'
Response
  • 저장 · 신고 없이 입력만 검증합니다. result.data 의 missing_required_fields 와 field_errors 로 고칠 항목을, workflow_gate 의 input_ready 와 can_submit_report 로 다음 단계로 갈 수 있는지 확인합니다.
순번변수명설명
success요청 처리 성공 여부
feature_name기능 식별자
phase처리 단계(draft_validate)
workflow_step처리 단계 식별자
route_kind처리 방식 — live_context_local_validation(화면 계약을 불러와 서버에서 검증)
source_url업스트림 요청 URL
current_view현재 화면 식별자
target_ready대상 폼 준비 여부
business_context사업장 컨텍스트 객체
selected_insurances검증 대상으로 고른 보험 목록
enabled_sections화면 기준 섹션 사용 가능 상태 배열(key · label · enabled)
required_fields화면 기준 필수 입력 항목 배열(field_key · label · section · required_when)
missing_required_fields빠진 필수 입력 항목 배열(required_fields 와 같은 모양)
field_errors입력 누락 · 형식 오류 배열(field_key · label · section · message)
warnings주의 메시지 배열(code · section · message · field_key)
screen_notes화면 확인 메모 배열
field_bindings입력 키와 화면 필드의 대응 맵
normalized_input정규화한 입력값 맵
draft_form_preview화면 필드에 채울 값 미리보기 맵
followup_endpoints후속 endpoint URL 배열
workflow_gate진행 판정 객체(input_ready · blocking_issue_count · can_save=false · can_submit_report · report_status · blocked_reason)
safety안전 플래그 객체(input_only=true · save_executed=false · submit_executed=false)
implementation_status구현 상태 식별자
json
// result.data
{
  "success": true,
  "feature_name": "...",
  "phase": "...",
  "workflow_step": "...",
  "route_kind": "...",
  "source_url": "...",
  "current_view": "...",
  "target_ready": true,
  "business_context": {},
  "selected_insurances": [],
  "enabled_sections": [],
  "required_fields": [],
  "missing_required_fields": [],
  "field_errors": [],
  "warnings": [],
  "screen_notes": [],
  "field_bindings": {},
  "normalized_input": {},
  "draft_form_preview": {},
  "followup_endpoints": [],
  "workflow_gate": {},
  "safety": {},
  "implementation_status": "..."
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.

2. 자격취득 입력 서식 조회fourinsure.b1.member_qualification.acqs_init

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

가입자 자격취득 신고서에 무엇을 적어야 하는지, 보험별 입력 항목과 필수 여부, 미리 채워져 있는 사업장 정보까지 한 번에 확인합니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstring-Y호출할 작업입니다.
  • fourinsure.b1.member_qualification.acqs_init이 API 고정값 (기본값)

예시 : fourinsure.b1.member_qualification.acqs_init

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

추가 파라미터가 없습니다. params 는 {} 로 보냅니다.

bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-acqs_init-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.member_qualification.acqs_init",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'
Response
  • result.data 에서 입력 항목(fields)과 다음 단계 정보를 확인해 후속 요청 본문을 만듭니다.
순번변수명설명
success요청 처리 성공 여부
page화면 페이지 메타 객체
formsform 메타데이터 배열
fields입력 필드 계약 배열
semantic_fields의미 단위 입력 컨트롤 배열
semantic_payload의미 필드 키-값 맵
semantic_field_count의미 필드 개수
csrf_token_presentCSRF 토큰 존재 여부
followup_endpoints후속 endpoint URL 배열
navigation_steps화면 내비게이션 단계 배열
current_view현재 화면 식별자
target_ready대상 폼 준비 여부
raw_html_len원본 HTML 길이
source_url업스트림 요청 URL
json
// result.data (form contract — 주요 필드)
{
  "success": true,
  "current_view": "target_form",
  "target_ready": true,
  "csrf_token_present": true,
  "semantic_field_count": 8,
  "page": {},
  "forms": [],
  "fields": [{ "tag": "input", "name": "rrnoFront", "required": true }],
  "semantic_fields": [],
  "semantic_payload": {},
  "followup_endpoints": [{ "url": "https://..." }],
  "navigation_steps": [],
  "raw_html_len": 0,
  "source_url": "https://..."
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 파라미터 값을 기관이 거부했습니다. 값을 확인합니다.

3. 가입자 내용변경 신고 입력 초안 검증fourinsure.b1.member_qualification.chg_draft_validate

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

가입자 내용변경 신고 입력 초안을 저장과 제출 없이 검증하고 변경 항목별 오류를 반환합니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstring-Y호출할 작업입니다.
  • fourinsure.b1.member_qualification.chg_draft_validate이 API 고정값 (기본값)

예시 : fourinsure.b1.member_qualification.chg_draft_validate

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
selected_insurancesarrayN반영 보험
applicant_namestringN성명
resident_registration_numberstringN-
rrno_frontstringN주민등록번호 앞자리
rrno_backstringN주민등록번호 뒷자리
change_codestringN변경부호
change_beforestringN변경전
change_afterstringN변경후
change_datestringN변경일자
modification_confirmedstring | booleanN-
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-chg_draft_validate-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.member_qualification.chg_draft_validate",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'
Response
  • 저장 · 신고 없이 입력만 검증합니다. result.data 의 missing_required_fields 와 field_errors 로 고칠 항목을, workflow_gate 의 input_ready 와 can_submit_report 로 다음 단계로 갈 수 있는지 확인합니다.
순번변수명설명
success요청 처리 성공 여부
feature_name기능 식별자
phase처리 단계(draft_validate)
workflow_step처리 단계 식별자
route_kind처리 방식 — live_context_local_validation(화면 계약을 불러와 서버에서 검증)
source_url업스트림 요청 URL
current_view현재 화면 식별자
target_ready대상 폼 준비 여부
business_context사업장 컨텍스트 객체
selected_insurances검증 대상으로 고른 보험 목록
enabled_sections화면 기준 섹션 사용 가능 상태 배열(key · label · enabled)
required_fields화면 기준 필수 입력 항목 배열(field_key · label · section · required_when)
missing_required_fields빠진 필수 입력 항목 배열(required_fields 와 같은 모양)
field_errors입력 누락 · 형식 오류 배열(field_key · label · section · message)
warnings주의 메시지 배열(code · section · message · field_key)
screen_notes화면 확인 메모 배열
field_bindings입력 키와 화면 필드의 대응 맵
normalized_input정규화한 입력값 맵
draft_form_preview화면 필드에 채울 값 미리보기 맵
followup_endpoints후속 endpoint URL 배열
workflow_gate진행 판정 객체(input_ready · blocking_issue_count · can_save=false · can_submit_report · report_status · blocked_reason)
safety안전 플래그 객체(input_only=true · save_executed=false · submit_executed=false)
implementation_status구현 상태 식별자
json
// result.data
{
  "success": true,
  "feature_name": "...",
  "phase": "...",
  "workflow_step": "...",
  "route_kind": "...",
  "source_url": "...",
  "current_view": "...",
  "target_ready": true,
  "business_context": {},
  "selected_insurances": [],
  "enabled_sections": [],
  "required_fields": [],
  "missing_required_fields": [],
  "field_errors": [],
  "warnings": [],
  "screen_notes": [],
  "field_bindings": {},
  "normalized_input": {},
  "draft_form_preview": {},
  "followup_endpoints": [],
  "workflow_gate": {},
  "safety": {},
  "implementation_status": "..."
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.

4. 가입자 내용변경 입력 서식 조회fourinsure.b1.member_qualification.chg_init

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

가입자 내용변경 신고서에 무엇을 적어야 하는지, 고를 수 있는 변경 항목과 미리 채워진 값까지 한 번에 확인합니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstring-Y호출할 작업입니다.
  • fourinsure.b1.member_qualification.chg_init이 API 고정값 (기본값)

예시 : fourinsure.b1.member_qualification.chg_init

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

추가 파라미터가 없습니다. params 는 {} 로 보냅니다.

bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-chg_init-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.member_qualification.chg_init",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'
Response
  • result.data 에서 입력 항목(fields)과 다음 단계 정보를 확인해 후속 요청 본문을 만듭니다.
순번변수명설명
success요청 처리 성공 여부
page화면 페이지 메타 객체
formsform 메타데이터 배열
fields입력 필드 계약 배열
semantic_fields의미 단위 입력 컨트롤 배열
semantic_payload의미 필드 키-값 맵
semantic_field_count의미 필드 개수
csrf_token_presentCSRF 토큰 존재 여부
followup_endpoints후속 endpoint URL 배열
navigation_steps화면 내비게이션 단계 배열
current_view현재 화면 식별자
target_ready대상 폼 준비 여부
raw_html_len원본 HTML 길이
source_url업스트림 요청 URL
json
// result.data
{
  "success": true,
  "page": {},
  "forms": [],
  "fields": [],
  "semantic_fields": [],
  "semantic_payload": {},
  "semantic_field_count": 1,
  "csrf_token_present": true,
  "followup_endpoints": [],
  "navigation_steps": [],
  "current_view": "...",
  "target_ready": true,
  "raw_html_len": 0,
  "source_url": "..."
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 파라미터 값을 기관이 거부했습니다. 값을 확인합니다.

5. 피부양자 자격 신고 입력 초안 검증fourinsure.b1.member_qualification.dependent_draft_validate

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

피부양자 자격 신고 입력 초안을 저장과 제출 없이 검증하고 취득과 상실 구분별 누락 필드를 반환합니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstring-Y호출할 작업입니다.
  • fourinsure.b1.member_qualification.dependent_draft_validate이 API 고정값 (기본값)

예시 : fourinsure.b1.member_qualification.dependent_draft_validate

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
action_divstringN-
applicant_namestringN-
resident_registration_numberstringN주민(외국인) 등록번호·국내거소신고번호
rrno_frontstringN주민등록번호 앞자리
rrno_backstringN주민등록번호 뒷자리
report_datestringN-
reporter_namestringN-
bplc_telno1stringN-
bplc_telno2stringN-
bplc_telno3stringN-
bplc_fxno1stringN-
bplc_fxno2stringN-
bplc_fxno3stringN-
home_telno1stringN-
home_telno2stringN-
home_telno3stringN-
co_telno1stringN-
co_telno2stringN-
co_telno3stringN-
mbl_telno1stringN-
mbl_telno2stringN-
mbl_telno3stringN-
dependentsarrayN-
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-dependent_draft_validate-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.member_qualification.dependent_draft_validate",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'
Response
  • 저장 · 신고 없이 입력만 검증합니다. result.data 의 missing_required_fields 와 field_errors 로 고칠 항목을, workflow_gate 의 input_ready 와 can_submit_report 로 다음 단계로 갈 수 있는지 확인합니다.
순번변수명설명
success요청 처리 성공 여부
feature_name기능 식별자
phase처리 단계(draft_validate)
workflow_step처리 단계 식별자
route_kind처리 방식 — live_context_local_validation(화면 계약을 불러와 서버에서 검증)
source_url업스트림 요청 URL
current_view현재 화면 식별자
target_ready대상 폼 준비 여부
business_context사업장 컨텍스트 객체
selected_insurances검증 대상으로 고른 보험 목록
enabled_sections화면 기준 섹션 사용 가능 상태 배열(key · label · enabled)
required_fields화면 기준 필수 입력 항목 배열(field_key · label · section · required_when)
missing_required_fields빠진 필수 입력 항목 배열(required_fields 와 같은 모양)
field_errors입력 누락 · 형식 오류 배열(field_key · label · section · message)
warnings주의 메시지 배열(code · section · message · field_key)
screen_notes화면 확인 메모 배열
field_bindings입력 키와 화면 필드의 대응 맵
normalized_input정규화한 입력값 맵
draft_form_preview화면 필드에 채울 값 미리보기 맵
followup_endpoints후속 endpoint URL 배열
workflow_gate진행 판정 객체(input_ready · blocking_issue_count · can_save=false · can_submit_report · report_status · blocked_reason)
safety안전 플래그 객체(input_only=true · save_executed=false · submit_executed=false)
implementation_status구현 상태 식별자
json
// result.data
{
  "success": true,
  "feature_name": "...",
  "phase": "...",
  "workflow_step": "...",
  "route_kind": "...",
  "source_url": "...",
  "current_view": "...",
  "target_ready": true,
  "business_context": {},
  "selected_insurances": [],
  "enabled_sections": [],
  "required_fields": [],
  "missing_required_fields": [],
  "field_errors": [],
  "warnings": [],
  "screen_notes": [],
  "field_bindings": {},
  "normalized_input": {},
  "draft_form_preview": {},
  "followup_endpoints": [],
  "workflow_gate": {},
  "safety": {},
  "implementation_status": "..."
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.

6. 피부양자 자격 취득/상실 입력 서식 조회fourinsure.b1.member_qualification.dependent_init

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

피부양자 취득과 상실 신고서에 무엇을 적어야 하는지, 입력 항목 구성과 신고일, 신고인 성명을 비롯해 항목마다 지금 들어 있는 값까지 한 번에 확인합니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstring-Y호출할 작업입니다.
  • fourinsure.b1.member_qualification.dependent_init이 API 고정값 (기본값)

예시 : fourinsure.b1.member_qualification.dependent_init

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

추가 파라미터가 없습니다. params 는 {} 로 보냅니다.

bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-dependent_init-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.member_qualification.dependent_init",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'
Response
  • result.data 에서 입력 항목(fields)과 다음 단계 정보를 확인해 후속 요청 본문을 만듭니다.
순번변수명설명
success요청 처리 성공 여부
page화면 페이지 메타 객체
formsform 메타데이터 배열
fields입력 필드 계약 배열
semantic_fields의미 단위 입력 컨트롤 배열
semantic_payload의미 필드 키-값 맵
semantic_field_count의미 필드 개수
csrf_token_presentCSRF 토큰 존재 여부
followup_endpoints후속 endpoint URL 배열
navigation_steps화면 내비게이션 단계 배열
current_view현재 화면 식별자
target_ready대상 폼 준비 여부
raw_html_len원본 HTML 길이
source_url업스트림 요청 URL
json
// result.data
{
  "success": true,
  "page": {},
  "forms": [],
  "fields": [],
  "semantic_fields": [],
  "semantic_payload": {},
  "semantic_field_count": 1,
  "csrf_token_present": true,
  "followup_endpoints": [],
  "navigation_steps": [],
  "current_view": "...",
  "target_ready": true,
  "raw_html_len": 0,
  "source_url": "..."
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 파라미터 값을 기관이 거부했습니다. 값을 확인합니다.

7. 자격상실 신고 입력 초안 검증fourinsure.b1.member_qualification.los_draft_validate

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

가입자 자격상실 신고 입력 초안을 저장과 제출 없이 검증하고 상실 사유와 일자 오류를 반환합니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstring-Y호출할 작업입니다.
  • fourinsure.b1.member_qualification.los_draft_validate이 API 고정값 (기본값)

예시 : fourinsure.b1.member_qualification.los_draft_validate

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
selected_insurancesarrayN-
applicant_namestringN-
resident_registration_numberstringN주민(외국인) 등록번호·국내거소신고번호
rrno_frontstringN주민등록번호 앞자리
rrno_backstringN주민등록번호 뒷자리
common_loss_datestringN공통 자격상실일
loss_date_modestringN-
national_pensionobjectN국민연금
health_insuranceobjectN건강보험
employment_insuranceobjectN고용보험
workers_compensationobjectN산재보험
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-los_draft_validate-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.member_qualification.los_draft_validate",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'
Response
  • 저장 · 신고 없이 입력만 검증합니다. result.data 의 missing_required_fields 와 field_errors 로 고칠 항목을, workflow_gate 의 input_ready 와 can_submit_report 로 다음 단계로 갈 수 있는지 확인합니다.
순번변수명설명
success요청 처리 성공 여부
feature_name기능 식별자
phase처리 단계(draft_validate)
workflow_step처리 단계 식별자
route_kind처리 방식 — live_context_local_validation(화면 계약을 불러와 서버에서 검증)
source_url업스트림 요청 URL
current_view현재 화면 식별자
target_ready대상 폼 준비 여부
business_context사업장 컨텍스트 객체
selected_insurances검증 대상으로 고른 보험 목록
enabled_sections화면 기준 섹션 사용 가능 상태 배열(key · label · enabled)
required_fields화면 기준 필수 입력 항목 배열(field_key · label · section · required_when)
missing_required_fields빠진 필수 입력 항목 배열(required_fields 와 같은 모양)
field_errors입력 누락 · 형식 오류 배열(field_key · label · section · message)
warnings주의 메시지 배열(code · section · message · field_key)
screen_notes화면 확인 메모 배열
field_bindings입력 키와 화면 필드의 대응 맵
normalized_input정규화한 입력값 맵
draft_form_preview화면 필드에 채울 값 미리보기 맵
followup_endpoints후속 endpoint URL 배열
workflow_gate진행 판정 객체(input_ready · blocking_issue_count · can_save=false · can_submit_report · report_status · blocked_reason)
safety안전 플래그 객체(input_only=true · save_executed=false · submit_executed=false)
implementation_status구현 상태 식별자
json
// result.data
{
  "success": true,
  "feature_name": "...",
  "phase": "...",
  "workflow_step": "...",
  "route_kind": "...",
  "source_url": "...",
  "current_view": "...",
  "target_ready": true,
  "business_context": {},
  "selected_insurances": [],
  "enabled_sections": [],
  "required_fields": [],
  "missing_required_fields": [],
  "field_errors": [],
  "warnings": [],
  "screen_notes": [],
  "field_bindings": {},
  "normalized_input": {},
  "draft_form_preview": {},
  "followup_endpoints": [],
  "workflow_gate": {},
  "safety": {},
  "implementation_status": "..."
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.

8. 자격상실 입력 서식 조회fourinsure.b1.member_qualification.los_init

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

가입자 자격상실 신고서를 작성하기 전에 정보연계센터 화면이 요구하는 입력 항목을 그대로 받아옵니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • fourinsure이 API 고정값 (기본값)

예시 : fourinsure

actionstring-Y호출할 작업입니다.
  • fourinsure.b1.member_qualification.los_init이 API 고정값 (기본값)

예시 : fourinsure.b1.member_qualification.los_init

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

추가 파라미터가 없습니다. params 는 {} 로 보냅니다.

bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-los_init-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.member_qualification.los_init",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'
Response
  • result.data 에서 입력 항목(fields)과 다음 단계 정보를 확인해 후속 요청 본문을 만듭니다.
순번변수명설명
success요청 처리 성공 여부
page화면 페이지 메타 객체
formsform 메타데이터 배열
fields입력 필드 계약 배열
semantic_fields의미 단위 입력 컨트롤 배열
semantic_payload의미 필드 키-값 맵
semantic_field_count의미 필드 개수
csrf_token_presentCSRF 토큰 존재 여부
followup_endpoints후속 endpoint URL 배열
navigation_steps화면 내비게이션 단계 배열
current_view현재 화면 식별자
target_ready대상 폼 준비 여부
raw_html_len원본 HTML 길이
source_url업스트림 요청 URL
json
// result.data
{
  "success": true,
  "page": {},
  "forms": [],
  "fields": [],
  "semantic_fields": [],
  "semantic_payload": {},
  "semantic_field_count": 1,
  "csrf_token_present": true,
  "followup_endpoints": [],
  "navigation_steps": [],
  "current_view": "...",
  "target_ready": true,
  "raw_html_len": 0,
  "source_url": "..."
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 응답이 지연되거나 형식이 올바르지 않습니다. 잠시 후 다시 호출합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 파라미터 값을 기관이 거부했습니다. 값을 확인합니다.