정보조회

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

MCP 도구 이름 comwel__info__individual_billed_premium__detail

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

지정한 근로자의 산재보험과 고용보험 월별 부과 내역을 조회합니다.

고용산재 세션 로그인 뒤, individual_billed_premium.worker_select 응답의 detail_key(worker_resident_no · worker_record_no · labor_provider_yn 셋 다 필수)를 그대로 넘깁니다. labor_provider_yn 은 Y 또는 N 만 받습니다. [근로복지공단 로그인]
sandbox 환경에서는 실제 근로복지공단에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
사업장관리번호(business_management_no)는 선택입니다. 생략하면 세션에 저장된 값을 씁니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `comwel`이 API 고정값 (기본값) 예시 : comwel
action	string	-	Y	호출할 작업입니다. `comwel.info.individual_billed_premium.detail`이 API 고정값 (기본값) 예시 : comwel.info.individual_billed_premium.detail
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	필수	설명
business_management_no	string	N	-
insurance_month	string	N	-
insurance_year	string	Y	-
labor_provider_yn	string	Y	-
refund_reflection_yn	string	N	-
worker_record_no	string	Y	-
worker_resident_no	string	Y	-

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-detail-001' \
  --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

success 는 Job 이 성공하면 항상 true 로 고정된 값입니다(2026-09-15 정정 - 성패 판정에 쓸 수 없습니다). result.data 의 나머지 조회 결과 필드로 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	API_KEY	연동 ID(account_link_id)
	context	조회에 쓰인 사업장 컨텍스트 객체
	detail_key	이 상세 조회에 쓰인 근로자·조회조건 키 객체
	worker	조회 대상 근로자 정보 객체
	workplace	조회 대상 사업장 정보 객체
	row_counts	산재·고용 각각의 근로자월별·사업장월별 행 수 객체
	industrial_accident	산재보험 근로자월별·사업장월별 행 묶음 객체
	employment	고용보험 근로자월별·사업장월별 행 묶음 객체
	message	기관 안내 메시지 객체
	raw	기관 원본 응답 보존용 객체

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "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 에 파라미터 이름으로 옵니다(영문 원문 그대로일 수 있습니다). 재시도 불가로 표시됩니다.
	PROVIDER_TIMEOUT_CONNECT	연결 지연 — 근로복지공단 접속이 지연됐습니다. 재시도 가능으로 표시되므로 잠시 후 다시 호출합니다.
	PROVIDER_TIMEOUT_READ	응답 지연 — 근로복지공단 응답이 지연됐습니다. 재시도 가능으로 표시되므로 잠시 후 다시 호출합니다.
	PROVIDER_UNAVAILABLE	연결 오류 — 근로복지공단 접속에 실패했습니다. 잠시 후 다시 호출합니다.
	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: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

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

고용산재 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [근로복지공단 로그인]
sandbox 환경에서는 실제 근로복지공단에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
사업장관리번호(business_management_no)는 선택입니다. 생략하면 세션에 저장된 값을 씁니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `comwel`이 API 고정값 (기본값) 예시 : comwel
action	string	-	Y	호출할 작업입니다. `comwel.info.individual_billed_premium.worker_select`이 API 고정값 (기본값) 예시 : comwel.info.individual_billed_premium.worker_select
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	필수	설명
birth_ymd	string	Y	-
business_management_no	string	N	-
insurance_year	string	Y	-
worker_name	string	Y	-

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-worker_select-001' \
  --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

success 는 Job 이 성공하면 항상 true 로 고정된 값입니다(2026-09-15 정정 - 성패 판정에 쓸 수 없습니다). result.data 의 나머지 조회 결과 필드로 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	API_KEY	연동 ID(account_link_id)
	context	조회에 쓰인 사업장 컨텍스트 객체
	search_key	검색 조건 객체 - business_management_no · insurance_year · worker_name · birth_ymd
	selected_worker	검색 조건(성명 + 생년월일 6자리)에 정확히 맞은 근로자 1명 - 2026-09-15 정정: 이 필드가 오는 것 자체가 성공(정확히 1명 특정)의 증거입니다. 0명이면 조회가 실패하고 (대상 근로자 특정 실패), 2명 이상 겹쳐도 특정할 수 없어 역시 실패합니다(아래 오류표)
	detail_key	상세 조회(individual_billed_premium.detail)에 그대로 넘길 키 객체
	workers	기관이 성명으로 돌려준 근로자 목록 전체(생년월일 필터 전) - 2026-09-15 정정: 생년월일이 다른 동명이인이 함께 옵니다. 이 목록에 여러 명이 있는 것 자체는 정상이고, selected_worker 판정은 이 안에서 성명+생년월일이 둘 다 일치하는 사람만 봅니다
	raw	기관 원본 응답 보존용 객체

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "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 에 파라미터 이름으로 옵니다(영문 원문 그대로일 수 있습니다). 재시도 불가로 표시됩니다.
	PROVIDER_TIMEOUT_CONNECT	연결 지연 — 근로복지공단 접속이 지연됐습니다. 재시도 가능으로 표시되므로 잠시 후 다시 호출합니다.
	PROVIDER_TIMEOUT_READ	응답 지연 — 근로복지공단 응답이 지연됐습니다. 재시도 가능으로 표시되므로 잠시 후 다시 호출합니다.
	PROVIDER_UNAVAILABLE	연결 오류 — 근로복지공단 접속에 실패했습니다. 잠시 후 다시 호출합니다.
	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: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

부과고지 보험료 목록에서 행을 지정해 상세 내용을 확인합니다.

고용산재 세션 로그인 뒤, premium_billing_notice.search 응답의 detail_context 를 그대로, detail_candidates 중 조회할 행을 detail_keys 배열로 넘겨야 합니다(핸들러가 둘 다 필수로 검증합니다 - job_action_handlers_premium_billing_notice.py). 직접 만들어 보내면 거절됩니다. [근로복지공단 로그인]
sandbox 환경에서는 실제 근로복지공단에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `comwel`이 API 고정값 (기본값) 예시 : comwel
action	string	-	Y	호출할 작업입니다. `comwel.info.premium_billing_notice.detail`이 API 고정값 (기본값) 예시 : comwel.info.premium_billing_notice.detail
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	필수	설명
detail_context	string	Y	-
detail_keys	array	Y	-
insurance_type	string	N	-
worker_name	string	N	-
worker_resident_no	string	N	-

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-detail-001' \
  --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": "<필수>",
    "detail_keys": "<필수: array>"
  }
}'

Response

success 는 Job 이 성공하면 항상 true 로 고정된 값입니다(2026-09-15 정정 - 성패 판정에 쓸 수 없습니다). result.data 의 나머지 조회 결과 필드로 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	API_KEY	연동 ID(account_link_id)
	context	조회에 쓰인 사업장 컨텍스트 객체
	selected_insurance_type	선택된 보험 구분(산재 · 고용)
	selected_schema	선택된 조회 스키마 객체(내부 사용)
	detail_key	이 상세 조회에 실제로 쓰인 키 객체 - 상세 키가 1건일 때만 오고, 2건 이상 보내면 null 입니다(2026-09-15 정정, 그때는 detail_keys 를 봅니다)
	detail_keys	이번 조회에 실제로 쓰인 상세 키 목록(insurance_type 으로 걸러낸 결과) - 2026-09-15 정정: available_detail_keys 와 이름이 뒤바뀌어 있었습니다
	available_detail_keys	요청에 보낸 상세 키 목록 전체(그대로 돌려줍니다) - 2026-09-15 정정: detail_keys 와 이름이 뒤바뀌어 있었습니다
	details	행 단위 상세 결과 목록(기관 원본)
	detail_context	상세 조회 컨텍스트 객체
	representative_row	대표(사업주) 몫을 우리가 계산해 만든 행 - 칸 수는 고정이 아닙니다(2026-09-15 정정). 보험 구분별 고정 칸(산재 16 · 고용 25)에 근로자 식별 칸 3개와 그 조회에서 기관이 준 칸을 더한 합집합이라 최소 산재 19 · 고용 28이고 건마다 늘 수 있습니다
	reconciliation	정산 대사 결과 객체
	rows	보험 구분·기간별 행 묶음 객체 - 주의(2026-09-15 정정): 순수 기관 원본이 아닙니다. 마지막 원소는 우리가 계산해 붙인 representative_row 이고 그 보험료 칸은 그 페이지의 합계값입니다 - 이 배열을 그대로 합산하면 총액이 두 배가 됩니다
	period_rows	기간별 행 목록
	normalized_rows	표로 보기 좋게 다듬은 행 목록 - 보험료 · 정산액 등 계산된 값을 포함합니다. rows 와 같은 이유로 마지막 원소가 대표(사업주) 합성 행입니다(2026-09-15 추가) - 합계를 낼 때는 이 행을 빼거나 reconciliation 객체를 씁니다
	page_info	페이지 정보 목록
	raw	기관 원본 응답 보존용 객체

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "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 에 파라미터 이름으로 옵니다(영문 원문 그대로일 수 있습니다). 재시도 불가로 표시됩니다.
	PROVIDER_TIMEOUT_CONNECT	연결 지연 — 근로복지공단 접속이 지연됐습니다. 재시도 가능으로 표시되므로 잠시 후 다시 호출합니다.
	PROVIDER_TIMEOUT_READ	응답 지연 — 근로복지공단 응답이 지연됐습니다. 재시도 가능으로 표시되므로 잠시 후 다시 호출합니다.
	PROVIDER_UNAVAILABLE	연결 오류 — 근로복지공단 접속에 실패했습니다. 잠시 후 다시 호출합니다.
	INTERNAL_ERROR	그 밖의 오류 — 입력값이 올바르지 않거나(예: 대상 근로자를 찾지 못함), 근로복지공단이 오류를 반환했습니다. 세분화된 코드가 없으므로 보낸 파라미터 값부터 다시 확인하고, 계속되면 문의합니다.

4. 고용산재 부과고지 보험료 조회comwel.info.premium_billing_notice.search

MCP 도구 이름 comwel__info__premium_billing_notice__search

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

고용·산재보험 부과고지 보험료 내역을 고지 연월 기준으로 조회합니다.

고용산재 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [근로복지공단 로그인]
sandbox 환경에서는 실제 근로복지공단에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
사업장관리번호(business_management_no)는 선택입니다. 생략하면 세션에 저장된 값을 씁니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `comwel`이 API 고정값 (기본값) 예시 : comwel
action	string	-	Y	호출할 작업입니다. `comwel.info.premium_billing_notice.search`이 API 고정값 (기본값) 예시 : comwel.info.premium_billing_notice.search
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	필수	설명
billing_month	string	Y	-
billing_year	string	Y	-
business_management_no	string	N	-

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-search-001' \
  --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

success 는 Job 이 성공하면 항상 true 로 고정된 값입니다(2026-09-15 정정 - 성패 판정에 쓸 수 없습니다). result.data 의 나머지 조회 결과 필드로 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	API_KEY	연동 ID(account_link_id)
	context	조회에 쓰인 사업장 컨텍스트 객체(사업자등록번호 · 사업장관리번호 등)
	search_key	조회 조건 객체 - business_management_no · billing_year · billing_month
	summary	부과고지 보험료 요약 객체(기관 원본 그대로)
	detail_context	상세 조회(premium_billing_notice.detail)에 그대로 넘길 컨텍스트 객체
	detail_candidates	상세 조회에 넘길 수 있는 행 후보 목록 - 각 행은 insurance_key 등 조회·계산 조건을 담습니다
	platform_jobs	기관 화면 내부 처리 작업 목록(참고용)
	raw	기관 원본 응답 보존용 객체

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "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 에 파라미터 이름으로 옵니다(영문 원문 그대로일 수 있습니다). 재시도 불가로 표시됩니다.
	PROVIDER_TIMEOUT_CONNECT	연결 지연 — 근로복지공단 접속이 지연됐습니다. 재시도 가능으로 표시되므로 잠시 후 다시 호출합니다.
	PROVIDER_TIMEOUT_READ	응답 지연 — 근로복지공단 응답이 지연됐습니다. 재시도 가능으로 표시되므로 잠시 후 다시 호출합니다.
	PROVIDER_UNAVAILABLE	연결 오류 — 근로복지공단 접속에 실패했습니다. 잠시 후 다시 호출합니다.
	INTERNAL_ERROR	그 밖의 오류 — 입력값이 올바르지 않거나(예: 대상 근로자를 찾지 못함), 근로복지공단이 오류를 반환했습니다. 세분화된 코드가 없으므로 보낸 파라미터 값부터 다시 확인하고, 계속되면 문의합니다.