개발자 문서
API 레퍼런스

검진 - 국민건강보험공단 EDI

1. 건강검진 대상자 상세 조회nhis_edi.health_checkups.targets.detail

MCP 도구 이름 nhis_edi__health_checkups__targets__detail

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

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

최근 석 달 안에 받은 건강검진 대상자 문서에서 검진년도와 통보일, 사무직과 비사무직 대상자 수, 사업장 주소와 연락처를 돌려줍니다.

  • 로그인을 먼저 호출합니다. 수신 문서 조회 옵션을 먼저 확인하면 조건을 정확히 지정할 수 있습니다. [국민건강보험공단 EDI 로그인]
  • success=false. result.data.error_code=GGAB_020_ROW_NOT_FOUND.
  • success=false. result.data.error_code=GGAB_020_DATASET_EMPTY (business_datasets 비어 있음).
  • selector 생략 시 row_text_contains 기본 건강검진.

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

예시 : nhis_edi

actionstring-Y호출할 작업입니다.
  • nhis_edi.health_checkups.targets.detail이 API 고정값 (기본값)

예시 : nhis_edi.health_checkups.targets.detail

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

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
row_indexnumber-N이전 목록/검색 결과에서 선택할 행 번호
row_text_containsstring-N선택할 행의 텍스트 포함값
cell_text_containsstring-N선택할 행 셀 텍스트 포함값
row_keystring-N이전 목록/검색 결과 row 식별키
notice_year_monthstring6N고지연월

형식 : YYYYMM

goji_roundstring-N고지차수 GOJI_CHASU
from_datestring8N조회기간 시작일. 미입력 시 오늘 기준 3개월 전. 시작일은 종료일의 6개월 전까지

형식 : YYYYMMDD

to_datestring8N조회기간 종료일. 미입력 시 오늘. 조회 기간은 최대 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: real_test' \
  --header "Idempotency-Key: detail-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nhis_edi",
  "action": "nhis_edi.health_checkups.targets.detail",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • rows·business_datasets 확인.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
successboolean상세를 읽어 업무 dataset 을 받았는지 여부(찾는 항목이 없거나 응답에 업무 dataset 이 하나도 없으면 false)
feature_namestring기능 식별자
phasestring단계(이 액션은 detail)
workflow_stepstring워크플로 단계
screen_idstring화면 식별자
route_kindstring라우트 종류
row_countnumber결과 행 수
rowsarray업무 dataset 의 결과 행 목록
business_datasetsobject시스템 dataset을 제외한 업무 dataset
summaryobject찾았는지와 dataset 별 행 수 요약 객체(matched, document_id, business_dataset_count, business_row_count, dataset_row_counts)
source_evidenceobject출처 증적 객체
error_codestring | number | boolean | object | array | null오류 코드(문제가 없으면 null, 항목을 못 찾으면 문서 번호가 앞에 붙은 ROW_NOT_FOUND 코드, 업무 dataset 이 없으면 문서 번호가 앞에 붙은 DATASET_EMPTY 코드)
implementation_statusstring | number | boolean | object | array | null구현 상태(문제가 없으면 null, 항목을 못 찾으면 lookup_row_not_found, 업무 dataset 이 없으면 lookup_dataset_empty)
json
// result.data
{
  "success": true,
  "feature_name": "...",
  "phase": "detail",
  "workflow_step": "health_checkup_targets_loaded",
  "screen_id": "...",
  "route_kind": "live",
  "row_count": 0,
  "rows": [],
  "business_datasets": {
    "...": {
      "rows": []
    }
  },
  "summary": {
    "matched": true,
    "document_id": "GGAB_020",
    "business_dataset_count": 1,
    "business_row_count": 0,
    "dataset_row_counts": {
      "...": 0
    }
  },
  "source_evidence": {
    "screenshot": "...",
    "xfdl": "...",
    "sql_id": "...",
    "page_link_id": "...",
    "selected_row": {},
    "detail_source": "...",
    "detail_source_attempts": [],
    "response_dataset_names": [
      "..."
    ],
    "dataset_row_counts": {
      "...": 0
    },
    "source_summary": {}
  },
  "error_code": null,
  "implementation_status": null
}
순번오류 코드발생 조건
PROVIDER_UPSTREAM_ERROR읽기 미완료 — 행은 찾았지만 그 행의 내용을 끝까지 불러오지 못했습니다. 잠시 뒤 다시 시도합니다.
PROVIDER_VALIDATION_ERROR양식 불일치 — 고른 행이 이 조회의 서식이 아닙니다.