급여·고지

1. 전자고지 조회 계약 로드nhis_edi.hr_payroll.edi_electronic_notices.contract

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

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

BMBB_400 EDI 전자고지 조회 화면의 계약·검색팝업(BMBB_401) 선행조건·selection_contract를 로드합니다.

로그인을 먼저 호출하고 업무 화면에 진입한 뒤 호출합니다. [국민건강보험공단 EDI 로그인]
params 는 빈 객체로 보내도 호출됩니다.

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	호출할 기관입니다. `nhis_edi`이 API 고정값 (기본값) 예시 : nhis_edi
action	string	-	Y	호출할 작업입니다. `nhis_edi.hr_payroll.edi_electronic_notices.contract`이 API 고정값 (기본값) 예시 : nhis_edi.hr_payroll.edi_electronic_notices.contract
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	N	작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fields	object	-	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: sandbox' \
  --header 'Idempotency-Key: demo-contract-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nhis_edi",
  "action": "nhis_edi.hr_payroll.edi_electronic_notices.contract",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

search_popup·detail_transactions·selection_contract·safety(query_only)를 확인합니다.

순번	변수명	설명
	search_popup	검색팝업 계약 정보 객체
	detail_transactions	상세 트랜잭션 계약 배열
	selection_contract	선택 계약 정보 객체
	safety	안전 플래그 (query_only)

json

// result.data
{
  "search_popup": {},
  "detail_transactions": [],
  "selection_contract": {},
  "safety": {}
}

2. 전자고지 상세 조회nhis_edi.hr_payroll.edi_electronic_notices.detail

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

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

선택된 전자고지의 BMBB_400 상세(combo·rows·business_datasets)를 조회합니다.

대상을 먼저 선택하거나, 선택 조건을 함께 보냅니다. [국민건강보험공단 EDI 로그인]
result.data.error_code=EDI_ELECTRONIC_NOTICE_DETAIL_EMPTY.
result.data 의 success=false · error_code=EDI_ELECTRONIC_NOTICE_OPTIONS_EMPTY — 선택할 전자고지가 없습니다. Job 은 실패로 끝나지 않습니다.
선택을 먼저 하면 params 를 빈 객체로 보낼 수 있습니다. 선택 조건을 주면 내부에서 선택을 다시 수행합니다.

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

변수명	타입	길이	필수	설명
row_index	number	-	N	전자고지 검색 결과에서 선택할 행 번호
row_key	string	-	N	전자고지 검색 결과 row 식별키
goji_yyyymm	string	6	N	고지연월 형식 : YYYYMM
goji_chasu	string	-	N	고지차수 GOJI_CHASU
wrt_chasu	string	-	N	작성 차수 WRT_CHASU
wrt_dup_seq	string	-	N	작성 중복순번 WRT_DUP_SEQ
unb_no	string	-	N	통합납부번호 UNB_NO

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": "nhis_edi",
  "action": "nhis_edi.hr_payroll.edi_electronic_notices.detail",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

combo·rows·summary·business_datasets를 확인합니다.

순번	변수명	설명
	combo	콤보 데이터 객체
	rows	전자고지 행 데이터 배열
	summary	요약 정보 객체
	business_datasets	데이터셋 객체 (키=데이터셋명)
	selected_option	조회한 고지 행 정보
	detail_sql_id	기관 상세 조회에 쓰인 조회 id
	row_count	상세 행 수

json

// result.data
{
  "combo": {},
  "rows": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "summary": {},
  "business_datasets": {},
  "selected_option": {},
  "detail_sql_id": "...",
  "row_count": 1
}

순번	오류 코드	발생 조건
	PROVIDER_VALIDATION_ERROR	행 없음 — 조건에 맞는 행을 찾지 못했습니다.

3. 전자고지 검색옵션 조회nhis_edi.hr_payroll.edi_electronic_notices.search_options

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

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

BMBB_401 전자고지 검색팝업에서 선택 가능한 고지 행(options)을 조회합니다.

로그인을 먼저 호출하고 업무 화면 진입까지 마친 뒤 호출합니다. [국민건강보험공단 EDI 로그인]
implementation_status=edi_electronic_notice_search_empty, error_code=null.
params 는 빈 객체로 보내도 호출됩니다. from_date 와 to_date 를 지정하지 않으면 3개월 전부터 오늘까지 조회합니다. doc_id 는 기본값이 BMBB_400 입니다.

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

변수명	타입	길이	필수	설명
from_date	string	8	N	조회기간 시작일 미입력 시 오늘 기준 3개월 전 형식 : YYYYMMDD
to_date	string	8	N	조회기간 종료일 미입력 시 오늘 형식 : YYYYMMDD
doc_id	string	-	N	문서 ID. 미입력 시 BMBB_400
insurance_type_code	string	-	N	보험종류 INSU_TYPE_CD

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_options-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nhis_edi",
  "action": "nhis_edi.hr_payroll.edi_electronic_notices.search_options",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

options·filters·selection_contract를 확인합니다.

순번	변수명	설명
	options	조회 가능한 전자고지 행 배열
	filters	검색 필터 정보 객체
	selection_contract	선택 계약 정보 객체
	row_count	옵션 행 수
	datasets	기관 응답 데이터셋 원본 (ds_List)

json

// result.data
{
  "options": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "filters": {},
  "selection_contract": {},
  "row_count": 1,
  "datasets": {}
}

순번	오류 코드	발생 조건
	PROVIDER_VALIDATION_ERROR	날짜 오류 — from_date · to_date 가 YYYYMMDD(또는 YYYY-MM-DD) 형식이 아니거나, from_date 가 to_date 보다 늦습니다.

4. 전자고지 검색행 선택nhis_edi.hr_payroll.edi_electronic_notices.select

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

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

검색팝업 options 1건을 선택하고 detail_selection 키를 세션에 저장합니다.

조회 옵션을 먼저 확인하고 호출합니다. 생략하면 내부에서 자동으로 조회합니다. [국민건강보험공단 EDI 로그인]
result.data 의 success=false · error_code=EDI_ELECTRONIC_NOTICE_OPTIONS_EMPTY — 선택할 전자고지가 없습니다. Job 은 실패로 끝나지 않습니다.
selector 생략 시 options 첫 행을 자동 선택합니다.

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

변수명	타입	길이	필수	설명
row_index	number	-	N	전자고지 검색 결과에서 선택할 행 번호
row_key	string	-	N	전자고지 검색 결과 row 식별키
goji_yyyymm	string	6	N	고지연월 형식 : YYYYMM
goji_chasu	string	-	N	고지차수 GOJI_CHASU
wrt_chasu	string	-	N	작성 차수 WRT_CHASU
wrt_dup_seq	string	-	N	작성 중복순번 WRT_DUP_SEQ
unb_no	string	-	N	통합납부번호 UNB_NO

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-select-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nhis_edi",
  "action": "nhis_edi.hr_payroll.edi_electronic_notices.select",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

selected_option·detail_selection·next_steps를 확인합니다.

순번	변수명	설명
	selected_option	선택된 전자고지 옵션 객체
	detail_selection	상세 조회용 선택 키 (세션에 저장됨)
	next_steps	다음 단계 힌트 배열
	selection_contract	선택 호출 계약 (다음 호출에 넘길 값)

json

// result.data
{
  "selected_option": {},
  "detail_selection": {},
  "next_steps": [],
  "selection_contract": {}
}

순번	오류 코드	발생 조건
	PROVIDER_VALIDATION_ERROR	행 없음 — 조건에 맞는 행을 찾지 못했습니다.

5. 건강보험료 개인별 상세 조회nhis_edi.hr_payroll.health_premiums.employee_details

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

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

건강 가입자고지(BMBB_020/040) 가입자별 보험료 상세(members)를 조회합니다.

보험료 요약 조회나 고지 선택을 먼저 호출합니다. [국민건강보험공단 EDI 로그인]
result.data.error_code=HEALTH_INSURANCE_NOTICE_DATASET_EMPTY.
row_index·row_key 생략 시 총괄 고지 행과 페어링된 가입자고지 행을 자동 선택합니다.

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

변수명	타입	길이	필수	설명
row_index	number	-	N	이전 목록/검색 결과에서 선택할 행 번호
row_text_contains	string	-	N	선택할 행의 텍스트 포함값
cell_text_contains	string	-	N	선택할 행 셀 텍스트 포함값
row_key	string	-	N	이전 목록/검색 결과 row 식별키
notice_year_month	string	6	N	고지연월 형식 : YYYYMM
goji_round	string	-	N	고지차수 GOJI_CHASU
from_date	string	8	N	조회기간 시작일 미입력 시 오늘 기준 3개월 전. 시작일은 종료일의 6개월 전까지 형식 : YYYYMMDD
to_date	string	8	N	조회기간 종료일 미입력 시 오늘. 조회 기간은 최대 6개월(시작일은 종료일의 6개월 전까지) 형식 : YYYYMMDD

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-employee_details-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nhis_edi",
  "action": "nhis_edi.hr_payroll.health_premiums.employee_details",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

members·summary·rows를 확인합니다.

순번	변수명	설명
	members	가입자별 보험료 상세 배열
	summary	요약 정보 객체
	notice	고지 기본정보 객체
	workplace	사업장 정보 객체

json

// result.data
{
  "members": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "summary": {},
  "notice": {},
  "workplace": {}
}

순번	오류 코드	발생 조건
	PROVIDER_VALIDATION_ERROR	행 오류 — 가입자 고지 행을 찾지 못했거나, 고른 행이 가입자 고지 행이 아닙니다.

6. 건강보험료 총괄 요약 조회nhis_edi.hr_payroll.health_premiums.summary

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

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

건강 사업장고지(BMBB_030/050) 총괄 요약(summary)을 조회합니다.

건강보험 총괄 고지를 먼저 선택하거나, 선택 조건을 함께 보냅니다. [국민건강보험공단 EDI 로그인]
result.data.error_code=HEALTH_PREMIUM_SUMMARY_DATASET_EMPTY.
선택을 먼저 하면 params 를 빈 객체로 보낼 수 있습니다.

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

변수명	타입	길이	필수	설명
row_index	number	-	N	이전 목록/검색 결과에서 선택할 행 번호
row_text_contains	string	-	N	선택할 행의 텍스트 포함값
cell_text_contains	string	-	N	선택할 행 셀 텍스트 포함값
row_key	string	-	N	이전 목록/검색 결과 row 식별키
notice_year_month	string	6	N	고지연월 형식 : YYYYMM
goji_round	string	-	N	고지차수 GOJI_CHASU
from_date	string	8	N	조회기간 시작일 미입력 시 오늘 기준 3개월 전. 시작일은 종료일의 6개월 전까지 형식 : YYYYMMDD
to_date	string	8	N	조회기간 종료일 미입력 시 오늘. 조회 기간은 최대 6개월(시작일은 종료일의 6개월 전까지) 형식 : YYYYMMDD

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-summary-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nhis_edi",
  "action": "nhis_edi.hr_payroll.health_premiums.summary",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

summary·rows·business_datasets를 확인합니다.

순번	변수명	설명
	summary	건강보험료 총괄 요약 객체
	notice	고지 기본정보 객체
	workplace	사업장 정보 객체
	selected_option	선택된 고지 행 정보

json

// result.data
{
  "summary": {},
  "notice": {},
  "workplace": {},
  "selected_option": {}
}

순번	오류 코드	발생 조건
	PROVIDER_VALIDATION_ERROR	행 오류 — 총괄 요약 행을 찾지 못했거나, 고른 행이 총괄 요약 행이 아닙니다.

7. 보험료 납부와 미납 내역 조회nhis_edi.hr_payroll.payment_status.list

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

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

보험료 납부·미납 내역(BMDZ_240)을 조회합니다.

로그인을 먼저 호출합니다. 세션에 회계·차수 정보가 남아 있으면 params 를 빈 객체로 보낼 수 있습니다. [국민건강보험공단 EDI 로그인]
implementation_status=premium_payment_status_empty, error_code=null.
insurance_code 기본 1(건강). search_year 기본 당해. goji_chasu·nation_finance_cd·unb_no는 세션 firm info에서 fallback.

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

변수명	타입	길이	필수	설명
insurance_code	string	-	N	보험종류 SEARCH_GUBUN. 기본 1(건강보험)
search_year	string	4	N	조회 연도 미입력 시 당해 형식 : YYYY
goji_chasu	string	-	N	고지 차수. 미입력 시 세션 ds_Si4nFirmInfo 또는 1
nation_finance_cd	string	-	N	회계코드. 미입력 시 세션 FINANCE_CD 또는 00
unb_no	string	-	N	통합납부번호. 미입력 시 세션 UNB_NO

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-list-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nhis_edi",
  "action": "nhis_edi.hr_payroll.payment_status.list",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

rows·filters·row_count를 확인합니다.

순번	변수명	설명
	rows	납부·미납 내역 행 배열
	filters	적용된 필터 정보 객체
	row_count	결과 건수
	datasets	기관 응답 데이터셋 원본 (ds_List)

json

// result.data
{
  "rows": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "filters": {},
  "row_count": 1,
  "datasets": {}
}

순번	오류 코드	발생 조건
	PROVIDER_VALIDATION_ERROR	필터 부족 — insurance_code=1(기본값) 조회인데 goji_chasu 나 nation_finance_cd 가 빈 값입니다. 두 값은 보내지 않으면 사업장 정보나 기본값으로 채워집니다.

8. 보수월액 보험료 고지 상세 조회nhis_edi.hr_payroll.premium_notices.detail

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

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

선택된 고지의 사업장 고지 업무 데이터셋(business_datasets·rows)을 조회합니다.

보험료 고지 선택을 먼저 호출하거나, 선택 조건을 함께 보냅니다. [국민건강보험공단 EDI 로그인]
result.data.error_code=PREMIUM_NOTICE_DETAIL_DATASET_EMPTY (business_datasets 비어 있음).
선택을 먼저 하면 params 를 빈 객체로 보낼 수 있습니다. 세션에 남은 선택 행을 사용합니다.

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

변수명	타입	길이	필수	설명
row_index	number	-	N	이전 목록/검색 결과에서 선택할 행 번호
row_text_contains	string	-	N	선택할 행의 텍스트 포함값
cell_text_contains	string	-	N	선택할 행 셀 텍스트 포함값
row_key	string	-	N	이전 목록/검색 결과 row 식별키
notice_year_month	string	6	N	고지연월 형식 : YYYYMM
goji_round	string	-	N	고지차수 GOJI_CHASU
from_date	string	8	N	조회기간 시작일 미입력 시 오늘 기준 3개월 전. 시작일은 종료일의 6개월 전까지 형식 : YYYYMMDD
to_date	string	8	N	조회기간 종료일 미입력 시 오늘. 조회 기간은 최대 6개월(시작일은 종료일의 6개월 전까지) 형식 : YYYYMMDD

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": "nhis_edi",
  "action": "nhis_edi.hr_payroll.premium_notices.detail",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

business_datasets·rows·summary를 확인합니다.

순번	변수명	설명
	business_datasets	사업장 고지 데이터셋 객체 (키=데이터셋명)
	rows	행 데이터 배열
	summary	고지 요약 정보 객체
	workplace	사업장 정보 (사업장관리번호, 사업자번호, 사업장명 등)
	notice	선택한 고지 정보
	selected_option	선택한 행 정보

json

// result.data
{
  "business_datasets": {},
  "rows": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "summary": {},
  "workplace": {},
  "notice": {},
  "selected_option": {}
}

9. 보수월액 보험료 고지 탐색nhis_edi.hr_payroll.premium_notices.search

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

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

보수월액 보험료 고지 팝업에서 선택 가능한 고지내역서 행(options)을 검색합니다.

로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [국민건강보험공단 EDI 로그인]
result.data.error_code=PREMIUM_NOTICE_SEARCH_EMPTY.
params 는 빈 객체로 보내도 호출됩니다. 날짜와 필터 규칙은 수신 문서 조회와 같습니다.

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

변수명	타입	길이	필수	설명
row_text_contains	string	-	N	선택 후보 고지 행 텍스트 포함값. 검색 결과 후처리 필터
cell_text_contains	string	-	N	선택 후보 고지 셀 텍스트 포함값. 검색 결과 후처리 필터
notice_year_month	string	6	N	고지연월 형식 : YYYYMM
goji_round	string	-	N	고지차수 GOJI_CHASU
from_date	string	8	N	조회기간 시작일 미입력 시 오늘 기준 3개월 전. 시작일은 종료일의 6개월 전까지 형식 : YYYYMMDD
to_date	string	8	N	조회기간 종료일 미입력 시 오늘. 조회 기간은 최대 6개월(시작일은 종료일의 6개월 전까지) 형식 : YYYYMMDD

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": "nhis_edi",
  "action": "nhis_edi.hr_payroll.premium_notices.search",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

options·selection_contract·workflow_contract를 확인합니다.

순번	변수명	설명
	options	고지내역서 행 배열
	selection_contract	선택 계약 정보 객체
	workflow_contract	워크플로우 계약 정보 객체
	row_count	고지 옵션 행 수

json

// result.data
{
  "options": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "selection_contract": {},
  "workflow_contract": {},
  "row_count": 1
}

10. 보수월액 보험료 고지 선택nhis_edi.hr_payroll.premium_notices.select

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

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

고지 1건을 선택하고 세션에 selected_option·next_steps를 저장합니다.

목록 조회로 선택 가능한 옵션을 먼저 확인한 뒤 호출합니다. [국민건강보험공단 EDI 로그인]
row_index·row_key 생략 시 필터 후 첫 고지내역서 행을 자동 선택합니다.

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

변수명	타입	길이	필수	설명
row_index	number	-	N	이전 목록/검색 결과에서 선택할 행 번호
row_text_contains	string	-	N	선택할 행의 텍스트 포함값
cell_text_contains	string	-	N	선택할 행 셀 텍스트 포함값
row_key	string	-	N	이전 목록/검색 결과 row 식별키
notice_year_month	string	6	N	고지연월 형식 : YYYYMM
goji_round	string	-	N	고지차수 GOJI_CHASU
from_date	string	8	N	조회기간 시작일 미입력 시 오늘 기준 3개월 전. 시작일은 종료일의 6개월 전까지 형식 : YYYYMMDD
to_date	string	8	N	조회기간 종료일 미입력 시 오늘. 조회 기간은 최대 6개월(시작일은 종료일의 6개월 전까지) 형식 : YYYYMMDD

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-select-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nhis_edi",
  "action": "nhis_edi.hr_payroll.premium_notices.select",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

selected_option·next_steps를 확인합니다. 이후 detail·health_premiums에 params {} 가능.

순번	변수명	설명
	selected_option	선택된 고지 행 정보 객체
	selection	선택 컨텍스트 (이후 상세 API에서 재사용)
	next_steps	다음 단계 힌트 배열
	selection_contract	선택 호출 계약 (다음 호출에 넘길 값)

json

// result.data
{
  "selected_option": {},
  "selection": {},
  "next_steps": [],
  "selection_contract": {}
}

순번	오류 코드	발생 조건
	PROVIDER_VALIDATION_ERROR	행 없음·불일치 — 보험료 고지 행을 찾지 못했거나, 고른 행이 보험료 고지 행이 아닙니다.

11. 인사급여 처리결과 목록 조회nhis_edi.hr_payroll.processing_results.list

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

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

수신문서·보낸문서 목록을 합쳐 처리결과 rows(box=received|sent)로 반환합니다.

로그인을 먼저 호출하고 업무 화면 진입까지 마친 뒤 호출합니다. [국민건강보험공단 EDI 로그인]
params 는 빈 객체로 보내도 호출됩니다. notice_year_month 와 from_date·to_date 는 수신 문서 쪽 필터에 적용됩니다.

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

변수명	타입	길이	필수	설명
notice_year_month	string	6	N	고지연월 형식 : YYYYMM
goji_round	string	-	N	고지차수 GOJI_CHASU
from_date	string	8	N	조회기간 시작일 미입력 시 오늘 기준 3개월 전. 시작일은 종료일의 6개월 전까지 형식 : YYYYMMDD
to_date	string	8	N	조회기간 종료일 미입력 시 오늘. 조회 기간은 최대 6개월(시작일은 종료일의 6개월 전까지) 형식 : YYYYMMDD

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-list-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nhis_edi",
  "action": "nhis_edi.hr_payroll.processing_results.list",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

rows·received_count·sent_count·row_count 확인.

순번	변수명	설명
	rows	처리결과 행 배열 (box=received\|sent 포함)
	received_count	수신 건수
	sent_count	발신 건수
	row_count	전체 건수
	business	사업장 기본정보
	business_datasets	시스템 dataset을 제외한 업무 dataset
	download_contract	다운로드 기능 계약
	filters	실제 적용된 조회 조건
	insurance_symbols	보험별 사업장번호
	source_url	원천 NHIS EDI URL
	status_code	HTTP 또는 업무 상태 코드
	summary	합계·건수 요약

json

// result.data
{
  "rows": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "received_count": "...",
  "sent_count": "...",
  "row_count": "...",
  "business": {},
  "business_datasets": {},
  "download_contract": {},
  "filters": {},
  "insurance_symbols": {},
  "source_url": "...",
  "status_code": "...",
  "summary": {}
}

12. 보수월액 수신문서 일괄 상세 조회nhis_edi.hr_payroll.received_documents.batch_details

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

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

row_indexes에 지정한 여러 수신문서 행의 상세를 한 Job에서 일괄 조회합니다.

로그인을 먼저 호출합니다. 조회 옵션으로 행 번호를 확인한 뒤 row_index 를 지정합니다. [국민건강보험공단 EDI 로그인]
results[] 항목에 success=false·error_code=DETAIL_STRATEGY_UNRESOLVED 등이 포함될 수 있습니다.
row_indexes 배열 필수. notice_year_month·from_date/to_date는 options와 동일 규칙.

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

변수명	타입	길이	필수	설명
row_indexes	array	-	N	상세 조회할 행 번호 배열
notice_year_month	string	6	N	고지연월 형식 : YYYYMM
goji_round	string	-	N	고지차수 GOJI_CHASU
from_date	string	8	N	조회기간 시작일 미입력 시 오늘 기준 3개월 전. 시작일은 종료일의 6개월 전까지 형식 : YYYYMMDD
to_date	string	8	N	조회기간 종료일 미입력 시 오늘. 조회 기간은 최대 6개월(시작일은 종료일의 6개월 전까지) 형식 : YYYYMMDD
form_name	string	-	N	서식명. 받은문서 목록과 동일한 서식명 필터
document_status	string	-	N	문서상태. 전체/all, 신규/new, 열람/viewed 중 하나

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-batch_details-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nhis_edi",
  "action": "nhis_edi.hr_payroll.received_documents.batch_details",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

results[]에 행별 상세가 포함됩니다. success는 1건이라도 성공 시 true.

순번	변수명	설명
	results	행별 상세 결과 배열 (success·datasets·error_code 포함)
	requested_count	요청한 행 수
	succeeded_count	성공한 행 수
	failed_count	실패한 행 수

json

// result.data
{
  "results": [],
  "requested_count": 1
}

13. 보수월액 수신문서 상세 조회nhis_edi.hr_payroll.received_documents.detail

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

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

수신문서 1건의 Direct SSV 상세(datasets·visible_fields)를 조회합니다.

로그인을 먼저 호출합니다. 조회 옵션으로 행을 확인한 뒤 row_index 또는 row_key 로 지정하면 정확합니다. [국민건강보험공단 EDI 로그인]
result.data.error_code=DETAIL_STRATEGY_UNRESOLVED — 등록된 Direct SSV 전략이 행을 해석하지 못함.
row_index·row_key 또는 row_text_contains·notice_year_month 등 필터로 1건 지정.

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

변수명	타입	길이	필수	설명
row_index	number	-	N	이전 목록/검색 결과에서 선택할 행 번호
row_text_contains	string	-	N	선택할 행의 텍스트 포함값
cell_text_contains	string	-	N	선택할 행 셀 텍스트 포함값
row_key	string	-	N	이전 목록/검색 결과 row 식별키
notice_year_month	string	6	N	고지연월 형식 : YYYYMM
goji_round	string	-	N	고지차수 GOJI_CHASU
from_date	string	8	N	조회기간 시작일 미입력 시 오늘 기준 3개월 전. 시작일은 종료일의 6개월 전까지 형식 : YYYYMMDD
to_date	string	8	N	조회기간 종료일 미입력 시 오늘. 조회 기간은 최대 6개월(시작일은 종료일의 6개월 전까지) 형식 : YYYYMMDD
form_name	string	-	N	서식명. 받은문서 목록과 동일한 서식명 필터
document_status	string	-	N	문서상태. 전체/all, 신규/new, 열람/viewed 중 하나

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": "nhis_edi",
  "action": "nhis_edi.hr_payroll.received_documents.detail",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

datasets·visible_fields·detail_source를 확인합니다.

순번	변수명	설명
	datasets	문서 데이터셋 객체 (키=데이터셋명)
	visible_fields	화면 표시 필드 배열
	detail_source	상세 조회 소스 정보 객체
	row_index	행 번호
	document_id	기관 화면 문서 id
	document_title	문서 제목
	primary_row	대표 행
	typed	형식을 맞춰 정리한 상세 값
	detail_source_attempts	상세 조회 전략별 시도 결과
	network_evidence	기관 화면이 호출한 SQL·프로그램 내역(요청 본문은 길이만)
	visible_text	화면에 표시된 값을 합친 텍스트

json

// result.data
{
  "datasets": {},
  "visible_fields": [],
  "detail_source": "...",
  "row_index": 0,
  "document_id": "...",
  "document_title": "...",
  "primary_row": {},
  "typed": {},
  "detail_source_attempts": [],
  "network_evidence": [],
  "visible_text": "..."
}

순번	오류 코드	발생 조건
	PROVIDER_VALIDATION_ERROR	행 없음 — 조건에 맞는 행을 찾지 못했습니다.

14. 보수월액 수신문서 목록 조회nhis_edi.hr_payroll.received_documents.options

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

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

인사급여 수신문서(WETC_110) 목록을 조회합니다. 세션·target_view·primary list를 서버가 자동 확보합니다.

로그인을 먼저 호출한 뒤 같은 account_link_id 로 호출합니다. [국민건강보험공단 EDI 로그인]
row_count=0 — 별도 error_code 없음.
params 는 빈 객체로 보내도 호출됩니다. from_date 와 to_date 를 지정하지 않으면 3개월 전부터 오늘까지 조회하고, 조회 기간은 최대 6개월입니다(시작일은 종료일의 6개월 전까지). notice_year_month 를 주면 수신일 조건을 그 고지월 범위로 넓힙니다.

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

변수명	타입	길이	필수	설명
row_text_contains	string	-	N	선택할 문서/고지 행 텍스트 포함값. 받은문서 화면 row_text 후처리 필터
cell_text_contains	string	-	N	선택할 문서 행의 셀 텍스트 포함값. 받은문서 화면 후처리 필터
notice_year_month	string	6	N	고지연월 받은문서 row를 고지연월 기준으로 좁힐 때 사용 형식 : YYYYMM
goji_round	string	-	N	고지차수 GOJI_CHASU
from_date	string	8	N	조회기간 시작일 미입력 시 오늘 기준 3개월 전. 시작일은 종료일의 6개월 전까지 형식 : YYYYMMDD
to_date	string	8	N	조회기간 종료일 미입력 시 오늘. 조회 기간은 최대 6개월(시작일은 종료일의 6개월 전까지) 형식 : YYYYMMDD
form_name	string	-	N	서식명. 받은문서 목록에서 특정 서식명만 후처리 필터
document_status	string	-	N	문서상태. 전체/all, 신규/new, 열람/viewed 중 하나

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-options-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nhis_edi",
  "action": "nhis_edi.hr_payroll.received_documents.options",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

list_rows·row_count·response_dataset_names를 확인합니다.

순번	변수명	설명
	list_rows	수신문서 행 배열
	row_count	목록 건수
	response_dataset_names	반환된 데이터셋 이름 배열

json

// result.data
{
  "list_rows": [
    { "row_index": 0, "row_key": "...", "row_text": "...", "received_date": "2026-06-01" }
  ],
  "row_count": 1,
  "response_dataset_names": ["WETC_110"]
}

순번	오류 코드	발생 조건
	PROVIDER_VALIDATION_ERROR	날짜 오류 — from_date · to_date 가 YYYYMMDD(또는 YYYY-MM-DD) 형식이 아니거나, from_date 가 to_date 보다 늦거나, 시작일이 종료일의 6개월 전보다 이릅니다.

15. 보수총액 통보서 상세 조회nhis_edi.hr_payroll.salary_total_notice.detail

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

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

BMCB_070 보수총액 통보서 상세(rows·business_datasets)를 조회합니다.

로그인을 먼저 호출합니다. 수신 문서 조회 옵션을 먼저 확인하면 조건을 정확히 지정할 수 있습니다. [국민건강보험공단 EDI 로그인]
success=false. result.data.error_code=BMCB_070_ROW_NOT_FOUND.
selector 생략 시 row_text_contains 기본 보수총액.

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

변수명	타입	길이	필수	설명
row_index	number	-	N	이전 목록/검색 결과에서 선택할 행 번호
row_text_contains	string	-	N	선택할 행의 텍스트 포함값
cell_text_contains	string	-	N	선택할 행 셀 텍스트 포함값
row_key	string	-	N	이전 목록/검색 결과 row 식별키
notice_year_month	string	6	N	고지연월 형식 : YYYYMM
goji_round	string	-	N	고지차수 GOJI_CHASU
from_date	string	8	N	조회기간 시작일 미입력 시 오늘 기준 3개월 전. 시작일은 종료일의 6개월 전까지 형식 : YYYYMMDD
to_date	string	8	N	조회기간 종료일 미입력 시 오늘. 조회 기간은 최대 6개월(시작일은 종료일의 6개월 전까지) 형식 : YYYYMMDD

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": "nhis_edi",
  "action": "nhis_edi.hr_payroll.salary_total_notice.detail",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

rows·business_datasets 확인.

순번	변수명	설명
	rows	보수총액 통보서 행 데이터 배열
	business_datasets	데이터셋 객체 (키=데이터셋명)
	row_count	반환 행 수
	summary	요약 합계
	business	사업장 기본정보
	download_contract	다운로드 기능 계약
	filters	실제 적용된 조회 조건
	insurance_symbols	보험별 사업장번호
	received_count	받은문서 결과 수
	sent_count	보낸문서 결과 수
	source_url	원천 NHIS EDI URL
	status_code	HTTP 또는 업무 상태 코드

json

// result.data
{
  "rows": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "business_datasets": {},
  "row_count": "...",
  "summary": {},
  "business": {},
  "download_contract": {},
  "filters": {},
  "insurance_symbols": {},
  "received_count": "...",
  "sent_count": "...",
  "source_url": "...",
  "status_code": "..."
}

순번	오류 코드	발생 조건
	PROVIDER_VALIDATION_ERROR	양식 불일치 — 고른 행이 이 조회의 서식이 아닙니다.

16. 연말정산 산출내역서 조회nhis_edi.hr_payroll.year_end_settlement.detail

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

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

BMCB_060 연말정산 산출내역서 상세(business_datasets·rows)를 조회합니다.

로그인을 먼저 호출합니다. 수신 문서 조회 옵션에서 해당 서식(BMCB_060) 행을 먼저 확인하면 정확합니다. [국민건강보험공단 EDI 로그인]
result.data.error_code=YEAR_END_SETTLEMENT_DATASET_EMPTY.
selector 생략 시 row_text_contains 기본 연말정산. received_documents와 동일 날짜·필터.

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

변수명	타입	길이	필수	설명
row_index	number	-	N	이전 목록/검색 결과에서 선택할 행 번호
row_text_contains	string	-	N	선택할 행의 텍스트 포함값
cell_text_contains	string	-	N	선택할 행 셀 텍스트 포함값
row_key	string	-	N	이전 목록/검색 결과 row 식별키
notice_year_month	string	6	N	고지연월 형식 : YYYYMM
goji_round	string	-	N	고지차수 GOJI_CHASU
from_date	string	8	N	조회기간 시작일 미입력 시 오늘 기준 3개월 전. 시작일은 종료일의 6개월 전까지 형식 : YYYYMMDD
to_date	string	8	N	조회기간 종료일 미입력 시 오늘. 조회 기간은 최대 6개월(시작일은 종료일의 6개월 전까지) 형식 : YYYYMMDD
form_name	string	-	N	서식명. 기본값은 직장가입자 보험료 연말정산 산출내역서
document_status	string	-	N	받은문서 상태 필터. 전체/all, 신규/new, 열람/viewed

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": "nhis_edi",
  "action": "nhis_edi.hr_payroll.year_end_settlement.detail",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

rows·business_datasets·summary 확인.

순번	변수명	설명
	rows	연말정산 행 데이터 배열
	business_datasets	데이터셋 객체 (키=데이터셋명)
	summary	산출내역 요약 객체
	selected_option	선택한 행 정보
	filters	이번 조회에 쓰인 필터

json

// result.data
{
  "rows": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "business_datasets": {},
  "summary": {},
  "selected_option": {},
  "filters": {}
}

순번	오류 코드	발생 조건
	PROVIDER_VALIDATION_ERROR	행 없음 — 연말정산 서식(BMCB_060) 행을 찾지 못했습니다.