개발자 문서
서비스 소개키 관리자격증명 등록OpenAPI콘솔
API 레퍼런스

공공자료

1. 공개 서식 목록 조회nhis_edi.public.forms.list

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

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

CO::WETZ_032 공개 서식 다운로드 화면 contract를 조회합니다. 실제 파일 다운로드는 하지 않습니다.

Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • nhis_edi이 API 고정값 (기본값)

예시 : nhis_edi

actionstring-Y호출할 작업입니다.
  • nhis_edi.public.forms.list이 API 고정값 (기본값)

예시 : nhis_edi.public.forms.list

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-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-list-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nhis_edi",
  "action": "nhis_edi.public.forms.list",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'
Response
  • download_contract 확인. implementation_status=form_download_contract_only, row_count=0.
순번변수명설명
download_contract서식 다운로드 계약 정보 객체
row_count반환 행 수
rows조회 행
business사업장 기본정보
business_datasets시스템 dataset을 제외한 업무 dataset
filters실제 적용된 조회 조건
insurance_symbols보험별 사업장번호
received_count받은문서 결과 수
sent_count보낸문서 결과 수
source_url원천 NHIS EDI URL
status_codeHTTP 또는 업무 상태 코드
summary합계·건수 요약
json
// result.data
{
  "download_contract": {},
  "row_count": "...",
  "rows": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "business": {},
  "business_datasets": {},
  "filters": {},
  "insurance_symbols": {},
  "received_count": "...",
  "sent_count": "...",
  "source_url": "...",
  "status_code": "...",
  "summary": {}
}

2. 대외 공지사항 목록 조회nhis_edi.public.notices.list

MCP 도구 이름 nhis_edi__public__notices__list

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

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

건강보험 EDI 포털 공지사항 HTML 목록(rows)을 조회합니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [국민건강보험공단 EDI 로그인]
  • implementation_status=public_html_rows_empty.
  • success=false. result.data.error_code=PUBLIC_HTML_HTTP_ERROR.
  • params 는 빈 객체로 보내도 호출됩니다. page 는 기본값이 1 입니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • nhis_edi이 API 고정값 (기본값)

예시 : nhis_edi

actionstring-Y호출할 작업입니다.
  • nhis_edi.public.notices.list이 API 고정값 (기본값)

예시 : nhis_edi.public.notices.list

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
pagenumberN페이지 번호
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.public.notices.list",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'
Response
  • rows·source_url·status_code 확인.
순번변수명설명
rows공지사항 행 배열
source_url조회된 URL
status_codeHTTP 상태 코드
row_count반환 행 수
business사업장 기본정보
business_datasets시스템 dataset을 제외한 업무 dataset
download_contract다운로드 기능 계약
filters실제 적용된 조회 조건
insurance_symbols보험별 사업장번호
received_count받은문서 결과 수
sent_count보낸문서 결과 수
summary합계·건수 요약
json
// result.data
{
  "rows": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "source_url": "...",
  "status_code": "...",
  "row_count": "...",
  "business": {},
  "business_datasets": {},
  "download_contract": {},
  "filters": {},
  "insurance_symbols": {},
  "received_count": "...",
  "sent_count": "...",
  "summary": {}
}

3. 공개 자료실 목록 조회nhis_edi.public.resources.list

MCP 도구 이름 nhis_edi__public__resources__list

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

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

건강보험 EDI 포털 자료실 HTML 목록(rows)을 조회합니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [국민건강보험공단 EDI 로그인]
  • implementation_status=public_html_rows_empty.
  • params 는 빈 객체로 보내도 호출됩니다. page 는 기본값이 1 입니다.
Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • nhis_edi이 API 고정값 (기본값)

예시 : nhis_edi

actionstring-Y호출할 작업입니다.
  • nhis_edi.public.resources.list이 API 고정값 (기본값)

예시 : nhis_edi.public.resources.list

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
pagenumberN페이지 번호
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.public.resources.list",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'
Response
  • rows·source_url 확인.
순번변수명설명
rows자료실 행 배열
source_url조회된 URL
status_code기관 응답 상태 코드
row_count반환 행 수
business사업장 기본정보
business_datasets시스템 dataset을 제외한 업무 dataset
download_contract다운로드 기능 계약
filters실제 적용된 조회 조건
insurance_symbols보험별 사업장번호
received_count받은문서 결과 수
sent_count보낸문서 결과 수
summary합계·건수 요약
json
// result.data
{
  "rows": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "source_url": "...",
  "status_code": "...",
  "row_count": "...",
  "business": {},
  "business_datasets": {},
  "download_contract": {},
  "filters": {},
  "insurance_symbols": {},
  "received_count": "...",
  "sent_count": "...",
  "summary": {}
}