개발자 문서
API 레퍼런스

자격 - 4대보험

1. 공통코드 목록 조회fourinsure.b1.common.com_cd.list

MCP 도구 이름 fourinsure__b1__common__com_cd__list

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

분류 아이디 하나를 넣으면 기관 코드 찾기 창에 보이는 그 분류의 공통코드를 코드 값과 이름의 짝으로 돌려줍니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

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

[참고] 재시도

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

예시 : fourinsure

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

예시 : fourinsure.b1.common.com_cd.list

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
com_cd_clsf_idstringY공통코드 분류 id(예: B112, D114, A101)
insurance_sestringN보험 구분 필터(선택)
levy_codestringN부과 구분 코드 필터(선택)
workplace_se_codestringN사업장 구분 코드 필터(선택)
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: list-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.common.com_cd.list",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "com_cd_clsf_id": "<필수>"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 의 items(행마다 code 와 name)로 com_cd_clsf_id 분류의 코드 목록을 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
com_cd_clsf_idstring조회한 공통코드 분류 id
itemsarray조회 결과 행 배열
save_executedboolean기관 저장 수행 여부(조회라 항상 false)
source_urlstring서버가 요청한 기관 화면 주소
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "fourinsure",
    "action": "fourinsure.b1.common.com_cd.list",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
PROVIDER_VALIDATION_ERROR코드 없음 — 그 분류에 코드가 하나도 없으면 빈 목록이 아니라 이 오류로 끝납니다. com_cd_clsf_id 를 확인합니다.
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
VALIDATION_INVALID_FIELD필수 칸 누락 — 필수 칸(com_cd_clsf_id)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다.

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

MCP 도구 이름 fourinsure__b1__member_qualification__acqs_draft_validate

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

입사자의 성명과 주민등록번호, 자격취득일, 보험별 값을 넣으면 저장 없이 점검해 빠진 항목과 형식 오류, 신고 가능 여부를 돌려줍니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • params 를 빈 객체로 보내도 작업은 성공하지만, 그러면 필수 입력이 missing_required_fields 로 돌아오고 workflow_gate.input_ready 가 false 입니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

  • 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
순번변수명타입필수설명
selected_insurancesarrayN신고할 보험 목록(national_pension, health_insurance, employment_insurance, workers_compensation)
applicant_namestringN대상자 성명(한글)
resident_registration_numberstringN주민등록번호
rrno_frontstringN주민등록번호 앞자리
rrno_backstringN주민등록번호 뒷자리
common_acquisition_datestringN공통 자격취득일
common_monthly_amountstring | numberN공통 월 소득액. 저장할 때는 0 보다 큰 값을 입력해야 합니다
nationality_codestringN국적 코드
nationality_namestringN국적
stay_qualification_codestringN체류자격 코드
stay_qualification_namestringN체류자격
representative_ynstring | booleanN대표자 여부
national_pensionobjectN국민연금
national_pension.monthly_income_amountstring | numberN국민연금 소득월액 생략 시 기본값: null
national_pension.acquisition_datestringN국민연금 자격취득일 생략 시 기본값: ""
national_pension.acquisition_reason_codestringN국민연금 자격취득부호 생략 시 기본값: ""
national_pension.acquisition_reason_namestringN국민연금 자격취득 사유 이름입니다. 생략 시 기본값: ""
national_pension.acquisition_month_payment_ynstring | booleanN국민연금 취득월납부여부 생략 시 기본값: null
national_pension.special_occupation_codestringN국민연금 특수직종부호 생략 시 기본값: ""
national_pension.special_occupation_namestringN국민연금 특수직종 이름입니다. 생략 시 기본값: ""
national_pension.special_pension_codestringN국민연금 직역연금부호 생략 시 기본값: ""
national_pension.special_pension_namestringN특수직역연금 이름입니다. 생략 시 기본값: ""
health_insuranceobjectN건강보험
health_insurance.monthly_income_amountstring | numberN건강보험 보수월액 생략 시 기본값: null
health_insurance.acquisition_datestringN건강보험 자격취득일 생략 시 기본값: ""
health_insurance.acquisition_reason_codestringN건강보험 자격취득부호 생략 시 기본값: ""
health_insurance.acquisition_reason_namestringN건강보험 자격취득 사유 이름입니다. 생략 시 기본값: ""
health_insurance.reduction_codestringN건강보험 감면부호 생략 시 기본값: ""
health_insurance.reduction_namestringN건강보험 감면부호명 생략 시 기본값: ""
health_insurance.account_division_codestringN건강보험 회계코드 생략 시 기본값: ""
health_insurance.account_division_namestringN건강보험 회계명 생략 시 기본값: ""
health_insurance.occupation_codestringN건강보험 직종코드 생략 시 기본값: ""
health_insurance.occupation_namestringN건강보험 직종명 생략 시 기본값: ""
employment_insuranceobjectN고용보험
employment_insurance.average_salary_amountstring | numberN고용보험 월평균 보수 생략 시 기본값: null
employment_insurance.acquisition_datestringN고용보험 자격취득일 생략 시 기본값: ""
employment_insurance.occupation_codestringN고용보험 직종 생략 시 기본값: ""
employment_insurance.occupation_namestringN고용보험 직종명 생략 시 기본값: ""
employment_insurance.weekly_work_hoursstring | numberN고용보험 1주 소정근로시간 생략 시 기본값: null
employment_insurance.remark_codestringN고용보험 비고코드 생략 시 기본값: ""
employment_insurance.remark_namestringN고용보험 비고명 생략 시 기본값: ""
employment_insurance.contract_worker_ynstring | booleanN고용보험 계약직 여부 생략 시 기본값: null
employment_insurance.contract_end_year_monthstringN고용보험 계약종료연월 생략 시 기본값: ""
employment_insurance.levy_codestringN고용보험 보험료 부과구분 부호 생략 시 기본값: ""
employment_insurance.levy_namestringN고용보험 보험료 부과구분 부호명 생략 시 기본값: ""
employment_insurance.levy_reason_codestringN고용보험 보험료 부과구분 사유코드 생략 시 기본값: ""
employment_insurance.levy_reason_namestringN고용보험 보험료 부과구분 사유명 생략 시 기본값: ""
workers_compensationobjectN산재보험
workers_compensation.average_salary_amountstring | numberN산재보험 월평균 보수 생략 시 기본값: null
workers_compensation.acquisition_datestringN산재보험 자격취득일 생략 시 기본값: ""
workers_compensation.occupation_codestringN산재보험 직종코드 생략 시 기본값: ""
workers_compensation.occupation_namestringN산재보험 직종명 생략 시 기본값: ""
workers_compensation.weekly_work_hoursstring | numberN산재보험 1주 소정근로시간 생략 시 기본값: null
workers_compensation.remark_codestringN산재보험 비고코드 생략 시 기본값: ""
workers_compensation.remark_namestringN산재보험 비고명 생략 시 기본값: ""
workers_compensation.contract_worker_ynstring | booleanN산재보험 계약직 여부 생략 시 기본값: null
workers_compensation.contract_end_year_monthstringN산재보험 계약종료연월 생략 시 기본값: ""
workers_compensation.levy_codestringN산재보험 보험료 부과구분 부호 생략 시 기본값: ""
workers_compensation.levy_namestringN산재보험 보험료 부과구분 부호명 생략 시 기본값: ""
workers_compensation.levy_reason_codestringN산재보험 보험료 부과구분 사유코드 생략 시 기본값: ""
workers_compensation.levy_reason_namestringN산재보험 보험료 부과구분 사유명 생략 시 기본값: ""
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: acqs_draft_validate-$(date +%s)-$RANDOM" \
  --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 로 다음 단계로 갈 수 있는지 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
feature_namestring기능 식별자
phasestring처리 단계(draft_validate)
workflow_stepstring처리 단계 식별자
route_kindstring처리 방식 — live_context_local_validation(화면 계약을 불러와 서버에서 검증)
source_urlstring서버가 요청한 기관 화면 주소
current_viewstring현재 화면 식별자
target_readyboolean대상 폼 준비 여부
business_contextobject사업장 컨텍스트 객체
selected_insurancesarray검증 대상으로 고른 보험 목록
enabled_sectionsarray화면 기준 섹션 사용 가능 상태 배열(key · label · enabled)
required_fieldsarray화면 기준 필수 입력 항목 배열(field_key · label · section · required_when)
missing_required_fieldsarray빠진 필수 입력 항목 배열(required_fields 와 같은 모양)
field_errorsarray입력 누락 · 형식 오류 배열(field_key · label · section · message)
warningsarray주의 메시지 배열(code · section · message · field_key)
screen_notesarray화면 확인 메모 배열
field_bindingsobject입력 키와 화면 필드의 대응 맵
normalized_inputobject정규화한 입력값 맵
draft_form_previewobject화면 필드에 채울 값 미리보기 맵
followup_endpointsarray기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다
workflow_gateobject진행 판정 객체(input_ready · blocking_issue_count · can_save=false · can_submit_report · report_status · blocked_reason)
safetyobject안전 플래그 객체(input_only=true · save_executed=false · submit_executed=false)
implementation_statusstring구현 상태 식별자
json
// result.data
{
  "success": true,
  "feature_name": "...",
  "phase": "draft_validate",
  "workflow_step": "member_qualification_acquisition_draft_validated",
  "route_kind": "live_context_local_validation",
  "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": "implemented_input_only_draft_validation"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.

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

MCP 도구 이름 fourinsure__b1__member_qualification__acqs_init

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

가입자 자격취득 신고서 화면을 열어 미리 채워진 사업장 정보와 보험별 가입 여부, 수정할 수 없는 항목을 돌려줍니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : 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: real_test' \
  --header "Idempotency-Key: acqs_init-$(date +%s)-$RANDOM" \
  --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)과 화면 정보를 확인해 다음 단계(fourinsure.b1.member_qualification.acqs_draft_validate, fourinsure.b1.member_qualification.acqs_member_lookup, fourinsure.b1.member_qualification.acqs_precheck, fourinsure.b1.member_qualification.acqs_save)의 요청 본문을 만듭니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
pageobject화면 페이지 메타 객체
formsarrayform 메타데이터 배열
fieldsarray입력 필드 계약 배열
semantic_fieldsarray의미 단위 입력 컨트롤 배열
semantic_payloadobject의미 필드 키-값 맵
semantic_field_countnumber의미 필드 개수
csrf_token_presentbooleanCSRF 토큰 존재 여부
followup_endpointsarray기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다
navigation_stepsarray화면 내비게이션 단계 배열
current_viewstring현재 화면 식별자
target_readyboolean대상 폼 준비 여부
raw_html_lennumber원본 HTML 길이
source_urlstring서버가 요청한 기관 화면 주소
json
// result.data (form contract — 주요 필드)
{
  "success": true,
  "current_view": "target_form",
  "target_ready": true,
  "csrf_token_present": true,
  "semantic_field_count": 52,
  "page": {},
  "forms": [],
  "fields": [{ "tag": "input", "name": "dclrmst[cvrcNo]", "required": false }],
  "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업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.

4. 자격취득 가입자 조회fourinsure.b1.member_qualification.acqs_member_lookup

MCP 도구 이름 fourinsure__b1__member_qualification__acqs_member_lookup

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

입사자의 성명과 주민등록번호를 넣으면 자격취득 초안 저장에 쓸 자격키와 보험별 기존 취득일, 상실일을 돌려줍니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • 가입자를 찾지 못하면 작업은 성공하고 lookup_ok 가 false, rrkey 는 빈 값입니다. 기관 안내 문장이 있으면 alert_message 에 옵니다.
  • REST 요청 표와 MCP 도구 규격의 필수 표시가 다릅니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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_member_lookup이 API 고정값 (기본값)

예시 : fourinsure.b1.member_qualification.acqs_member_lookup

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
applicant_namestring-Y대상자 성명(한글)
resident_registration_numberstring-조건부주민등록번호 13자리
rrno_frontstring-조건부주민등록번호 앞자리
rrno_backstring-조건부주민등록번호 뒷자리
declaration_apply_datestring8N신고 적용일(비우면 기관 화면 값을 쓴다)

형식 : YYYYMMDD

bpmnostring-N사업장관리번호(비우면 기관 화면 값을 쓴다)
cvrc_nostring-N작성 중인 초안의 접수번호(없으면 비운다)
up_cvrc_nostring-N상위 접수번호(비우면 기관 화면 값을 쓴다)
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: acqs_member_lookup-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.member_qualification.acqs_member_lookup",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "applicant_name": "<필수>",
    "resident_registration_number": "<필수>"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • 기관에 저장하거나 신고하지 않는 조회입니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
lookup_okboolean가입자를 찾았는지 여부(false 면 rrkey 가 빈 값)
alert_messagestring기관이 돌려준 안내 문장(없으면 빈 값)
rrkeystring가입자 자격키, 같은 신고의 다음 조회에 그대로 넣는 값
applicant_namestring조회한 대상자 성명
rrno_maskedstring가린 주민등록번호
representative_ynboolean대표자 여부
is_familystring가족 여부 표시(기관 값 그대로)
status_codestring상태 코드
existsobject보험별 존재 표시 맵(기관이 돌려준 값 그대로)
qualification_acquisition_datesobject보험별 기존 자격취득일 맵
qualification_loss_datesobject보험별 기존 자격상실일 맵
save_executedboolean기관 저장 수행 여부(조회라 항상 false)
source_urlstring서버가 요청한 기관 화면 주소
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "fourinsure",
    "action": "fourinsure.b1.member_qualification.acqs_member_lookup",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
VALIDATION_INVALID_FIELD필수 칸 누락 — 필수 칸(applicant_name)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다.

5. 자격취득 사전 확인fourinsure.b1.member_qualification.acqs_precheck

MCP 도구 이름 fourinsure__b1__member_qualification__acqs_precheck

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

자격취득 신고서를 쓰기 전에 상위 접수번호를 넣으면 그 번호에 이미 작성된 건수를 돌려줍니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • 유효한 상위 접수번호로 확인한 작성 건수가 없으면 count 가 0, check_applicable 이 true 로 옵니다. 실패가 아닙니다.
  • 작업은 성공하고 result.data 의 check_applicable 이 false, count 는 0, up_cvrc_no 는 빈 값입니다.
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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_precheck이 API 고정값 (기본값)

예시 : fourinsure.b1.member_qualification.acqs_precheck

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
up_cvrc_nostringN확인할 상위 접수번호(비우면 기관 화면 값을 쓴다. 화면에도 없으면 확인 대상이 아니라고 답한다)
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: acqs_precheck-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.member_qualification.acqs_precheck",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • 기관에 저장하거나 신고하지 않는 확인입니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
up_cvrc_nostring확인한 상위 접수번호
check_applicableboolean사전 확인 대상인지 여부. 상위 접수번호가 요청에도 자격취득 화면에도 없으면 false 이고 기관에 묻지 않습니다. 이때 count 는 0 이지만 확인한 결과가 아닙니다.
countnumber상위 접수번호에 이미 작성된 건수
save_executedboolean기관 저장 수행 여부(조회라 항상 false)
source_urlstring서버가 요청한 기관 화면 주소
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "fourinsure",
    "action": "fourinsure.b1.member_qualification.acqs_precheck",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.

6. 자격취득 초안 저장fourinsure.b1.member_qualification.acqs_save

MCP 도구 이름 fourinsure__b1__member_qualification__acqs_save

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

입사자 자격키와 성명, 주민등록번호, 자격취득일, 월 보수, 건강보험 취득부호, 고용보험 직종을 넣으면 자격취득 신고서를 정보연계센터에 초안으로 저장하고 접수번호를 받습니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • dry_run 을 true 로 보내면 기관에 보내지 않고 저장할 내용을 result.data 의 preview 로 돌려줍니다(save_executed=false).
  • REST 요청 표와 MCP 도구 규격의 필수 표시가 다릅니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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_save이 API 고정값 (기본값)

예시 : fourinsure.b1.member_qualification.acqs_save

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채우고 resident_registration_number 또는 rrno_front 중 하나 이상, resident_registration_number 또는 rrno_back 중 하나 이상, common_acquisition_date 또는 hire_date 중 하나 이상, common_monthly_amount 또는 monthly_wage 중 하나 이상을 함께 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

  • 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
순번변수명타입길이필수설명
selected_insurancesarray-N신고할 보험 목록(national_pension, health_insurance, employment_insurance, workers_compensation, 기본은 네 보험 모두, 이미 취득 중인 보험은 뺀다)
applicant_namestring-Y대상자 성명(한글)
resident_registration_numberstring-조건부주민등록번호 13자리
rrno_frontstring-조건부주민등록번호 앞자리
rrno_backstring-조건부주민등록번호 뒷자리
common_acquisition_datestring8조건부자격취득일(입사일)

형식 : YYYYMMDD

common_monthly_amountstring | number-조건부공통 월 소득액. 저장할 때는 0 보다 큰 값을 입력해야 합니다
nationality_codestring-N국적 코드
nationality_namestring-N국적
stay_qualification_codestring-N체류자격 코드
stay_qualification_namestring-N체류자격
representative_ynstring | boolean-N대표자 여부
national_pensionobject-N국민연금
national_pension.monthly_income_amountstring | number-N국민연금 소득월액 생략 시 기본값: null
national_pension.acquisition_datestring-N국민연금 자격취득일 생략 시 기본값: ""
national_pension.acquisition_reason_codestring-N국민연금 자격취득부호 생략 시 기본값: ""
national_pension.acquisition_reason_namestring-N국민연금 자격취득 사유 이름입니다. 생략 시 기본값: ""
national_pension.acquisition_month_payment_ynstring | boolean-N국민연금 취득월납부여부 생략 시 기본값: null
national_pension.special_occupation_codestring-N국민연금 특수직종부호 생략 시 기본값: ""
national_pension.special_occupation_namestring-N국민연금 특수직종 이름입니다. 생략 시 기본값: ""
national_pension.special_pension_codestring-N국민연금 직역연금부호 생략 시 기본값: ""
national_pension.special_pension_namestring-N특수직역연금 이름입니다. 생략 시 기본값: ""
health_insuranceobject-N건강보험 취득 사유. 코드와 이름을 둘 다 입력합니다. 코드는 4대보험 공통코드 목록 조회 결과에서 받습니다
health_insurance.monthly_income_amountstring | number-N건강보험 보수월액 생략 시 기본값: null
health_insurance.acquisition_datestring-N건강보험 자격취득일 생략 시 기본값: ""
health_insurance.acquisition_reason_codestring-조건부건강보험을 신고할 때 꼭 보내는 취득 사유 코드입니다(예: 00). 이름과 함께 보내야 하고 없으면 저장하지 않고 거절합니다. selected_insurances 를 보내지 않으면 건강보험도 신고합니다
health_insurance.acquisition_reason_namestring-조건부위 코드에 해당하는 건강보험 취득 사유 이름입니다. 코드와 이름을 둘 다 보내야 하며 하나만 보내도 저장하지 않고 거절합니다
health_insurance.reduction_codestring-N건강보험 감면부호 생략 시 기본값: ""
health_insurance.reduction_namestring-N건강보험 감면부호명 생략 시 기본값: ""
health_insurance.account_division_codestring-N건강보험 회계코드 생략 시 기본값: ""
health_insurance.account_division_namestring-N건강보험 회계명 생략 시 기본값: ""
health_insurance.occupation_codestring-N건강보험 직종코드 생략 시 기본값: ""
health_insurance.occupation_namestring-N건강보험 직종명 생략 시 기본값: ""
employment_insuranceobject-N고용보험
employment_insurance.average_salary_amountstring | number-N고용보험 월평균 보수 생략 시 기본값: null
employment_insurance.acquisition_datestring-N고용보험 자격취득일 생략 시 기본값: ""
employment_insurance.occupation_codestring-N고용보험 직종 생략 시 기본값: ""
employment_insurance.occupation_namestring-N고용보험 직종명 생략 시 기본값: ""
employment_insurance.weekly_work_hoursstring | number-N고용보험 1주 소정근로시간 생략 시 기본값: null
employment_insurance.remark_codestring-N고용보험 비고코드 생략 시 기본값: ""
employment_insurance.remark_namestring-N고용보험 비고명 생략 시 기본값: ""
employment_insurance.contract_worker_ynstring | boolean-N고용보험 계약직 여부 생략 시 기본값: null
employment_insurance.contract_end_year_monthstring-N고용보험 계약종료연월 생략 시 기본값: ""
employment_insurance.levy_codestring-N고용보험 보험료 부과구분 부호 생략 시 기본값: ""
employment_insurance.levy_namestring-N고용보험 보험료 부과구분 부호명 생략 시 기본값: ""
employment_insurance.levy_reason_codestring-N고용보험 보험료 부과구분 사유코드 생략 시 기본값: ""
employment_insurance.levy_reason_namestring-N고용보험 보험료 부과구분 사유명 생략 시 기본값: ""
workers_compensationobject-N산재보험
workers_compensation.average_salary_amountstring | number-N산재보험 월평균 보수 생략 시 기본값: null
workers_compensation.acquisition_datestring-N산재보험 자격취득일 생략 시 기본값: ""
workers_compensation.occupation_codestring-N산재보험 직종코드 생략 시 기본값: ""
workers_compensation.occupation_namestring-N산재보험 직종명 생략 시 기본값: ""
workers_compensation.weekly_work_hoursstring | number-N산재보험 1주 소정근로시간 생략 시 기본값: null
workers_compensation.remark_codestring-N산재보험 비고코드 생략 시 기본값: ""
workers_compensation.remark_namestring-N산재보험 비고명 생략 시 기본값: ""
workers_compensation.contract_worker_ynstring | boolean-N산재보험 계약직 여부 생략 시 기본값: null
workers_compensation.contract_end_year_monthstring-N산재보험 계약종료연월 생략 시 기본값: ""
workers_compensation.levy_codestring-N산재보험 보험료 부과구분 부호 생략 시 기본값: ""
workers_compensation.levy_namestring-N산재보험 보험료 부과구분 부호명 생략 시 기본값: ""
workers_compensation.levy_reason_codestring-N산재보험 보험료 부과구분 사유코드 생략 시 기본값: ""
workers_compensation.levy_reason_namestring-N산재보험 보험료 부과구분 사유명 생략 시 기본값: ""
rrkeystring-Y자격취득 가입자 조회 결과의 rrkey
cmdstring-N저장 구분(Regist 신규, Modify 수정)
cvrc_nostring-N수정할 초안의 접수번호(cmd 가 Modify 일 때 필수)
hire_datestring-조건부입사일(common_acquisition_date 대신 보낼 수 있다)
monthly_wagestring | number-조건부월 보수액(common_monthly_amount 대신 보낼 수 있다)
weekly_work_hoursstring | number-N주 소정근로시간(비우면 40)
epi_occupation_codestring-N고용보험 직종 코드(공통코드 목록 조회로 받는다, 고용보험을 신고할 때 필수)
epi_occupation_namestring-N고용보험 직종 이름(고용보험을 신고할 때 필수)
iai_occupation_codestring-N산재보험 직종 코드(비우면 고용보험 직종을 쓴다)
iai_occupation_namestring-N산재보험 직종 이름(비우면 고용보험 직종을 쓴다)
nps_qlfc_acqs_ymdstring-N국민연금 기존 자격취득일(가입자 조회 결과, 상실일 없이 있으면 그 보험은 신고에서 뺀다)
nhi_qlfc_acqs_ymdstring-N건강보험 기존 자격취득일(가입자 조회 결과, 상실일 없이 있으면 그 보험은 신고에서 뺀다)
epi_qlfc_acqs_ymdstring-N고용보험 기존 자격취득일(가입자 조회 결과, 상실일 없이 있으면 그 보험은 신고에서 뺀다)
iai_qlfc_acqs_ymdstring-N산재보험 기존 자격취득일(가입자 조회 결과, 상실일 없이 있으면 그 보험은 신고에서 뺀다)
nps_qlfc_los_ymdstring-N국민연금 기존 자격상실일(가입자 조회 결과)
nhi_qlfc_los_ymdstring-N건강보험 기존 자격상실일(가입자 조회 결과)
epi_qlfc_los_ymdstring-N고용보험 기존 자격상실일(가입자 조회 결과)
iai_qlfc_los_ymdstring-N산재보험 기존 자격상실일(가입자 조회 결과)
exists_npsstring-N국민연금 존재 표시(가입자 조회 결과의 exists 값 그대로)
exists_nhistring-N건강보험 존재 표시(가입자 조회 결과의 exists 값 그대로)
exists_epistring-N고용보험 존재 표시(가입자 조회 결과의 exists 값 그대로)
exists_iaistring-N산재보험 존재 표시(가입자 조회 결과의 exists 값 그대로)
confirmboolean-Ntrue 여야 저장한다. 없으면 저장하지 않고 저장할 내용 미리보기와 함께 거절한다
dry_runboolean-Ntrue 면 기관에 보내지 않고 저장할 내용만 돌려준다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: acqs_save-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.member_qualification.acqs_save",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "applicant_name": "<필수>",
    "rrkey": "<필수>",
    "resident_registration_number": "<필수>",
    "common_acquisition_date": "<필수>",
    "common_monthly_amount": "<필수: string | number>"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • 자격취득 신고 초안이 정보연계센터에 저장되며 저장한 초안을 되돌리는 API 는 없습니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
save_okboolean기관이 초안 저장을 받아들였는지 여부(새 접수번호를 받았을 때만 true)
save_executedboolean기관에 저장 요청을 보냈는지 여부(dry_run 이면 false)
submit_executedboolean기관 전송 수행 여부(이 API 는 전송하지 않아 항상 false)
dry_runboolean접수 없이 검증만 한 호출이면 true
alert_messagestring기관이 돌려준 안내 문장(없으면 빈 값)
cvrc_nostring기관이 새로 발번한 신고 초안 접수번호(save_ok 가 true 일 때만 값이 있다)
bpmnostring사업장관리번호(save_ok 가 true 일 때만 값이 있다)
dong_cdstring기관이 돌려준 동 코드
previewobject기관에 보낼 저장 내용 미리보기 맵
source_urlstring서버가 요청한 기관 화면 주소
outcomestring기관 쓰기 판정입니다. 새 접수번호를 받아 저장을 확인했으면 confirmed 입니다. 확인하지 못하면 작업 API 는 결과 대신 실패(error_code PROVIDER_OUTCOME_UNCONFIRMED, 재시도 불가)로 끝나고, REST 응답은 이 칸이 unconfirmed 이고 success 가 false 입니다. 실제 저장 때만 옵니다. dry_run 이면 이 칸이 없습니다
message_kostringREST 응답에서 outcome 이 unconfirmed 일 때만 값이 있는 안내 문장입니다. 작업 API 는 이 문장을 실패의 오류 문장 앞부분으로 줍니다. 실제 저장 때만 옵니다. dry_run 이면 이 칸이 없습니다
how_to_kostringREST 응답에서 outcome 이 unconfirmed 일 때만 값이 있습니다. 다시 저장하기 전에 방금 저장이 됐는지 확인하는 방법을 알려 줍니다. 작업 API 는 이 문장을 실패의 오류 문장 뒤에 붙여 줍니다. 실제 저장 때만 옵니다. dry_run 이면 이 칸이 없습니다
actionstring작업 API 결과에만 있는 칸입니다. 저장을 확인했을 때 이 액션 이름이 그대로 옵니다. REST 응답에는 없습니다. 실제 저장 때만 옵니다. dry_run 이면 이 칸이 없습니다
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "fourinsure",
    "action": "fourinsure.b1.member_qualification.acqs_save",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
VALIDATION_MISSING_FIELD확인 필요 — confirm 없이 보내면 저장하지 않고 이 오류로 끝나며, error.message 에 저장될 내용의 [미리보기] 가 담깁니다. 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 confirm=true 를 더해 다시 호출합니다.
POLICY_FEATURE_DISABLED일시 중지 — 상품이 일시 중지 상태입니다. 다시 보내도 풀리지 않습니다.
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_OUTCOME_UNCONFIRMED결과 불명 — 저장 요청을 보낸 뒤 기관이 새 접수번호를 주지 않거나 오류로 답하거나 연결이 끊기면, 다시 실행하지 말고 자격취득 신고 화면에서 방금 저장한 초안이 있는지 먼저 확인합니다. 기관이 오류 응답을 보내거나 응답이 오지 않거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UPSTREAM_ERROR결과 불명 — 저장 요청을 보낸 뒤 기관이 새 접수번호를 주지 않거나 오류로 답하거나 연결이 끊기면, 다시 실행하지 말고 자격취득 신고 화면에서 방금 저장한 초안이 있는지 먼저 확인합니다. 기관이 오류 응답을 보내거나 응답이 오지 않거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
VALIDATION_INVALID_FIELD필수 칸 누락 — 필수 칸(applicant_name, rrkey)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다.

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

MCP 도구 이름 fourinsure__b1__member_qualification__chg_draft_validate

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

정정할 가입자의 성명과 주민등록번호, 변경부호, 변경후 값, 변경일자를 넣으면 저장 없이 점검해 빠진 항목과 오류, 신고 가능 여부를 돌려줍니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • params 를 빈 객체로 보내도 작업은 성공하지만, 그러면 필수 입력이 missing_required_fields 로 돌아오고 workflow_gate.input_ready 가 false 입니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
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변경 내용 확인 여부입니다. 생략하면 N 으로 정리됩니다. 이 값이 있어도 검증 호출은 저장이나 신고를 실행하지 않습니다
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: chg_draft_validate-$(date +%s)-$RANDOM" \
  --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 로 다음 단계로 갈 수 있는지 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
feature_namestring기능 식별자
phasestring처리 단계(draft_validate)
workflow_stepstring처리 단계 식별자
route_kindstring처리 방식 — live_context_local_validation(화면 계약을 불러와 서버에서 검증)
source_urlstring서버가 요청한 기관 화면 주소
current_viewstring현재 화면 식별자
target_readyboolean대상 폼 준비 여부
business_contextobject사업장 컨텍스트 객체
selected_insurancesarray검증 대상으로 고른 보험 목록
enabled_sectionsarray화면 기준 섹션 사용 가능 상태 배열(key · label · enabled)
required_fieldsarray화면 기준 필수 입력 항목 배열(field_key · label · section · required_when)
missing_required_fieldsarray빠진 필수 입력 항목 배열(required_fields 와 같은 모양)
field_errorsarray입력 누락 · 형식 오류 배열(field_key · label · section · message)
warningsarray주의 메시지 배열(code · section · message · field_key)
screen_notesarray화면 확인 메모 배열
field_bindingsobject입력 키와 화면 필드의 대응 맵
normalized_inputobject정규화한 입력값 맵
draft_form_previewobject화면 필드에 채울 값 미리보기 맵
followup_endpointsarray기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다
workflow_gateobject진행 판정 객체(input_ready · blocking_issue_count · can_save=false · can_submit_report · report_status · blocked_reason)
safetyobject안전 플래그 객체(input_only=true · save_executed=false · submit_executed=false)
implementation_statusstring구현 상태 식별자
json
// result.data
{
  "success": true,
  "feature_name": "...",
  "phase": "draft_validate",
  "workflow_step": "member_qualification_change_draft_validated",
  "route_kind": "live_context_local_validation",
  "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": "implemented_input_only_draft_validation"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.

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

MCP 도구 이름 fourinsure__b1__member_qualification__chg_init

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

가입자 내용변경 신고서 화면을 열어 변경 항목별 보험 변경후 입력란과 특수직종 선택 목록, 미리 채워진 사업장 값을 돌려줍니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : 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: real_test' \
  --header "Idempotency-Key: chg_init-$(date +%s)-$RANDOM" \
  --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)과 화면 정보를 확인해 다음 단계(fourinsure.b1.member_qualification.chg_draft_validate)의 요청 본문을 만듭니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
pageobject화면 페이지 메타 객체
formsarrayform 메타데이터 배열
fieldsarray입력 필드 계약 배열
semantic_fieldsarray의미 단위 입력 컨트롤 배열
semantic_payloadobject의미 필드 키-값 맵
semantic_field_countnumber의미 필드 개수
csrf_token_presentbooleanCSRF 토큰 존재 여부
followup_endpointsarray기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다
navigation_stepsarray화면 내비게이션 단계 배열
current_viewstring현재 화면 식별자
target_readyboolean대상 폼 준비 여부
raw_html_lennumber원본 HTML 길이
source_urlstring서버가 요청한 기관 화면 주소
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업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.

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

MCP 도구 이름 fourinsure__b1__member_qualification__dependent_draft_validate

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

취득 또는 상실 구분, 직장가입자, 피부양자 명단, 연락처를 넣으면 빠진 필수 항목과 형식 오류, 신고 가능 여부를 돌려줍니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • params 를 빈 객체로 보내도 작업은 성공하지만, 그러면 필수 입력이 missing_required_fields 로 돌아오고 workflow_gate.input_ready 가 false 입니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

  • 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
순번변수명타입필수설명
action_divstringN취득 또는 상실 구분
applicant_namestringN직장가입자 성명입니다. 피부양자 성명은 dependents 의 name 에 보냅니다
resident_registration_numberstringN주민등록번호
rrno_frontstringN주민등록번호 앞자리
rrno_backstringN주민등록번호 뒷자리
report_datestringN신고일자
reporter_namestringN신고인 성명
bplc_telno1stringN사업장 전화번호 (3칸 중 1번째)
bplc_telno2stringN사업장 전화번호 (3칸 중 2번째)
bplc_telno3stringN사업장 전화번호 (3칸 중 3번째)
bplc_fxno1stringN사업장 팩스번호 (3칸 중 1번째)
bplc_fxno2stringN사업장 팩스번호 (3칸 중 2번째)
bplc_fxno3stringN사업장 팩스번호 (3칸 중 3번째)
home_telno1stringN자택 전화번호 (3칸 중 1번째)
home_telno2stringN자택 전화번호 (3칸 중 2번째)
home_telno3stringN자택 전화번호 (3칸 중 3번째)
co_telno1stringN직장 전화번호 (3칸 중 1번째)
co_telno2stringN직장 전화번호 (3칸 중 2번째)
co_telno3stringN직장 전화번호 (3칸 중 3번째)
mbl_telno1stringN휴대전화번호 (3칸 중 1번째)
mbl_telno2stringN휴대전화번호 (3칸 중 2번째)
mbl_telno3stringN휴대전화번호 (3칸 중 3번째)
dependentsarrayN피부양자
dependents[].resident_registration_numberstringN피부양자 주민등록번호입니다. 분리 입력 시 rrno_front 와 rrno_back 을 함께 보냅니다. 생략 시 기본값: ""
dependents[].rrno_frontstringN피부양자 주민등록번호 앞자리입니다. 생략 시 기본값: ""
dependents[].rrno_backstringN피부양자 주민등록번호 뒷자리입니다. 생략 시 기본값: ""
dependents[].namestringN피부양자 성명입니다. 생략 시 기본값: ""
dependents[].relationship_codestringN가입자와의 관계 코드입니다. 생략 시 기본값: ""
dependents[].relationship_namestringN가입자와의 관계 이름입니다. 생략 시 기본값: ""
dependents[].acquisition_datestringN피부양자 자격취득일입니다. 생략 시 기본값: ""
dependents[].acquisition_reason_codestringN피부양자 취득 사유 코드입니다. 생략 시 기본값: ""
dependents[].acquisition_reason_namestringN피부양자 취득 사유 이름입니다. 생략 시 기본값: ""
dependents[].attachment_required_ynstring | booleanN첨부서류 필요 여부입니다. 생략 시 기본값: null
dependents[].disabled_veteran_codestringN장애인 또는 국가유공자 구분 코드입니다. 생략 시 기본값: ""
dependents[].disabled_veteran_namestringN장애인 또는 국가유공자 구분 이름입니다. 생략 시 기본값: ""
dependents[].disabled_veteran_grade_codestringN장애 또는 보훈 등급 코드입니다. 생략 시 기본값: ""
dependents[].disabled_veteran_grade_namestringN장애 또는 보훈 등급 이름입니다. 생략 시 기본값: ""
dependents[].disabled_veteran_registered_datestringN장애인 또는 국가유공자 등록일입니다. 생략 시 기본값: ""
dependents[].nationality_codestringN국적 코드입니다. 생략 시 기본값: ""
dependents[].nationality_namestringN국적 이름입니다. 생략 시 기본값: ""
dependents[].stay_qualification_codestringN체류자격 코드입니다. 생략 시 기본값: ""
dependents[].stay_qualification_namestringN체류자격 이름입니다. 생략 시 기본값: ""
dependents[].stay_period_start_datestringN체류기간 시작일입니다. 생략 시 기본값: ""
dependents[].stay_period_end_datestringN체류기간 종료일입니다. 생략 시 기본값: ""
dependents[].loss_datestringN피부양자 자격상실일입니다. 생략 시 기본값: ""
dependents[].loss_reason_codestringN피부양자 상실 사유 코드입니다. 생략 시 기본값: ""
dependents[].loss_reason_namestringN피부양자 상실 사유 이름입니다. 생략 시 기본값: ""
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: dependent_draft_validate-$(date +%s)-$RANDOM" \
  --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 로 다음 단계로 갈 수 있는지 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
feature_namestring기능 식별자
phasestring처리 단계(draft_validate)
workflow_stepstring처리 단계 식별자
route_kindstring처리 방식 — live_context_local_validation(화면 계약을 불러와 서버에서 검증)
source_urlstring서버가 요청한 기관 화면 주소
current_viewstring현재 화면 식별자
target_readyboolean대상 폼 준비 여부
business_contextobject사업장 컨텍스트 객체
selected_insurancesarray검증 대상으로 고른 보험 목록
enabled_sectionsarray화면 기준 섹션 사용 가능 상태 배열(key · label · enabled)
required_fieldsarray화면 기준 필수 입력 항목 배열(field_key · label · section · required_when)
missing_required_fieldsarray빠진 필수 입력 항목 배열(required_fields 와 같은 모양)
field_errorsarray입력 누락 · 형식 오류 배열(field_key · label · section · message)
warningsarray주의 메시지 배열(code · section · message · field_key)
screen_notesarray화면 확인 메모 배열
field_bindingsobject입력 키와 화면 필드의 대응 맵
normalized_inputobject정규화한 입력값 맵
draft_form_previewobject화면 필드에 채울 값 미리보기 맵
followup_endpointsarray기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다
workflow_gateobject진행 판정 객체(input_ready · blocking_issue_count · can_save=false · can_submit_report · report_status · blocked_reason)
safetyobject안전 플래그 객체(input_only=true · save_executed=false · submit_executed=false)
implementation_statusstring구현 상태 식별자
json
// result.data
{
  "success": true,
  "feature_name": "...",
  "phase": "draft_validate",
  "workflow_step": "member_qualification_dependent_draft_validated",
  "route_kind": "live_context_local_validation",
  "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": "implemented_input_only_draft_validation"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.

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

MCP 도구 이름 fourinsure__b1__member_qualification__dependent_init

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

로그인한 연동으로 부르면 건강보험 피부양자 신고서 화면의 신고서 종류, 채워진 사업장 정보와 신고일, 빈 가입자와 연락처 칸을 받습니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : 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: real_test' \
  --header "Idempotency-Key: dependent_init-$(date +%s)-$RANDOM" \
  --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)과 화면 정보를 확인해 다음 단계(fourinsure.b1.member_qualification.dependent_draft_validate)의 요청 본문을 만듭니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
pageobject화면 페이지 메타 객체
formsarrayform 메타데이터 배열
fieldsarray입력 필드 계약 배열
semantic_fieldsarray의미 단위 입력 컨트롤 배열
semantic_payloadobject의미 필드 키-값 맵
semantic_field_countnumber의미 필드 개수
csrf_token_presentbooleanCSRF 토큰 존재 여부
followup_endpointsarray기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다
navigation_stepsarray화면 내비게이션 단계 배열
current_viewstring현재 화면 식별자
target_readyboolean대상 폼 준비 여부
raw_html_lennumber원본 HTML 길이
source_urlstring서버가 요청한 기관 화면 주소
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업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.

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

MCP 도구 이름 fourinsure__b1__member_qualification__los_draft_validate

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

상실자 성명과 주민등록번호, 고른 보험, 상실일과 보험별 상실사유, 보수총액을 넣으면 빠진 항목과 오류, 신고 가능 여부를 돌려줍니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • params 를 빈 객체로 보내도 작업은 성공하지만, 그러면 필수 입력이 missing_required_fields 로 돌아오고 workflow_gate.input_ready 가 false 입니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

  • 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
순번변수명타입필수설명
selected_insurancesarrayN신고할 보험 목록(national_pension, health_insurance, employment_insurance, workers_compensation)
applicant_namestringN대상자 성명(한글)
resident_registration_numberstringN주민등록번호
rrno_frontstringN주민등록번호 앞자리
rrno_backstringN주민등록번호 뒷자리
common_loss_datestringN공통 자격상실일
loss_date_modestringN상실일 입력 방식(기관 화면 값, 저장 때 비우면 all)
national_pensionobjectN국민연금
national_pension.loss_reason_codestringN국민연금 상실사유코드 생략 시 기본값: ""
national_pension.loss_reason_namestringN국민연금 상실사유명 생략 시 기본값: ""
national_pension.loss_datestringN국민연금 자격상실일 생략 시 기본값: ""
national_pension.loss_month_payment_ynstring | booleanN국민연금 상실월납부여부 생략 시 기본값: null
health_insuranceobjectN건강보험
health_insurance.loss_reason_codestringN건강보험 상실사유코드 생략 시 기본값: ""
health_insurance.loss_reason_namestringN건강보험 상실사유명 생략 시 기본값: ""
health_insurance.loss_datestringN건강보험 자격상실일 생략 시 기본값: ""
employment_insuranceobjectN고용보험
employment_insurance.loss_reason_codestringN고용보험 상실사유코드 생략 시 기본값: ""
employment_insurance.loss_reason_namestringN고용보험 상실사유명 생략 시 기본값: ""
employment_insurance.specific_reason_textstringN고용보험 구체적사유 생략 시 기본값: ""
employment_insurance.loss_datestringN고용보험 자격상실일 생략 시 기본값: ""
employment_insurance.current_year_salary_amountstring | numberN고용보험 해당연도 보수총액 생략 시 기본값: null
employment_insurance.previous_year_salary_amountstring | numberN고용보험 전년도 보수총액 생략 시 기본값: null
workers_compensationobjectN산재보험
workers_compensation.loss_reason_codestringN산재보험 상실사유코드 생략 시 기본값: ""
workers_compensation.loss_reason_namestringN산재보험 상실사유명 생략 시 기본값: ""
workers_compensation.specific_reason_textstringN산재보험 구체적사유 생략 시 기본값: ""
workers_compensation.loss_datestringN산재보험 자격상실일 생략 시 기본값: ""
workers_compensation.current_year_salary_amountstring | numberN산재보험 해당연도 보수총액 생략 시 기본값: null
workers_compensation.previous_year_salary_amountstring | numberN산재보험 전년도 보수총액 생략 시 기본값: null
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: los_draft_validate-$(date +%s)-$RANDOM" \
  --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 로 다음 단계로 갈 수 있는지 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
feature_namestring기능 식별자
phasestring처리 단계(draft_validate)
workflow_stepstring처리 단계 식별자
route_kindstring처리 방식 — live_context_local_validation(화면 계약을 불러와 서버에서 검증)
source_urlstring서버가 요청한 기관 화면 주소
current_viewstring현재 화면 식별자
target_readyboolean대상 폼 준비 여부
business_contextobject사업장 컨텍스트 객체
selected_insurancesarray검증 대상으로 고른 보험 목록
enabled_sectionsarray화면 기준 섹션 사용 가능 상태 배열(key · label · enabled)
required_fieldsarray화면 기준 필수 입력 항목 배열(field_key · label · section · required_when)
missing_required_fieldsarray빠진 필수 입력 항목 배열(required_fields 와 같은 모양)
field_errorsarray입력 누락 · 형식 오류 배열(field_key · label · section · message)
warningsarray주의 메시지 배열(code · section · message · field_key)
screen_notesarray화면 확인 메모 배열
field_bindingsobject입력 키와 화면 필드의 대응 맵
normalized_inputobject정규화한 입력값 맵
draft_form_previewobject화면 필드에 채울 값 미리보기 맵
followup_endpointsarray기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다
workflow_gateobject진행 판정 객체(input_ready · blocking_issue_count · can_save=false · can_submit_report · report_status · blocked_reason)
safetyobject안전 플래그 객체(input_only=true · save_executed=false · submit_executed=false)
implementation_statusstring구현 상태 식별자
json
// result.data
{
  "success": true,
  "feature_name": "...",
  "phase": "draft_validate",
  "workflow_step": "member_qualification_loss_draft_validated",
  "route_kind": "live_context_local_validation",
  "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": "implemented_input_only_draft_validation"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.

12. 자격상실 기존 신고 확인fourinsure.b1.member_qualification.los_exist_check

MCP 도구 이름 fourinsure__b1__member_qualification__los_exist_check

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

자격키와 보험 하나를 넣으면 그 보험에 기존 상실신고가 있는지 기관에 확인해 신고 막힘 여부와 안내 문구를 돌려줍니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • 기존 신고가 있어 기관이 안내 문장을 돌려주면 작업은 성공하고 duplicate_blocked 가 true 이며 그 문장이 alert_message 에 옵니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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_exist_check이 API 고정값 (기본값)

예시 : fourinsure.b1.member_qualification.los_exist_check

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
rrkeystringY자격상실 가입자 조회 결과의 rrkey
flagstringY확인할 보험(YG, GG, GY, SJ 또는 national_pension 같은 보험 이름)
check_typestringN기관 확인 구분 값(기본 2)
bpmnostringN사업장관리번호(비우면 기관 화면 값을 쓴다)
workplace_namestringN사업장 이름(비우면 기관 화면 값을 쓴다)
declaration_apply_datestringN신고 적용일(비우면 기관 화면 값을 쓴다)
applicant_rrkeystringN신고인 자격키(비우면 기관 화면 값을 쓴다)
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: los_exist_check-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.member_qualification.los_exist_check",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "rrkey": "<필수>",
    "flag": "<필수>"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • 기관에 저장하거나 신고하지 않는 확인입니다. result.data 의 duplicate_blocked 가 false 면 insurance_key 의 보험에 진행을 막는 기존 상실신고가 없습니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
duplicate_blockedboolean기관이 안내 문장으로 진행을 막았는지 여부(기존 신고가 있을 때 true)
alert_messagestring기관이 돌려준 안내 문장(없으면 빈 값)
flagstring확인한 보험 구분 값(YG, GG, GY, SJ)
insurance_keystring확인한 보험 이름 키(national_pension 등)
save_executedboolean기관 저장 수행 여부(조회라 항상 false)
source_urlstring서버가 요청한 기관 화면 주소
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "fourinsure",
    "action": "fourinsure.b1.member_qualification.los_exist_check",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
VALIDATION_INVALID_FIELD필수 칸 누락 — 필수 칸(rrkey, flag)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다.

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

MCP 도구 이름 fourinsure__b1__member_qualification__los_init

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

로그인한 연동으로 부르면 자격상실 신고 화면의 채워진 사업장 정보와, 비어 있는 상실일과 보험별 상실사유, 보수총액 칸 구성을 받습니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : 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: real_test' \
  --header "Idempotency-Key: los_init-$(date +%s)-$RANDOM" \
  --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)과 화면 정보를 확인해 다음 단계(fourinsure.b1.member_qualification.los_draft_validate, fourinsure.b1.member_qualification.los_exist_check, fourinsure.b1.member_qualification.los_member_lookup, fourinsure.b1.member_qualification.los_save)의 요청 본문을 만듭니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
pageobject화면 페이지 메타 객체
formsarrayform 메타데이터 배열
fieldsarray입력 필드 계약 배열
semantic_fieldsarray의미 단위 입력 컨트롤 배열
semantic_payloadobject의미 필드 키-값 맵
semantic_field_countnumber의미 필드 개수
csrf_token_presentbooleanCSRF 토큰 존재 여부
followup_endpointsarray기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다
navigation_stepsarray화면 내비게이션 단계 배열
current_viewstring현재 화면 식별자
target_readyboolean대상 폼 준비 여부
raw_html_lennumber원본 HTML 길이
source_urlstring서버가 요청한 기관 화면 주소
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업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.

14. 자격상실 가입자 조회fourinsure.b1.member_qualification.los_member_lookup

MCP 도구 이름 fourinsure__b1__member_qualification__los_member_lookup

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

퇴사자의 성명과 주민등록번호를 넣으면 자격상실 신고서에 쓸 자격키와 기존 자격취득일, 보험별 상실일을 돌려줍니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • 기관이 안내 문장을 돌려주면 작업은 성공하고 lookup_ok 가 false, rrkey 는 빈 값이며 그 문장이 alert_message 에 옵니다.
  • REST 요청 표와 MCP 도구 규격의 필수 표시가 다릅니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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_member_lookup이 API 고정값 (기본값)

예시 : fourinsure.b1.member_qualification.los_member_lookup

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
applicant_namestring-Y대상자 성명(한글)
resident_registration_numberstring-조건부주민등록번호 13자리
rrno_frontstring-조건부주민등록번호 앞 6자리
rrno_backstring-조건부주민등록번호 뒤 7자리
declaration_apply_datestring8N신고 적용일(비우면 기관 화면 값을 쓴다)

형식 : YYYYMMDD

bpmnostring-N사업장관리번호(비우면 기관 화면 값을 쓴다)
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: los_member_lookup-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.member_qualification.los_member_lookup",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "applicant_name": "<필수>",
    "resident_registration_number": "<필수>"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • 기관에 저장하거나 신고하지 않는 조회입니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
lookup_okboolean가입자를 찾았는지 여부(false 면 rrkey 가 빈 값)
alert_messagestring기관이 돌려준 안내 문장(없으면 빈 값)
rrkeystring가입자 자격키, 같은 신고의 다음 조회에 그대로 넣는 값
applicant_namestring조회한 대상자 성명
rrno_maskedstring가린 주민등록번호
health_card_nostring건강보험증 번호
qualification_acquisition_datestring자격취득일
qualification_acquisition_datesobject보험별 기존 자격취득일 맵
existing_loss_datesobject보험별 기존 자격상실일 맵
existsobject보험별 존재 표시 맵(기관이 돌려준 값 그대로)
save_executedboolean기관 저장 수행 여부(조회라 항상 false)
source_urlstring서버가 요청한 기관 화면 주소
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "fourinsure",
    "action": "fourinsure.b1.member_qualification.los_member_lookup",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
VALIDATION_INVALID_FIELD필수 칸 누락 — 필수 칸(applicant_name)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다.

15. 자격상실 초안 저장fourinsure.b1.member_qualification.los_save

MCP 도구 이름 fourinsure__b1__member_qualification__los_save

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

퇴사자 자격키와 성명, 주민등록번호, 공통 자격상실일, 보험마다 상실 사유, 당해연도 보수총액, 건강보험 산정 개월수를 넣으면 자격상실 신고서를 정보연계센터에 초안으로 저장하고 접수번호를 받습니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
  • dry_run 을 true 로 보내면 기관에 보내지 않고 저장할 내용을 result.data 의 preview 로 돌려줍니다(save_executed=false).
  • REST 요청 표와 MCP 도구 규격의 필수 표시가 다릅니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • 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_save이 API 고정값 (기본값)

예시 : fourinsure.b1.member_qualification.los_save

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

  • 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
순번변수명타입길이필수설명
selected_insurancesarray-N신고할 보험 목록(national_pension, health_insurance, employment_insurance, workers_compensation, 기본은 네 보험 모두)
applicant_namestring-Y대상자 성명(한글)
resident_registration_numberstring-조건부주민등록번호 13자리
rrno_frontstring-조건부주민등록번호 앞자리
rrno_backstring-조건부주민등록번호 뒷자리
common_loss_datestring8Y공통 상실일

형식 : YYYYMMDD

loss_date_modestring-N상실일 입력 방식(기관 화면 값, 저장 때 비우면 all)
national_pensionobject-N국민연금 상실 사유. 코드와 이름을 둘 다 입력합니다. 비우면 저장하지 않습니다
national_pension.loss_reason_codestring-조건부국민연금을 신고할 때 꼭 보내는 상실 사유 코드입니다. 이름과 함께 보내야 하고 없으면 저장하지 않고 거절합니다. selected_insurances 를 보내지 않으면 국민연금도 신고합니다
national_pension.loss_reason_namestring-조건부위 코드에 해당하는 국민연금 상실 사유 이름입니다. 코드와 이름을 둘 다 보내야 하며 하나만 보내도 저장하지 않고 거절합니다
national_pension.loss_datestring-N국민연금 자격상실일 생략 시 기본값: ""
national_pension.loss_month_payment_ynstring | boolean-N국민연금 상실월납부여부 생략 시 기본값: null
health_insuranceobject-N건강보험 상실 사유. 코드와 이름을 둘 다 입력합니다. 비우면 저장하지 않습니다
health_insurance.loss_reason_codestring-조건부건강보험을 신고할 때 꼭 보내는 상실 사유 코드입니다. 이름과 함께 보내야 하고 없으면 저장하지 않고 거절합니다. selected_insurances 를 보내지 않으면 건강보험도 신고합니다
health_insurance.loss_reason_namestring-조건부위 코드에 해당하는 건강보험 상실 사유 이름입니다. 코드와 이름을 둘 다 보내야 하며 하나만 보내도 저장하지 않고 거절합니다
health_insurance.loss_datestring-N건강보험 자격상실일 생략 시 기본값: ""
employment_insuranceobject-N고용보험 상실 사유. 코드와 이름을 둘 다 입력합니다. 비우면 저장하지 않습니다
employment_insurance.loss_reason_codestring-조건부고용보험을 신고할 때 꼭 보내는 상실 사유 코드입니다. 이름과 함께 보내야 하고 없으면 저장하지 않고 거절합니다. selected_insurances 를 보내지 않으면 고용보험도 신고합니다
employment_insurance.loss_reason_namestring-조건부위 코드에 해당하는 고용보험 상실 사유 이름입니다. 코드와 이름을 둘 다 보내야 하며 하나만 보내도 저장하지 않고 거절합니다
employment_insurance.specific_reason_textstring-N구체적 사유. 입력하지 않으면 비워 저장합니다
employment_insurance.loss_datestring-N고용보험 자격상실일 생략 시 기본값: ""
employment_insurance.current_year_salary_amountstring | number-N고용보험 해당연도 보수총액 생략 시 기본값: null
employment_insurance.previous_year_salary_amountstring | number-N고용보험 전년도 보수총액 생략 시 기본값: null
workers_compensationobject-N산재보험 상실 사유. 코드와 이름을 둘 다 입력합니다. 비우면 저장하지 않습니다
workers_compensation.loss_reason_codestring-조건부산재보험을 신고할 때 꼭 보내는 상실 사유 코드입니다. 이름과 함께 보내야 하고 없으면 저장하지 않고 거절합니다. selected_insurances 를 보내지 않으면 산재보험도 신고합니다
workers_compensation.loss_reason_namestring-조건부위 코드에 해당하는 산재보험 상실 사유 이름입니다. 코드와 이름을 둘 다 보내야 하며 하나만 보내도 저장하지 않고 거절합니다
workers_compensation.specific_reason_textstring-N구체적 사유. 입력하지 않으면 비워 저장합니다
workers_compensation.loss_datestring-N산재보험 자격상실일 생략 시 기본값: ""
workers_compensation.current_year_salary_amountstring | number-N산재보험 해당연도 보수총액 생략 시 기본값: null
workers_compensation.previous_year_salary_amountstring | number-N산재보험 전년도 보수총액 생략 시 기본값: null
rrkeystring-Y자격상실 가입자 조회 결과의 rrkey
cmdstring-N저장 구분(Regist 신규, Modify 수정)
cvrc_nostring-N수정할 초안의 접수번호(cmd 가 Modify 일 때 필수)
current_year_salary_amountstring | number-N당해연도 보수총액(건강보험, 고용보험, 산재보험을 신고할 때 필수). 0 보다 큰 값을 입력합니다
previous_year_salary_amountstring | number-N전년도 보수총액
health_insurance_month_countstring-N건강보험 당해연도 산정월수(건강보험을 신고할 때 필수)
qualification_acquisition_datestring-N자격취득일(가입자 조회 결과의 qualification_acquisition_date)
health_card_nostring-N건강보험증 번호(가입자 조회 결과의 health_card_no)
confirmboolean-Ntrue 여야 저장한다. 없으면 저장하지 않고 저장할 내용 미리보기와 함께 거절한다
dry_runboolean-Ntrue 면 기관에 보내지 않고 저장할 내용만 돌려준다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: los_save-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.member_qualification.los_save",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "applicant_name": "<필수>",
    "common_loss_date": "<필수>",
    "rrkey": "<필수>",
    "resident_registration_number": "<필수>"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • 자격상실 신고 초안이 정보연계센터에 저장되며 저장한 초안을 되돌리는 API 는 없습니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
save_okboolean기관이 초안 저장을 받아들였는지 여부(새 접수번호를 받았을 때만 true)
save_executedboolean기관에 저장 요청을 보냈는지 여부(dry_run 이면 false)
submit_executedboolean기관 전송 수행 여부(이 API 는 전송하지 않아 항상 false)
dry_runboolean접수 없이 검증만 한 호출이면 true
alert_messagestring기관이 돌려준 안내 문장(없으면 빈 값)
cvrc_nostring기관이 새로 발번한 신고 초안 접수번호(save_ok 가 true 일 때만 값이 있다)
bpmnostring사업장관리번호(save_ok 가 true 일 때만 값이 있다)
dong_cdstring기관이 돌려준 동 코드
previewobject기관에 보낼 저장 내용 미리보기 맵
source_urlstring서버가 요청한 기관 화면 주소
outcomestring기관 쓰기 판정입니다. 새 접수번호를 받아 저장을 확인했으면 confirmed 입니다. 확인하지 못하면 작업 API 는 결과 대신 실패(error_code PROVIDER_OUTCOME_UNCONFIRMED, 재시도 불가)로 끝나고, REST 응답은 이 칸이 unconfirmed 이고 success 가 false 입니다. 실제 저장 때만 옵니다. dry_run 이면 이 칸이 없습니다
message_kostringREST 응답에서 outcome 이 unconfirmed 일 때만 값이 있는 안내 문장입니다. 작업 API 는 이 문장을 실패의 오류 문장 앞부분으로 줍니다. 실제 저장 때만 옵니다. dry_run 이면 이 칸이 없습니다
how_to_kostringREST 응답에서 outcome 이 unconfirmed 일 때만 값이 있습니다. 다시 저장하기 전에 방금 저장이 됐는지 확인하는 방법을 알려 줍니다. 작업 API 는 이 문장을 실패의 오류 문장 뒤에 붙여 줍니다. 실제 저장 때만 옵니다. dry_run 이면 이 칸이 없습니다
actionstring작업 API 결과에만 있는 칸입니다. 저장을 확인했을 때 이 액션 이름이 그대로 옵니다. REST 응답에는 없습니다. 실제 저장 때만 옵니다. dry_run 이면 이 칸이 없습니다
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "fourinsure",
    "action": "fourinsure.b1.member_qualification.los_save",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
VALIDATION_MISSING_FIELD확인 필요 — confirm 없이 보내면 저장하지 않고 이 오류로 끝나며, error.message 에 저장될 내용의 [미리보기] 가 담깁니다. 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 confirm=true 를 더해 다시 호출합니다.
POLICY_FEATURE_DISABLED일시 중지 — 상품이 일시 중지 상태입니다. 다시 보내도 풀리지 않습니다.
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_OUTCOME_UNCONFIRMED결과 불명 — 저장 요청을 보낸 뒤 기관이 새 접수번호를 주지 않거나 오류로 답하거나 연결이 끊기면, 다시 실행하지 말고 자격상실 신고 화면에서 방금 저장한 초안이 있는지 먼저 확인합니다. 기관이 오류 응답을 보내거나 응답이 오지 않거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
PROVIDER_UPSTREAM_ERROR결과 불명 — 저장 요청을 보낸 뒤 기관이 새 접수번호를 주지 않거나 오류로 답하거나 연결이 끊기면, 다시 실행하지 말고 자격상실 신고 화면에서 방금 저장한 초안이 있는지 먼저 확인합니다. 기관이 오류 응답을 보내거나 응답이 오지 않거나 연결이 끊긴 경우 error.message 는 결과 확인 불가 안내('기관의 요청 처리 여부를 확인하지 못했습니다. 다시 실행하지 마세요. 이미 처리됐을 수 있어 중복 처리로 이어집니다.')입니다.
VALIDATION_INVALID_FIELD필수 칸 누락 — 필수 칸(applicant_name, rrkey, common_loss_date)이 비어 있어 기관을 부르기 전에 거절했습니다. error.message 가 빠진 칸 이름을 알려 줍니다. 재시도 불가로 표시되니 그 칸을 채워 다시 호출합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다.