민원 - 4대보험
이 쪽의 모든 작업에 해당
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [4대보험 로그인]
- params 는 빈 객체로 보내도 호출됩니다. 사용할 인증서는 account_link_id 로 지정합니다.
1. 민원처리현황 조회fourinsure. b1. civil_ receipt. history. list
MCP 도구 이름 fourinsure__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
조건 없이 부르면 기관 화면에 미리 채워진 기간의 첫 쪽에 보이는 민원마다 민원 종류, 신고일, 진행상태, 보험과 기관, 처리 지사를 돌려줍니다.
- 조회 결과가 없으면 items 가 빈 배열로 옵니다. 실패가 아닙니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| srch_ | string | - | N | 검색 민원번호 srchCvrcNo | |
| rrno | string | - | N | 주민번호 13자리 (하이픈 제거). rrno_front+rrno_back 대체 가능 | |
| rrno_ | string | - | N | 주민번호 앞자리 | |
| rrno_ | string | - | N | 주민번호 뒷자리 | |
| frst_ | string | 8-10 | N | 조회 시작일. 로 입력합니다. 입력하지 않으면 기관 기본 기간으로 조회합니다 | |
| frst_ | string | 8-10 | N | 조회 종료일. 로 입력합니다. 입력하지 않으면 기관 기본 기간으로 조회합니다 | |
| prgrs_ | string | - | N | 진행상태 코드 prgrsSttsCd | |
| sins_ | string | - | N | 4대보험 유형 코드 sinsTypeCd | |
| cvlcpt_ | string | - | N | 민원 서식 코드 cvlcptTmpltCd | |
| current_ | number | - | N | 페이지 번호 currentPageNo. 기본 1 | |
| output_ | array | - | N | 이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다 |
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"])의 열로 내보내는 칸이고, 열 이름은 엑셀 파일 맨 윗줄의 머리글입니다.
- 아래 표의 줄은 엑셀로 내보내는 열이라 응답 행의 칸 전부가 아닐 수 있습니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| items | array | 조회 결과 행 배열 | |
| items[]. | number | 번호 | |
| items[]. | string | 민원 접수번호 | |
| items[]. | string | 원천 접수번호 | |
| items[]. | string | 상위 접수번호 | |
| items[]. | string | 증명서/민원 종류 | |
| items[]. | string | 신고일시 | |
| items[]. | string | 처리 대상 | |
| items[]. | string | 기관 접수일시 | |
| items[]. | string | 보험/기관 | |
| items[]. | string | 진행상태 | |
| items[]. | string | 처리 지사 | |
| query | object | 적용된 검색 조건 맵 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// 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_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| PROVIDER_ | 검증 오류 — 보낸 값이 빠졌거나 형식이 맞지 않거나 값에 맞는 대상을 찾지 못한 경우입니다. error.message 가 알려 주는 값을 고쳐 다시 호출합니다. |
2. 민원처리현황 조회 입력 서식 조회fourinsure. b1. civil_ receipt. history. list_ init
MCP 도구 이름 fourinsure__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
로그인한 연동 계정으로 민원처리현황 화면을 열어 처리여부, 보험유형, 민원서식 보기와 미리 채워진 조회 기간을 돌려줍니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
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)의 요청 본문을 만듭니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| page | object | 화면 페이지 메타 객체 | |
| forms | array | form 메타데이터 배열 | |
| fields | array | 입력 필드 계약 배열 | |
| semantic_ | array | 의미 단위 입력 컨트롤 배열 | |
| semantic_ | object | 의미 필드 키-값 맵 | |
| semantic_ | number | 의미 필드 개수 | |
| csrf_ | boolean | CSRF 토큰 존재 여부 | |
| followup_ | array | 기관 화면이 다음 단계에서 부르는 주소 목록({url} 객체 배열)입니다. 우리 API 주소가 아니며 직접 호출하지 않습니다 | |
| raw_ | number | 원본 HTML 길이 | |
| source_ | string | 서버가 요청한 기관 화면 주소 |
// 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_ | 세션 없음 — 로그인 세션이 없습니다. 로그인을 먼저 호출합니다. | |
| PROVIDER_ | 인증 만료 — 인증이 만료됐습니다. 로그인을 다시 호출합니다. | |
| PROVIDER_ | 업스트림 오류 — 기관 연결 실패, 응답 없음, 오류 응답, 읽을 수 없는 응답입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. |