개발자 문서
API 레퍼런스

민원 - 4대보험

이 쪽의 모든 작업에 해당

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

1. 민원처리현황 조회fourinsure.b1.civil_receipt.history.list

MCP 도구 이름 fourinsure__b1__civil_receipt__history__list

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

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

조건 없이 부르면 기관 화면에 미리 채워진 기간의 첫 쪽에 보이는 민원마다 민원 종류, 신고일, 진행상태, 보험과 기관, 처리 지사를 돌려줍니다.

  • 조회 결과가 없으면 items 가 빈 배열로 옵니다. 실패가 아닙니다.

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.civil_receipt.history.list이 API 고정값 (기본값)

예시 : fourinsure.b1.civil_receipt.history.list

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
srch_cvrc_nostring-N검색 민원번호 srchCvrcNo
rrnostring-N주민번호 13자리 (하이픈 제거). rrno_front+rrno_back 대체 가능
rrno_frontstring-N주민번호 앞자리
rrno_backstring-N주민번호 뒷자리
frst_reg_str_dtstring8-10N조회 시작일. 로 입력합니다. 입력하지 않으면 기관 기본 기간으로 조회합니다

형식 : YYYY-MM-DD 또는 YYYYMMDD

frst_reg_end_dtstring8-10N조회 종료일. 로 입력합니다. 입력하지 않으면 기관 기본 기간으로 조회합니다

형식 : YYYY-MM-DD 또는 YYYYMMDD

prgrs_stts_cdstring-N진행상태 코드 prgrsSttsCd
sins_type_cdstring-N4대보험 유형 코드 sinsTypeCd
cvlcpt_tmplt_cdstring-N민원 서식 코드 cvlcptTmpltCd
current_page_nonumber-N페이지 번호 currentPageNo. 기본 1
output_formatsarray-N이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: list-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.civil_receipt.history.list",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • result.data 의 items 로 조회 결과를 확인합니다.
  • 아래 표의 items[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 엑셀 파일 맨 윗줄의 머리글입니다.
  • 아래 표의 줄은 엑셀로 내보내는 열이라 응답 행의 칸 전부가 아닐 수 있습니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
itemsarray조회 결과 행 배열
items[].row_nonumber번호
items[].cvrc_nostring민원 접수번호
items[].upstream_cvrc_nostring원천 접수번호
items[].upper_cvrc_nostring상위 접수번호
items[].request_typestring증명서/민원 종류
items[].reported_atstring신고일시
items[].process_targetstring처리 대상
items[].agency_received_atstring기관 접수일시
items[].insurance_and_agencystring보험/기관
items[].progress_statusstring진행상태
items[].process_branchstring처리 지사
queryobject적용된 검색 조건 맵
source_urlstring서버가 요청한 기관 화면 주소
json
// result.data
{
  "success": true,
  "items": [
    {
      "row_no": 1,
      "cvrc_no": "...",
      "upstream_cvrc_no": "...",
      "template_code": "...",
      "upper_cvrc_no": "...",
      "request_type": "...",
      "reported_at": "...",
      "process_target": "...",
      "agency_received_at": "...",
      "insurance_and_agency": "...",
      "progress_status": "...",
      "process_branch": "..."
    }
  ],
  "query": { "srchCvrcNo": "...", "rrno_masked": "...", "frstRegStrDt": "...", "frstRegEndDt": "...", "prgrsSttsCd": "...", "sinsTypeCd": "...", "cvlcptTmpltCd": "...", "currentPageNo": "1" },
  "source_url": "..."
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
PROVIDER_VALIDATION_ERROR검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다.

2. 민원처리현황 조회 입력 서식 조회fourinsure.b1.civil_receipt.history.list_init

MCP 도구 이름 fourinsure__b1__civil_receipt__history__list_init

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

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

로그인한 연동 계정으로 민원처리현황 화면을 열어 처리여부, 보험유형, 민원서식 보기와 미리 채워진 조회 기간을 돌려줍니다.

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.civil_receipt.history.list_init이 API 고정값 (기본값)

예시 : fourinsure.b1.civil_receipt.history.list_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: list_init-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "fourinsure",
  "action": "fourinsure.b1.civil_receipt.history.list_init",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • result.data 에서 입력 항목(fields)과 화면 정보를 확인해 다음 단계(fourinsure.b1.civil_receipt.history.list)의 요청 본문을 만듭니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
pageobject화면 페이지 메타 객체
formsarrayform 메타데이터 배열
fieldsarray입력 필드 계약 배열
semantic_fieldsarray의미 단위 입력 컨트롤 배열
semantic_payloadobject의미 필드 키-값 맵
semantic_field_countnumber의미 필드 개수
csrf_token_presentbooleanCSRF 토큰 존재 여부
followup_endpointsarray기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다
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": [],
  "raw_html_len": 0,
  "source_url": "..."
}
순번오류 코드발생 조건
AUTH_REQUIRED세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다.
PROVIDER_AUTH_FAILED인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.