개발자 문서
API 레퍼런스

정보조회 - 근로복지공단

1. 개인별 부과고지보험료 상세comwel.info.individual_billed_premium.detail

MCP 도구 이름 comwel__info__individual_billed_premium__detail

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 셋 다 필수)를 그대로 넘깁니다. [근로복지공단 로그인]
  • 사업장관리번호(business_management_no)는 선택입니다. 생략하면 세션에 저장된 값을 씁니다.

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호출할 기관입니다.
  • comwel이 API 고정값 (기본값)

예시 : comwel

actionstring-Y호출할 작업입니다.
  • comwel.info.individual_billed_premium.detail이 API 고정값 (기본값)

예시 : comwel.info.individual_billed_premium.detail

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
business_management_nostringN조회할 사업장의 사업장관리번호입니다. 숫자 이외의 글자(붙임표 등)는 지우고 읽으며, 보내지 않으면 로그인한 사업장의 번호를 쓰고 그것도 없으면 입력 오류로 거절합니다
insurance_monthstringN보험월(MM). 기관 요청에 실려 가지만 응답을 그 달로 줄이지 않습니다. 응답은 그 보험연도의 월별 내역 전체이고, 특정 달은 그 안에서 고릅니다
insurance_yearstringY보험 연도입니다. 네 자리 연도(예: 2025)로 보내며 정수로 보내도 됩니다
labor_provider_ynstringY노무제공자 여부입니다. Y 또는 N 으로 보내며 그 밖의 값은 입력 오류로 거절합니다. 근로자 선택 조회(worker_select) 결과의 detail_key 에 들어 있는 값을 그대로 보냅니다
refund_reflection_ynstringN환수 처리 반영 여부를 정하는 기관 조회 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 빈 값입니다
worker_record_nostringY근로자 관리번호입니다. 비어 있으면 입력 오류로 거절합니다. 근로자 선택 조회(worker_select) 결과의 detail_key 에 들어 있는 값을 그대로 보냅니다
worker_resident_nostringY근로자의 주민등록번호입니다. 하이픈 없이 앞 여섯 자리와 뒤 일곱 자리를 모두 보내며, 숫자만 남기고 읽어 일곱 자리에 못 미치면 입력 오류로 거절합니다. 근로자 선택 조회(worker_select) 결과의 detail_key 에 들어 있는 값을 그대로 보냅니다
output_formatsarrayN이 결과를 엑셀(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: 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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
API_KEYstring이 호출에 쓴 연동 계정의 ID(account_link_id)입니다. XBOSS API 키가 아닙니다.
contextobject조회에 쓰인 사업장 컨텍스트 객체
detail_keyobject이 상세 조회에 쓰인 근로자·조회조건 키 객체
workerstring | number | boolean | object | array | null조회 대상 근로자 정보 객체
workplacestring | number | boolean | object | array | null조회 대상 사업장 정보 객체
row_countsobject산재·고용 각각의 근로자월별·사업장월별 행 수 객체
industrial_accidentobject산재보험 근로자월별·사업장월별 행 묶음 객체
industrial_accident.worker_monthly_rows[].BOHEOM_YYMMstring | number | boolean | object | array | null보험 연월
industrial_accident.worker_monthly_rows[].GEUNMU_ILSUstring | number | boolean | object | array | null근무일수
industrial_accident.worker_monthly_rows[].MM_AVG_BOSU_PRCstring | number | boolean | object | array | null월평균보수
industrial_accident.worker_monthly_rows[].SJ_BHRstring | number | boolean | object | array | null산재보험료
industrial_accident.worker_monthly_rows[].SJ_SAEOPJA_BUDAM_BHRstring | number | boolean | object | array | null산재 사업자부담 보험료
industrial_accident.worker_monthly_rows[].SJ_GEUNROJA_BUDAM_BHRstring | number | boolean | object | array | null산재 근로자부담 보험료
industrial_accident.worker_monthly_rows[].BUDAM_SUM_BHRstring | number | boolean | object | array | null부담 합계 보험료
employmentobject고용보험 근로자월별·사업장월별 행 묶음 객체
employment.worker_monthly_rows[].BOHEOM_YYMMstring | number | boolean | object | array | null보험 연월
employment.worker_monthly_rows[].GEUNMU_ILSUstring | number | boolean | object | array | null근무일수
employment.worker_monthly_rows[].MM_AVG_BOSU_PRCstring | number | boolean | object | array | null월평균보수
employment.worker_monthly_rows[].GAJN_BHRstring | number | boolean | object | array | null고용안정 직업능력개발 보험료
employment.worker_monthly_rows[].SG_SAEOPJA_BUDAM_BHRstring | number | boolean | object | array | null실업급여 사업자부담 보험료
employment.worker_monthly_rows[].SG_GEUNROJA_BUDAM_BHRstring | number | boolean | object | array | null실업급여 근로자부담 보험료
messagestring | number | boolean | object | array | null기관 안내 메시지 객체
rawobject기관 원본 응답 보존용 객체
json
{
    "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_REQUIRED세션 없음 — 근로복지공단 세션이 없습니다. 고용산재 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 근로복지공단 세션이 만료됐습니다(응답 401 · 403). 고용산재 세션 로그인을 다시 호출합니다.
VALIDATION_INVALID_FIELD필수 값 누락 — 어느 값이 빠졌는지는 error.message 에 한국어 안내 문장으로 옵니다(예: 근로자 성명을 입력해 주세요). 근로자 선택(worker_select) 결과에서 받는 값이 빠졌으면 그 결과에서 받는다는 안내가 함께 옵니다. 재시도 불가로 표시됩니다.
VALIDATION_INVALID_FIELD입력값 오류 — 보낸 값의 형식이나 조합이 맞지 않습니다. 어느 값을 어떻게 고칠지는 error.message 에 한국어 문장으로 옵니다. 재시도 불가로 표시되니 값을 고친 뒤 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR기관 응답 오류 — 근로복지공단 접속이 지연되거나 끊겼거나, 근로복지공단이 오류 상태나 읽을 수 없는 응답을 돌려줬습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다.
INTERNAL_ERROR그 밖의 오류 — 위에 적은 경우가 아닌 처리 오류입니다. 재시도 불가로 표시됩니다. 같은 요청이 계속 실패하면 서비스문의로 알립니다.

2. 개인별 부과고지보험료 근로자 검색comwel.info.individual_billed_premium.worker_select

MCP 도구 이름 comwel__info__individual_billed_premium__worker_select

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

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

보험연도와 성명, 생년월일로 개인별 부과고지보험료를 확인할 근로자를 찾아 지정합니다.

  • 고용산재 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [근로복지공단 로그인]
  • 사업장관리번호(business_management_no)는 선택입니다. 생략하면 세션에 저장된 값을 씁니다.

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호출할 기관입니다.
  • comwel이 API 고정값 (기본값)

예시 : comwel

actionstring-Y호출할 작업입니다.
  • comwel.info.individual_billed_premium.worker_select이 API 고정값 (기본값)

예시 : comwel.info.individual_billed_premium.worker_select

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
birth_ymdstringY조회할 근로자의 생년월일입니다. 숫자 여섯 자리(YYMMDD)로 보내며 숫자 이외의 글자는 지우고 읽습니다. 성명과 이 값이 같은 근로자가 둘 이상이면 한 사람을 정하지 못해 입력 오류로 거절합니다
business_management_nostringN조회할 사업장의 사업장관리번호입니다. 숫자 이외의 글자(붙임표 등)는 지우고 읽으며, 보내지 않으면 로그인한 사업장의 번호를 쓰고 그것도 없으면 입력 오류로 거절합니다
insurance_yearstringY보험 연도입니다. 네 자리 연도(예: 2025)로 보내며 정수로 보내도 됩니다
worker_namestringY조회할 근로자의 성명입니다. 앞뒤 공백은 지우며 비어 있으면 입력 오류로 거절합니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: 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 의 나머지 조회 결과 필드로 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
API_KEYstring이 호출에 쓴 연동 계정의 ID(account_link_id)입니다. XBOSS API 키가 아닙니다.
contextobject조회에 쓰인 사업장 컨텍스트 객체
search_keyobject검색 조건 객체 - business_management_no · insurance_year · worker_name · birth_ymd
selected_workerobject검색 조건(성명 + 생년월일 6자리)에 정확히 맞은 근로자 1명 - 이 필드가 오는 것 자체가 성공(정확히 1명 특정)의 증거입니다. 0명이면 조회가 실패하고(대상 근로자 특정 실패), 2명 이상 겹쳐도 특정할 수 없어 역시 실패합니다(아래 오류표)
detail_keyobject상세 조회(individual_billed_premium.detail)에 그대로 넘길 키 객체
workersarray기관이 성명으로 돌려준 근로자 목록 전체(생년월일 필터 전) - 생년월일이 다른 동명이인이 함께 옵니다. 이 목록에 여러 명이 있는 것 자체는 정상이고, selected_worker 판정은 이 안에서 성명+생년월일이 둘 다 일치하는 사람만 봅니다
rawobject기관 원본 응답 보존용 객체
json
{
    "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_REQUIRED세션 없음 — 근로복지공단 세션이 없습니다. 고용산재 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 근로복지공단 세션이 만료됐습니다(응답 401 · 403). 고용산재 세션 로그인을 다시 호출합니다.
VALIDATION_INVALID_FIELD필수 값 누락 — 어느 값이 빠졌는지는 error.message 에 한국어 안내 문장으로 옵니다(예: 근로자 성명을 입력해 주세요). 근로자 선택(worker_select) 결과에서 받는 값이 빠졌으면 그 결과에서 받는다는 안내가 함께 옵니다. 재시도 불가로 표시됩니다.
VALIDATION_INVALID_FIELD입력값 오류 — 보낸 값의 형식이나 조합이 맞지 않습니다. 어느 값을 어떻게 고칠지는 error.message 에 한국어 문장으로 옵니다. 재시도 불가로 표시되니 값을 고친 뒤 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR기관 응답 오류 — 근로복지공단 접속이 지연되거나 끊겼거나, 근로복지공단이 오류 상태나 읽을 수 없는 응답을 돌려줬습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다.
RESOURCE_NOT_FOUND대상 근로자 없음 — 성명(worker_name)·생년월일(birth_ymd)과 정확히 맞는 근로자를 찾지 못했습니다. 두 값을 다시 확인해 주세요.
VALIDATION_INVALID_FIELD대상 근로자 여러 명 — 같은 성명·생년월일의 근로자가 둘 이상 조회되어 한 사람을 정하지 못했습니다. 두 값을 다시 확인해 주세요.
INTERNAL_ERROR그 밖의 오류 — 위에 적은 경우가 아닌 처리 오류입니다. 재시도 불가로 표시됩니다. 같은 요청이 계속 실패하면 서비스문의로 알립니다.

3. 보험료 부과고지 상세comwel.info.premium_billing_notice.detail

MCP 도구 이름 comwel__info__premium_billing_notice__detail

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

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

부과고지 검색에서 받은 항목으로 근로자별 산재보험과 고용보험 산정 내역을 조회하고, 고지 합계와 맞는지 대조합니다.

  • 고용산재 세션 로그인 뒤, premium_billing_notice.search 응답의 detail_context 를 그대로, detail_candidates 중 조회할 행을 detail_keys 배열로 넘겨야 합니다(둘 다 필수입니다). 직접 만들어 보내면 거절됩니다. [근로복지공단 로그인]

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호출할 기관입니다.
  • comwel이 API 고정값 (기본값)

예시 : comwel

actionstring-Y호출할 작업입니다.
  • comwel.info.premium_billing_notice.detail이 API 고정값 (기본값)

예시 : comwel.info.premium_billing_notice.detail

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
detail_contextobjectY앞서 조회(search) 결과의 detail_context 객체를 고치지 말고 그대로 보냅니다. 객체가 아니거나 필요한 칸이 없으면 입력 오류로 거절합니다
detail_keysarrayY상세를 볼 항목의 배열입니다. 앞서 조회(search) 결과의 detail_candidates 항목을 그대로 담으며, 항목마다 보험 종류(산재 또는 고용)가 들어 있어야 하고 비어 있거나 객체가 아닌 항목이 있으면 입력 오류로 거절합니다
insurance_typestringN상세를 볼 보험 종류입니다. employment 는 고용, industrial_accident 는 산재이며, 보내지 않으면 detail_keys 가 한 종류뿐일 때만 처리하고 산재와 고용이 함께 있으면 입력 오류로 거절합니다
worker_namestringN기관 상세 조회 요청의 근로자 성명 칸에 그대로 넣습니다. 보내지 않으면 빈 값입니다. 성명을 보내면(공백만 보내면 지정한 것으로 보지 않습니다) 기관이 그 근로자의 행만 돌려주어 고지서 전체와 견줄 수 없으므로 응답의 대표 행(representative_row)은 만들지 않아 null 이고, 정산 대사(reconciliation)의 대표 몫 칸과 일치 표시 칸도 null 입니다
worker_resident_nostringN기관 상세 조회 요청의 근로자 주민등록번호 칸에 숫자만 남겨 넣습니다. 보내지 않으면 빈 값입니다. 숫자가 하나라도 있으면 성명을 보낸 것과 같이 근로자를 지정한 호출로 보므로 응답의 대표 행(representative_row)은 만들지 않아 null 이고, 정산 대사(reconciliation)의 대표 몫 칸과 일치 표시 칸도 null 입니다
output_formatsarrayN이 결과를 엑셀(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: 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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
API_KEYstring이 호출에 쓴 연동 계정의 ID(account_link_id)입니다. XBOSS API 키가 아닙니다.
contextobject조회에 쓰인 사업장 컨텍스트 객체
selected_insurance_typestring | null선택된 보험 구분(산재 · 고용)
selected_schemaobject | null선택된 조회 스키마 객체(내부 사용)
detail_keyobject | null이 상세 조회에 실제로 쓰인 키 객체 - 상세 키가 1건일 때만 오고, 2건 이상 보내면 null 입니다(그때는 detail_keys 를 봅니다)
detail_keysarray이번 조회에 실제로 쓰인 상세 키 목록(insurance_type 으로 걸러낸 결과)
available_detail_keysarray요청에 보낸 상세 키 목록 전체(그대로 돌려줍니다)
detailsarray행 단위 상세 결과 목록(기관 원본) - 기관 호출 하나가 원소 하나입니다. detail_keys 에 같은 사업장의 행을 여럿 보내도 기관은 한 번만 부르므로 근로자 행이 겹쳐 나오지 않습니다. 각 원소에는 그 호출이 대표하는 detail_keys, representative_row, reconciliation 도 함께 실립니다
detail_contextobject상세 조회 컨텍스트 객체
representative_rowobject | null대표(사업주) 몫을 계산해 만든 행 - 칸 수는 고정이 아닙니다. 보험 구분별 고정 칸(산재 16, 고용 25)에 근로자 식별 칸 3개와 그 조회에서 기관이 준 칸을 더한 합집합이라 최소 산재 19, 고용 28이고 건마다 늘 수 있습니다. 고용 조회에서 계산한 대표(사업주) 몫이 음수가 되면 행을 만들지 않고 null 입니다(작업은 실패하지 않습니다). 기관이 근로자 성명으로 행을 거르므로, 근로자를 지정해(worker_name 이나 worker_resident_no 를 보내) 부르면 고지서 전체의 합계에서 근로자 몫을 뺄 수 없어 산재와 고용 모두 행을 만들지 않고 null 입니다. 사업장이 둘 이상이면 이 칸은 null 이고 호출마다의 행은 details 의 각 원소에 있습니다
reconciliationobject정산 대사 결과 객체 - 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_ 로 시작하는 칸)과 돌려받은 근로자 행의 합 칸은 그대로 옵니다
rowsobject보험 구분별, 기간별 행 묶음 객체 - 주의: 순수 기관 원본이 아닙니다. 고른 보험 구분의 행 목록에는 기관 호출마다 근로자 행들 뒤에 계산해 붙인 representative_row 가 하나 붙고(만들 수 없으면 붙지 않습니다 - 고용 조회의 대표 몫이 음수이거나 근로자를 지정해 부를 때입니다), 그 행의 보험료 칸은 근로자 행에서 더한 값이 아니라 고지서 합계에서 계산한 값입니다 - 대표자 행이 붙어 있을 때 이 배열을 그대로 합산하면 합계가 어긋나니 근로자 행만 더하거나 reconciliation 객체를 씁니다
period_rowsarray기간별 행 목록
normalized_rowsarray표로 보기 좋게 다듬은 행 목록 - 보험료와 정산액 등 계산된 값을 포함합니다. rows 와 같은 이유로 대표(사업주) 합성 행이 들어 있습니다(대표자 행을 만들 수 없으면 없습니다 - 근로자를 지정해 부를 때도 없습니다) - 합계를 낼 때는 이 행을 빼거나 reconciliation 객체를 씁니다
normalizedobject보험 구분별로 나눈 정리 행 목록 객체 - industrial_accident(산재)와 employment(고용) 두 칸이 항상 있고, 한 번의 조회는 한 종류만 담으므로 고르지 않은 쪽은 보통 빈 배열입니다. 고른 쪽의 내용은 normalized_rows 와 같습니다(엑셀 출력의 시트 둘이 읽는 자리입니다)
normalized.industrial_accident[].sequencestring | number | boolean | object | array | null순번
normalized.industrial_accident[].insurance_labelstring보험구분
normalized.industrial_accident[].worker_typestring | number | boolean | object | array | null근로자구분
normalized.industrial_accident[].worker_namestring | number | boolean | object | array | null근로자명
normalized.industrial_accident[].worker_birthdaystring | number | boolean | object | array | null생년월일
normalized.industrial_accident[].acquisition_datestring | number | boolean | object | array | null자격취득일
normalized.industrial_accident[].loss_datestring | number | boolean | object | array | null자격상실일
normalized.industrial_accident[].calculation_from_datestring | number | boolean | object | array | null산정 시작일
normalized.industrial_accident[].calculation_to_datestring | number | boolean | object | array | null산정 종료일
normalized.industrial_accident[].work_daysstring | number | boolean | object | array | null근무일수
normalized.industrial_accident[].monthly_average_paystring | number | boolean | object | array | null월평균보수
normalized.industrial_accident[].monthly_premiumstring | number | boolean | object | array | null산정보험료
normalized.industrial_accident[].current_calculated_premiumstring | number | boolean | object | array | null현재 산정보험료
normalized.industrial_accident[].previous_premiumstring | number | boolean | object | array | null이전 산정보험료
normalized.industrial_accident[].settlement_premiumstring | number | boolean | object | array | null정산보험료
normalized.industrial_accident[].retirement_settlement_premiumstring | number | boolean | object | array | null퇴직정산보험료
normalized.industrial_accident[].total_premiumstring | number | boolean | object | array | null합계보험료
normalized.employment[].sequencestring | number | boolean | object | array | null순번
normalized.employment[].insurance_labelstring보험구분
normalized.employment[].worker_typestring | number | boolean | object | array | null근로자구분
normalized.employment[].worker_namestring | number | boolean | object | array | null근로자명
normalized.employment[].worker_birthdaystring | number | boolean | object | array | null생년월일
normalized.employment[].acquisition_datestring | number | boolean | object | array | null자격취득일
normalized.employment[].loss_datestring | number | boolean | object | array | null자격상실일
normalized.employment[].calculation_from_datestring | number | boolean | object | array | null산정 시작일
normalized.employment[].calculation_to_datestring | number | boolean | object | array | null산정 종료일
normalized.employment[].work_daysstring | number | boolean | object | array | null근무일수
normalized.employment[].monthly_average_paystring | number | boolean | object | array | null월평균보수
normalized.employment[].worker_unemployment_premiumstring | number | boolean | object | array | null근로자 실업급여
normalized.employment[].employer_unemployment_premiumstring | number | boolean | object | array | null사업주 실업급여
normalized.employment[].employer_employment_stability_premiumstring | number | boolean | object | array | null사업주 고용안정 직업능력개발
normalized.employment[].current_worker_unemployment_premiumstring | number | boolean | object | array | null현재 근로자 실업급여
normalized.employment[].current_employer_unemployment_premiumstring | number | boolean | object | array | null현재 사업주 실업급여
normalized.employment[].current_employer_employment_stability_premiumstring | number | boolean | object | array | null현재 사업주 고용안정 직업능력개발
normalized.employment[].worker_unemployment_totalstring | number | boolean | object | array | null근로자 실업급여 합계
normalized.employment[].employer_unemployment_totalstring | number | boolean | object | array | null사업주 실업급여 합계
normalized.employment[].employer_employment_stability_totalstring | number | boolean | object | array | null사업주 고용안정 직업능력개발 합계
page_infoarray페이지 정보 목록
rawobject기관 원본 응답 보존용 객체
json
{
    "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_REQUIRED세션 없음 — 근로복지공단 세션이 없습니다. 고용산재 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 근로복지공단 세션이 만료됐습니다(응답 401 · 403). 고용산재 세션 로그인을 다시 호출합니다.
VALIDATION_INVALID_FIELD필수 값 누락 — 어느 값이 빠졌는지는 error.message 에 한국어 안내 문장으로 옵니다(예: 부과 월을 01 부터 12 사이로 입력해 주세요). 부과고지 검색(search) 결과에서 받는 값(detail_keys, detail_context)이 빠졌으면 그 값을 고치지 않고 그대로 보내라는 안내가 옵니다. 재시도 불가로 표시됩니다.
VALIDATION_INVALID_FIELD입력값 오류 — 보낸 값의 형식이나 조합이 맞지 않습니다. 어느 값을 어떻게 고칠지는 error.message 에 한국어 문장으로 옵니다. 재시도 불가로 표시되니 값을 고친 뒤 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR기관 응답 오류 — 근로복지공단 접속이 지연되거나 끊겼거나, 근로복지공단이 오류 상태나 읽을 수 없는 응답을 돌려줬습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다.
VALIDATION_INVALID_FIELD상세 키 불일치 — 보낸 detail_keys 가 함께 보낸 detail_context 와 맞지 않습니다(다른 조회 결과의 값이 섞였거나 값을 고친 경우). error.message 에 고칠 방법이 한국어 문장으로 옵니다. 재시도 불가로 표시되니, 같은 부과고지 조회(premium_billing_notice.search) 결과에서 받은 detail_candidates 항목과 detail_context 를 고치지 않고 함께 보냅니다.
INTERNAL_ERROR그 밖의 오류 — 위에 적은 경우가 아닌 처리 오류입니다. 재시도 불가로 표시됩니다. 같은 요청이 계속 실패하면 서비스문의로 알립니다.

MCP 도구 이름 comwel__info__premium_billing_notice__search

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

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

부과 연도와 월을 지정해 사업장에 고지된 산재보험료와 고용보험료의 월별 합계를 받고, 근로자별 상세 조회에 쓸 항목을 함께 돌려받습니다.

  • 고용산재 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [근로복지공단 로그인]
  • 사업장관리번호(business_management_no)는 선택입니다. 생략하면 세션에 저장된 값을 씁니다.

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호출할 기관입니다.
  • comwel이 API 고정값 (기본값)

예시 : comwel

actionstring-Y호출할 작업입니다.
  • comwel.info.premium_billing_notice.search이 API 고정값 (기본값)

예시 : comwel.info.premium_billing_notice.search

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
billing_monthstringY부과 월입니다. 1 에서 12 사이의 월로 보내며 한 자리 월은 앞에 0 을 붙여 읽습니다(1 은 01)
billing_yearstringY부과 연도입니다. 네 자리 연도(예: 2026)로 보내며 정수로 보내도 됩니다
business_management_nostringN조회할 사업장의 사업장관리번호입니다. 숫자 이외의 글자(붙임표 등)는 지우고 읽으며, 보내지 않으면 로그인한 사업장의 번호를 쓰고 그것도 없으면 입력 오류로 거절합니다
output_formatsarrayN이 결과를 엑셀(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: 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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
API_KEYstring이 호출에 쓴 연동 계정의 ID(account_link_id)입니다. XBOSS API 키가 아닙니다.
contextobject조회에 쓰인 사업장 컨텍스트 객체(사업자등록번호 · 사업장관리번호 등)
search_keyobject조회 조건 객체 - business_management_no · billing_year · billing_month
summaryobject부과고지 보험료 요약 객체(기관 원본 그대로)
summary.industrial_accident[].BUGWA_GOJI_YYMMstring | number | boolean | object | array | null부과고지 연월
summary.industrial_accident[].MM_SJ_BHRstring | number | boolean | object | array | null당월 산재보험료
summary.industrial_accident[].YY_SJ_BHRstring | number | boolean | object | array | null연간 산재보험료
summary.employment[].BUGWA_GOJI_YYMMstring | number | boolean | object | array | null부과고지 연월
summary.employment[].MM_SG_BHRstring | number | boolean | object | array | null당월 실업급여 보험료
summary.employment[].MM_GA_BHRstring | number | boolean | object | array | null당월 고용안정 직업능력개발 보험료
summary.employment[].MM_TOT_BHRstring | number | boolean | object | array | null당월 고용보험료 합계
summary.employment[].YY_SG_BHRstring | number | boolean | object | array | null연간 실업급여 보험료
summary.employment[].YY_GA_BHRstring | number | boolean | object | array | null연간 고용안정 직업능력개발 보험료
summary.employment[].YY_TOT_BHRstring | number | boolean | object | array | null연간 고용보험료 합계
detail_contextobject상세 조회(premium_billing_notice.detail)에 그대로 넘길 컨텍스트 객체
detail_candidatesarray상세 조회에 넘길 수 있는 행 후보 목록 - 각 행은 insurance_key 등 조회·계산 조건을 담습니다
platform_jobsstring | number | boolean | object | array | null기관 화면 내부 처리 작업 목록(참고용)
rawobject기관 원본 응답 보존용 객체
json
{
    "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_REQUIRED세션 없음 — 근로복지공단 세션이 없습니다. 고용산재 세션 로그인을 먼저 호출한 뒤 같은 account_link_id 로 다시 요청합니다.
PROVIDER_SESSION_EXPIRED세션 만료 — 근로복지공단 세션이 만료됐습니다(응답 401 · 403). 고용산재 세션 로그인을 다시 호출합니다.
VALIDATION_INVALID_FIELD필수 값 누락 — 어느 값이 빠졌는지는 error.message 에 한국어 안내 문장으로 옵니다(예: 부과 월을 01 부터 12 사이로 입력해 주세요). 부과고지 검색(search) 결과에서 받는 값(detail_keys, detail_context)이 빠졌으면 그 값을 고치지 않고 그대로 보내라는 안내가 옵니다. 재시도 불가로 표시됩니다.
VALIDATION_INVALID_FIELD입력값 오류 — 보낸 값의 형식이나 조합이 맞지 않습니다. 어느 값을 어떻게 고칠지는 error.message 에 한국어 문장으로 옵니다. 재시도 불가로 표시되니 값을 고친 뒤 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR기관 응답 오류 — 근로복지공단 접속이 지연되거나 끊겼거나, 근로복지공단이 오류 상태나 읽을 수 없는 응답을 돌려줬습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다.
RESOURCE_NOT_FOUND대상 사업장 없음 — 보낸 사업장관리번호(business_management_no), 생략했다면 로그인 때 저장된 사업장관리번호가 이 계정의 사업장 목록에 없습니다. 값을 확인한 뒤 다시 호출합니다.
INTERNAL_ERROR그 밖의 오류 — 위에 적은 경우가 아닌 처리 오류입니다. 재시도 불가로 표시됩니다. 같은 요청이 계속 실패하면 서비스문의로 알립니다.