정보조회 - 근로복지공단
1. 개인별 부과고지보험료 상세comwel. info. individual_ billed_ premium. detail
MCP 도구 이름 comwel__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
지정한 근로자의 산재보험과 고용보험 월별 부과 내역을 조회합니다.
- 고용산재 세션 로그인 뒤, individual_billed_premium.worker_select 응답의 detail_key(worker_resident_no · worker_record_no · labor_provider_yn 셋 다 필수)를 그대로 넘깁니다. [근로복지공단 로그인]labor_provider_yn 은 Y 또는 N 만 받습니다.
- 사업장관리번호(business_management_no)는 선택입니다. 생략하면 세션에 저장된 값을 씁니다.
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 | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| business_ | string | N | 조회할 사업장의 사업장관리번호입니다. 숫자 이외의 글자(붙임표 등)는 지우고 읽으며, 보내지 않으면 로그인한 사업장의 번호를 쓰고 그것도 없으면 입력 오류로 거절합니다 | |
| insurance_ | string | N | 보험월(MM). 기관 요청에 실려 가지만 응답을 그 달로 줄이지 않습니다. 응답은 그 보험연도의 월별 내역 전체이고, 특정 달은 그 안에서 고릅니다 | |
| insurance_ | string | Y | 보험 연도입니다. 네 자리 연도(예: 2025)로 보내며 정수로 보내도 됩니다 | |
| labor_ | string | Y | 노무제공자 여부입니다. Y 또는 N 으로 보내며 그 밖의 값은 입력 오류로 거절합니다. 근로자 선택 조회(worker_select) 결과의 detail_key 에 들어 있는 값을 그대로 보냅니다 | |
| refund_ | string | N | 환수 처리 반영 여부를 정하는 기관 조회 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다 | |
| worker_ | string | Y | 근로자 관리번호입니다. 비어 있으면 입력 오류로 거절합니다. 근로자 선택 조회(worker_select) 결과의 detail_key 에 들어 있는 값을 그대로 보냅니다 | |
| worker_ | string | Y | 근로자의 주민등록번호입니다. 하이픈 없이 앞 여섯 자리와 뒤 일곱 자리를 모두 보내며, 숫자만 남기고 읽어 일곱 자리에 못 미치면 입력 오류로 거절합니다. 근로자 선택 조회(worker_select) 결과의 detail_key 에 들어 있는 값을 그대로 보냅니다 | |
| 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: detail-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "comwel",
"action": "comwel.info.individual_billed_premium.detail",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"insurance_year": "<필수>",
"labor_provider_yn": "<필수>",
"worker_record_no": "<필수>",
"worker_resident_no": "<필수>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- success 는 작업이 성공하면 항상 true 로 고정된 값이라 성패 판정에 쓸 수 없습니다. result.data 의 나머지 조회 결과 필드로 확인합니다.
- 아래 표의 industrial_accident.worker_monthly_rows[], employment.worker_monthly_rows[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 엑셀 파일 맨 윗줄의 머리글입니다.
- 아래 표의 줄은 엑셀로 내보내는 열이라 응답 행의 칸 전부가 아닐 수 있습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| API_ | string | 이 호출에 쓴 연동 계정의 ID(account_link_id)입니다. XBOSS API 키가 아닙니다. | |
| context | object | 조회에 쓰인 사업장 컨텍스트 객체 | |
| detail_ | object | 이 상세 조회에 쓰인 근로자·조회조건 키 객체 | |
| worker | string | number | boolean | object | array | null | 조회 대상 근로자 정보 객체 | |
| workplace | string | number | boolean | object | array | null | 조회 대상 사업장 정보 객체 | |
| row_ | object | 산재·고용 각각의 근로자월별·사업장월별 행 수 객체 | |
| industrial_ | object | 산재보험 근로자월별·사업장월별 행 묶음 객체 | |
| industrial_ | string | number | boolean | object | array | null | 보험 연월 | |
| industrial_ | string | number | boolean | object | array | null | 근무일수 | |
| industrial_ | string | number | boolean | object | array | null | 월평균보수 | |
| industrial_ | string | number | boolean | object | array | null | 산재보험료 | |
| industrial_ | string | number | boolean | object | array | null | 산재 사업자부담 보험료 | |
| industrial_ | string | number | boolean | object | array | null | 산재 근로자부담 보험료 | |
| industrial_ | string | number | boolean | object | array | null | 부담 합계 보험료 | |
| employment | object | 고용보험 근로자월별·사업장월별 행 묶음 객체 | |
| employment. | string | number | boolean | object | array | null | 보험 연월 | |
| employment. | string | number | boolean | object | array | null | 근무일수 | |
| employment. | string | number | boolean | object | array | null | 월평균보수 | |
| employment. | string | number | boolean | object | array | null | 고용안정 직업능력개발 보험료 | |
| employment. | string | number | boolean | object | array | null | 실업급여 사업자부담 보험료 | |
| employment. | string | number | boolean | object | array | null | 실업급여 근로자부담 보험료 | |
| message | string | number | boolean | object | array | null | 기관 안내 메시지 객체 | |
| raw | object | 기관 원본 응답 보존용 객체 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "comwel",
"action": "comwel.info.individual_billed_premium.detail",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 근로복지공단 세션이 없습니다. 고용산재 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 근로복지공단 세션이 만료됐습니다(응답 401 · 403). 고용산재 세션 로그인을 다시 호출합니다. | |
| VALIDATION_ | 필수 값 누락 — 어느 값이 빠졌는지는 error.message 에 한국어 안내 문장으로 옵니다(예: 근로자 성명을 입력해 주세요). 근로자 선택(worker_select) 결과에서 받는 값이 빠졌으면 그 결과에서 받는다는 안내가 함께 옵니다. 재시도 불가로 표시됩니다. | |
| VALIDATION_ | 입력값 오류 — 보낸 값의 형식이나 조합이 맞지 않습니다. 어느 값을 어떻게 고칠지는 error.message 에 한국어 문장으로 옵니다. 재시도 불가로 표시되니 값을 고친 뒤 다시 호출합니다. | |
| PROVIDER_ | 기관 응답 오류 — 근로복지공단 접속이 지연되거나 끊겼거나, 근로복지공단이 오류 상태나 읽을 수 없는 응답을 돌려줬습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다. | |
| INTERNAL_ | 그 밖의 오류 — 위에 적은 경우가 아닌 처리 오류입니다. 재시도 불가로 표시됩니다. 같은 요청이 계속 실패하면 서비스문의로 알립니다. |
2. 개인별 부과고지보험료 근로자 검색comwel. info. individual_ billed_ premium. worker_ select
MCP 도구 이름 comwel__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
보험연도와 성명, 생년월일로 개인별 부과고지보험료를 확인할 근로자를 찾아 지정합니다.
- 고용산재 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [근로복지공단 로그인]
- 사업장관리번호(business_management_no)는 선택입니다. 생략하면 세션에 저장된 값을 씁니다.
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 | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| birth_ | string | Y | 조회할 근로자의 생년월일입니다. 숫자 여섯 자리(YYMMDD)로 보내며 숫자 이외의 글자는 지우고 읽습니다. 성명과 이 값이 같은 근로자가 둘 이상이면 한 사람을 정하지 못해 입력 오류로 거절합니다 | |
| business_ | string | N | 조회할 사업장의 사업장관리번호입니다. 숫자 이외의 글자(붙임표 등)는 지우고 읽으며, 보내지 않으면 로그인한 사업장의 번호를 쓰고 그것도 없으면 입력 오류로 거절합니다 | |
| insurance_ | string | Y | 보험 연도입니다. 네 자리 연도(예: 2025)로 보내며 정수로 보내도 됩니다 | |
| worker_ | string | Y | 조회할 근로자의 성명입니다. 앞뒤 공백은 지우며 비어 있으면 입력 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: worker_select-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "comwel",
"action": "comwel.info.individual_billed_premium.worker_select",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"birth_ymd": "<필수>",
"insurance_year": "<필수>",
"worker_name": "<필수>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- success 는 작업이 성공하면 항상 true 로 고정된 값이라 성패 판정에 쓸 수 없습니다. result.data 의 나머지 조회 결과 필드로 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| API_ | string | 이 호출에 쓴 연동 계정의 ID(account_link_id)입니다. XBOSS API 키가 아닙니다. | |
| context | object | 조회에 쓰인 사업장 컨텍스트 객체 | |
| search_ | object | 검색 조건 객체 - business_management_no · insurance_year · worker_name · birth_ymd | |
| selected_ | object | 검색 조건(성명 + 생년월일 6자리)에 정확히 맞은 근로자 1명 - 이 필드가 오는 것 자체가 성공(정확히 1명 특정)의 증거입니다. 0명이면 조회가 실패하고(대상 근로자 특정 실패), 2명 이상 겹쳐도 특정할 수 없어 역시 실패합니다(아래 오류표) | |
| detail_ | object | 상세 조회(individual_billed_premium.detail)에 그대로 넘길 키 객체 | |
| workers | array | 기관이 성명으로 돌려준 근로자 목록 전체(생년월일 필터 전) - 생년월일이 다른 동명이인이 함께 옵니다. 이 목록에 여러 명이 있는 것 자체는 정상이고, selected_worker 판정은 이 안에서 성명+생년월일이 둘 다 일치하는 사람만 봅니다 | |
| raw | object | 기관 원본 응답 보존용 객체 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "comwel",
"action": "comwel.info.individual_billed_premium.worker_select",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 근로복지공단 세션이 없습니다. 고용산재 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 근로복지공단 세션이 만료됐습니다(응답 401 · 403). 고용산재 세션 로그인을 다시 호출합니다. | |
| VALIDATION_ | 필수 값 누락 — 어느 값이 빠졌는지는 error.message 에 한국어 안내 문장으로 옵니다(예: 근로자 성명을 입력해 주세요). 근로자 선택(worker_select) 결과에서 받는 값이 빠졌으면 그 결과에서 받는다는 안내가 함께 옵니다. 재시도 불가로 표시됩니다. | |
| VALIDATION_ | 입력값 오류 — 보낸 값의 형식이나 조합이 맞지 않습니다. 어느 값을 어떻게 고칠지는 error.message 에 한국어 문장으로 옵니다. 재시도 불가로 표시되니 값을 고친 뒤 다시 호출합니다. | |
| PROVIDER_ | 기관 응답 오류 — 근로복지공단 접속이 지연되거나 끊겼거나, 근로복지공단이 오류 상태나 읽을 수 없는 응답을 돌려줬습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다. | |
| RESOURCE_ | 대상 근로자 없음 — 성명(worker_name)·생년월일(birth_ymd)과 정확히 맞는 근로자를 찾지 못했습니다. 두 값을 다시 확인해 주세요. | |
| VALIDATION_ | 대상 근로자 여러 명 — 같은 성명·생년월일의 근로자가 둘 이상 조회되어 한 사람을 정하지 못했습니다. 두 값을 다시 확인해 주세요. | |
| INTERNAL_ | 그 밖의 오류 — 위에 적은 경우가 아닌 처리 오류입니다. 재시도 불가로 표시됩니다. 같은 요청이 계속 실패하면 서비스문의로 알립니다. |
3. 보험료 부과고지 상세comwel. info. premium_ billing_ notice. detail
MCP 도구 이름 comwel__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
부과고지 검색에서 받은 항목으로 근로자별 산재보험과 고용보험 산정 내역을 조회하고, 고지 합계와 맞는지 대조합니다.
- 고용산재 세션 로그인 뒤, premium_billing_notice.search 응답의 detail_context 를 그대로, detail_candidates 중 조회할 행을 detail_keys 배열로 넘겨야 합니다(둘 다 필수입니다). 직접 만들어 보내면 거절됩니다. [근로복지공단 로그인]
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 | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| detail_ | object | Y | 앞서 조회(search) 결과의 detail_context 객체를 고치지 말고 그대로 보냅니다. 객체가 아니거나 필요한 칸이 없으면 입력 오류로 거절합니다 | |
| detail_ | array | Y | 상세를 볼 항목의 배열입니다. 앞서 조회(search) 결과의 detail_candidates 항목을 그대로 담으며, 항목마다 보험 종류(산재 또는 고용)가 들어 있어야 하고 비어 있거나 객체가 아닌 항목이 있으면 입력 오류로 거절합니다 | |
| insurance_ | string | N | 상세를 볼 보험 종류입니다. employment 는 고용, industrial_accident 는 산재이며, 보내지 않으면 detail_keys 가 한 종류뿐일 때만 처리하고 산재와 고용이 함께 있으면 입력 오류로 거절합니다 | |
| worker_ | string | N | 기관 상세 조회 요청의 근로자 성명 칸에 그대로 넣습니다. 보내지 않으면 빈 값입니다. 성명을 보내면(공백만 보내면 지정한 것으로 보지 않습니다) 기관이 그 근로자의 행만 돌려주어 고지서 전체와 견줄 수 없으므로 응답의 대표 행(representative_row)은 만들지 않아 null 이고, 정산 대사(reconciliation)의 대표 몫 칸과 일치 표시 칸도 null 입니다 | |
| worker_ | string | N | 기관 상세 조회 요청의 근로자 주민등록번호 칸에 숫자만 남겨 넣습니다. 보내지 않으면 빈 값입니다. 숫자가 하나라도 있으면 성명을 보낸 것과 같이 근로자를 지정한 호출로 보므로 응답의 대표 행(representative_row)은 만들지 않아 null 이고, 정산 대사(reconciliation)의 대표 몫 칸과 일치 표시 칸도 null 입니다 | |
| 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: detail-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "comwel",
"action": "comwel.info.premium_billing_notice.detail",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"detail_context": "<필수: object>",
"detail_keys": "<필수: array>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- success 는 작업이 성공하면 항상 true 로 고정된 값이라 성패 판정에 쓸 수 없습니다. result.data 의 나머지 조회 결과 필드로 확인합니다.
- 아래 표의 normalized.industrial_accident[], normalized.employment[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 엑셀 파일 맨 윗줄의 머리글입니다.
- 아래 표의 줄은 엑셀로 내보내는 열이라 응답 행의 칸 전부가 아닐 수 있습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| API_ | string | 이 호출에 쓴 연동 계정의 ID(account_link_id)입니다. XBOSS API 키가 아닙니다. | |
| context | object | 조회에 쓰인 사업장 컨텍스트 객체 | |
| selected_ | string | null | 선택된 보험 구분(산재 · 고용) | |
| selected_ | object | null | 선택된 조회 스키마 객체(내부 사용) | |
| detail_ | object | null | 이 상세 조회에 실제로 쓰인 키 객체 - 상세 키가 1건일 때만 오고, 2건 이상 보내면 null 입니다(그때는 detail_keys 를 봅니다) | |
| detail_ | array | 이번 조회에 실제로 쓰인 상세 키 목록(insurance_type 으로 걸러낸 결과) | |
| available_ | array | 요청에 보낸 상세 키 목록 전체(그대로 돌려줍니다) | |
| details | array | 행 단위 상세 결과 목록(기관 원본) - 기관 호출 하나가 원소 하나입니다. detail_keys 에 같은 사업장의 행을 여럿 보내도 기관은 한 번만 부르므로 근로자 행이 겹쳐 나오지 않습니다. 각 원소에는 그 호출이 대표하는 detail_keys, representative_row, reconciliation 도 함께 실립니다 | |
| detail_ | object | 상세 조회 컨텍스트 객체 | |
| representative_ | object | null | 대표(사업주) 몫을 계산해 만든 행 - 칸 수는 고정이 아닙니다. 보험 구분별 고정 칸(산재 16, 고용 25)에 근로자 식별 칸 3개와 그 조회에서 기관이 준 칸을 더한 합집합이라 최소 산재 19, 고용 28이고 건마다 늘 수 있습니다. 고용 조회에서 계산한 대표(사업주) 몫이 음수가 되면 행을 만들지 않고 null 입니다(작업은 실패하지 않습니다). 기관이 근로자 성명으로 행을 거르므로, 근로자를 지정해(worker_name 이나 worker_resident_no 를 보내) 부르면 고지서 전체의 합계에서 근로자 몫을 뺄 수 없어 산재와 고용 모두 행을 만들지 않고 null 입니다. 사업장이 둘 이상이면 이 칸은 null 이고 호출마다의 행은 details 의 각 원소에 있습니다 | |
| reconciliation | object | 정산 대사 결과 객체 - detail_keys 에 행을 하나 보내든 여럿 보내든 그 사업장 고지서 전체의 합계에 맞춥니다(고용 조회의 page_unemployment_total 은 그 고지서에 든 모든 월별 합계의 고용 실업급여를 더한 값입니다). 사업장이 둘 이상이면 금액은 호출들의 합이고, 일치 표시 칸(unemployment_matches_detail 등)은 모든 호출이 맞아야 true, 하나라도 어긋나면 false 입니다. 비교하지 못한 호출이 있으면 그 칸은 null 입니다. 기관이 근로자 성명으로 행을 거르므로, 근로자를 지정해(worker_name 이나 worker_resident_no 를 보내) 부르면 고지서 전체와 견줄 수 없어 대표 몫 칸(representative_unemployment_total, representative_stability_total)과 일치 표시 칸(unemployment_matches_detail, stability_matches_detail, 산재는 premium_matches_detail)이 null 입니다. 고지서 합계 칸(page_ 로 시작하는 칸)과 돌려받은 근로자 행의 합 칸은 그대로 옵니다 | |
| rows | object | 보험 구분별, 기간별 행 묶음 객체 - 주의: 순수 기관 원본이 아닙니다. 고른 보험 구분의 행 목록에는 기관 호출마다 근로자 행들 뒤에 계산해 붙인 representative_row 가 하나 붙고(만들 수 없으면 붙지 않습니다 - 고용 조회의 대표 몫이 음수이거나 근로자를 지정해 부를 때입니다), 그 행의 보험료 칸은 근로자 행에서 더한 값이 아니라 고지서 합계에서 계산한 값입니다 - 대표자 행이 붙어 있을 때 이 배열을 그대로 합산하면 합계가 어긋나니 근로자 행만 더하거나 reconciliation 객체를 씁니다 | |
| period_ | array | 기간별 행 목록 | |
| normalized_ | array | 표로 보기 좋게 다듬은 행 목록 - 보험료와 정산액 등 계산된 값을 포함합니다. rows 와 같은 이유로 대표(사업주) 합성 행이 들어 있습니다(대표자 행을 만들 수 없으면 없습니다 - 근로자를 지정해 부를 때도 없습니다) - 합계를 낼 때는 이 행을 빼거나 reconciliation 객체를 씁니다 | |
| normalized | object | 보험 구분별로 나눈 정리 행 목록 객체 - industrial_accident(산재)와 employment(고용) 두 칸이 항상 있고, 한 번의 조회는 한 종류만 담으므로 고르지 않은 쪽은 보통 빈 배열입니다. 고른 쪽의 내용은 normalized_rows 와 같습니다(엑셀 출력의 시트 둘이 읽는 자리입니다) | |
| normalized. | string | number | boolean | object | array | null | 순번 | |
| normalized. | string | 보험구분 | |
| normalized. | string | number | boolean | object | array | null | 근로자구분 | |
| normalized. | string | number | boolean | object | array | null | 근로자명 | |
| normalized. | string | number | boolean | object | array | null | 생년월일 | |
| normalized. | string | number | boolean | object | array | null | 자격취득일 | |
| normalized. | string | number | boolean | object | array | null | 자격상실일 | |
| normalized. | string | number | boolean | object | array | null | 산정 시작일 | |
| normalized. | string | number | boolean | object | array | null | 산정 종료일 | |
| normalized. | string | number | boolean | object | array | null | 근무일수 | |
| normalized. | string | number | boolean | object | array | null | 월평균보수 | |
| normalized. | string | number | boolean | object | array | null | 산정보험료 | |
| normalized. | string | number | boolean | object | array | null | 현재 산정보험료 | |
| normalized. | string | number | boolean | object | array | null | 이전 산정보험료 | |
| normalized. | string | number | boolean | object | array | null | 정산보험료 | |
| normalized. | string | number | boolean | object | array | null | 퇴직정산보험료 | |
| normalized. | string | number | boolean | object | array | null | 합계보험료 | |
| normalized. | string | number | boolean | object | array | null | 순번 | |
| normalized. | string | 보험구분 | |
| normalized. | string | number | boolean | object | array | null | 근로자구분 | |
| normalized. | string | number | boolean | object | array | null | 근로자명 | |
| normalized. | string | number | boolean | object | array | null | 생년월일 | |
| normalized. | string | number | boolean | object | array | null | 자격취득일 | |
| normalized. | string | number | boolean | object | array | null | 자격상실일 | |
| normalized. | string | number | boolean | object | array | null | 산정 시작일 | |
| normalized. | string | number | boolean | object | array | null | 산정 종료일 | |
| normalized. | string | number | boolean | object | array | null | 근무일수 | |
| normalized. | string | number | boolean | object | array | null | 월평균보수 | |
| normalized. | string | number | boolean | object | array | null | 근로자 실업급여 | |
| normalized. | string | number | boolean | object | array | null | 사업주 실업급여 | |
| normalized. | string | number | boolean | object | array | null | 사업주 고용안정 직업능력개발 | |
| normalized. | string | number | boolean | object | array | null | 현재 근로자 실업급여 | |
| normalized. | string | number | boolean | object | array | null | 현재 사업주 실업급여 | |
| normalized. | string | number | boolean | object | array | null | 현재 사업주 고용안정 직업능력개발 | |
| normalized. | string | number | boolean | object | array | null | 근로자 실업급여 합계 | |
| normalized. | string | number | boolean | object | array | null | 사업주 실업급여 합계 | |
| normalized. | string | number | boolean | object | array | null | 사업주 고용안정 직업능력개발 합계 | |
| page_ | array | 페이지 정보 목록 | |
| raw | object | 기관 원본 응답 보존용 객체 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "comwel",
"action": "comwel.info.premium_billing_notice.detail",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 근로복지공단 세션이 없습니다. 고용산재 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 근로복지공단 세션이 만료됐습니다(응답 401 · 403). 고용산재 세션 로그인을 다시 호출합니다. | |
| VALIDATION_ | 필수 값 누락 — 어느 값이 빠졌는지는 error.message 에 한국어 안내 문장으로 옵니다(예: 부과 월을 01 부터 12 사이로 입력해 주세요). 부과고지 검색(search) 결과에서 받는 값(detail_keys, detail_context)이 빠졌으면 그 값을 고치지 않고 그대로 보내라는 안내가 옵니다. 재시도 불가로 표시됩니다. | |
| VALIDATION_ | 입력값 오류 — 보낸 값의 형식이나 조합이 맞지 않습니다. 어느 값을 어떻게 고칠지는 error.message 에 한국어 문장으로 옵니다. 재시도 불가로 표시되니 값을 고친 뒤 다시 호출합니다. | |
| PROVIDER_ | 기관 응답 오류 — 근로복지공단 접속이 지연되거나 끊겼거나, 근로복지공단이 오류 상태나 읽을 수 없는 응답을 돌려줬습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다. | |
| VALIDATION_ | 상세 키 불일치 — 보낸 detail_keys 가 함께 보낸 detail_context 와 맞지 않습니다(다른 조회 결과의 값이 섞였거나 값을 고친 경우). error.message 에 고칠 방법이 한국어 문장으로 옵니다. 재시도 불가로 표시되니, 같은 부과고지 조회(premium_billing_notice.search) 결과에서 받은 detail_candidates 항목과 detail_context 를 고치지 않고 함께 보냅니다. | |
| INTERNAL_ | 그 밖의 오류 — 위에 적은 경우가 아닌 처리 오류입니다. 재시도 불가로 표시됩니다. 같은 요청이 계속 실패하면 서비스문의로 알립니다. |
4. 보험료 부과고지 검색comwel. info. premium_ billing_ notice. search
MCP 도구 이름 comwel__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
부과 연도와 월을 지정해 사업장에 고지된 산재보험료와 고용보험료의 월별 합계를 받고, 근로자별 상세 조회에 쓸 항목을 함께 돌려받습니다.
- 고용산재 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [근로복지공단 로그인]
- 사업장관리번호(business_management_no)는 선택입니다. 생략하면 세션에 저장된 값을 씁니다.
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 | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| billing_ | string | Y | 부과 월입니다. 1 에서 12 사이의 월로 보내며 한 자리 월은 앞에 0 을 붙여 읽습니다(1 은 01) | |
| billing_ | string | Y | 부과 연도입니다. 네 자리 연도(예: 2026)로 보내며 정수로 보내도 됩니다 | |
| business_ | string | N | 조회할 사업장의 사업장관리번호입니다. 숫자 이외의 글자(붙임표 등)는 지우고 읽으며, 보내지 않으면 로그인한 사업장의 번호를 쓰고 그것도 없으면 입력 오류로 거절합니다 | |
| 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: search-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "comwel",
"action": "comwel.info.premium_billing_notice.search",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"billing_month": "<필수>",
"billing_year": "<필수>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- success 는 작업이 성공하면 항상 true 로 고정된 값이라 성패 판정에 쓸 수 없습니다. result.data 의 나머지 조회 결과 필드로 확인합니다.
- 아래 표의 summary.industrial_accident[], summary.employment[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 엑셀 파일 맨 윗줄의 머리글입니다.
- 아래 표의 줄은 엑셀로 내보내는 열이라 응답 행의 칸 전부가 아닐 수 있습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| API_ | string | 이 호출에 쓴 연동 계정의 ID(account_link_id)입니다. XBOSS API 키가 아닙니다. | |
| context | object | 조회에 쓰인 사업장 컨텍스트 객체(사업자등록번호 · 사업장관리번호 등) | |
| search_ | object | 조회 조건 객체 - business_management_no · billing_year · billing_month | |
| summary | object | 부과고지 보험료 요약 객체(기관 원본 그대로) | |
| summary. | string | number | boolean | object | array | null | 부과고지 연월 | |
| summary. | string | number | boolean | object | array | null | 당월 산재보험료 | |
| summary. | string | number | boolean | object | array | null | 연간 산재보험료 | |
| summary. | string | number | boolean | object | array | null | 부과고지 연월 | |
| summary. | string | number | boolean | object | array | null | 당월 실업급여 보험료 | |
| summary. | string | number | boolean | object | array | null | 당월 고용안정 직업능력개발 보험료 | |
| summary. | string | number | boolean | object | array | null | 당월 고용보험료 합계 | |
| summary. | string | number | boolean | object | array | null | 연간 실업급여 보험료 | |
| summary. | string | number | boolean | object | array | null | 연간 고용안정 직업능력개발 보험료 | |
| summary. | string | number | boolean | object | array | null | 연간 고용보험료 합계 | |
| detail_ | object | 상세 조회(premium_billing_notice.detail)에 그대로 넘길 컨텍스트 객체 | |
| detail_ | array | 상세 조회에 넘길 수 있는 행 후보 목록 - 각 행은 insurance_key 등 조회·계산 조건을 담습니다 | |
| platform_ | string | number | boolean | object | array | null | 기관 화면 내부 처리 작업 목록(참고용) | |
| raw | object | 기관 원본 응답 보존용 객체 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "comwel",
"action": "comwel.info.premium_billing_notice.search",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 세션 없음 — 근로복지공단 세션이 없습니다. 고용산재 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다. | |
| PROVIDER_ | 세션 만료 — 근로복지공단 세션이 만료됐습니다(응답 401 · 403). 고용산재 세션 로그인을 다시 호출합니다. | |
| VALIDATION_ | 필수 값 누락 — 어느 값이 빠졌는지는 error.message 에 한국어 안내 문장으로 옵니다(예: 부과 월을 01 부터 12 사이로 입력해 주세요). 부과고지 검색(search) 결과에서 받는 값(detail_keys, detail_context)이 빠졌으면 그 값을 고치지 않고 그대로 보내라는 안내가 옵니다. 재시도 불가로 표시됩니다. | |
| VALIDATION_ | 입력값 오류 — 보낸 값의 형식이나 조합이 맞지 않습니다. 어느 값을 어떻게 고칠지는 error.message 에 한국어 문장으로 옵니다. 재시도 불가로 표시되니 값을 고친 뒤 다시 호출합니다. | |
| PROVIDER_ | 기관 응답 오류 — 근로복지공단 접속이 지연되거나 끊겼거나, 근로복지공단이 오류 상태나 읽을 수 없는 응답을 돌려줬습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다. | |
| RESOURCE_ | 대상 사업장 없음 — 보낸 사업장관리번호(business_management_no), 생략했다면 로그인 때 저장된 사업장관리번호가 이 계정의 사업장 목록에 없습니다. 값을 확인한 뒤 다시 호출합니다. | |
| INTERNAL_ | 그 밖의 오류 — 위에 적은 경우가 아닌 처리 오류입니다. 재시도 불가로 표시됩니다. 같은 요청이 계속 실패하면 서비스문의로 알립니다. |