개발자 문서
API 레퍼런스

사업장 - 국민건강보험공단 EDI

1. 사업장 기본정보 조회nhis_edi.business.basic_info

MCP 도구 이름 nhis_edi__business__basic_info

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

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

연동 계정으로 부르면 로그인한 건강보험 EDI 세션이 가진 사업장 기본정보를 받습니다.

  • 로그인을 먼저 호출합니다. 이 API 는 세션만 있으면 되고 업무 화면 진입은 필요하지 않습니다. [국민건강보험공단 EDI 로그인]
  • result.data.error_code=BUSINESS_BASIC_INFO_EMPTY.
  • params 는 빈 객체로 보내도 호출됩니다.

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.business.basic_info이 API 고정값 (기본값)

예시 : nhis_edi.business.basic_info

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

형식 : 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: real_test' \
  --header "Idempotency-Key: basic_info-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nhis_edi",
  "action": "nhis_edi.business.basic_info",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • business·insurance_symbols 필드를 확인합니다.
순번변수명타입설명
successboolean사업장 기본정보를 읽었는지 여부(읽지 못하면 false 이고 error_code 에 사유가 옵니다)
feature_namestring기능 식별자
phasestring단계(이 액션은 detail)
workflow_stepstring워크플로 단계
screen_idstring화면 식별자
route_kindstring라우트 종류
businessobject사업장 기본정보 객체
insurance_symbolsobject보험별 사업장 기호 객체(health, pension, employment, industrial_accident)
source_evidenceobject출처 증적 객체
error_codestring | null오류 코드(문제가 없으면 null)
implementation_statusstring | null구현 상태(문제가 없으면 null)
json
// result.data
{
  "phase": "detail",
  "success": true,
  "business": {
    "unb_no": "12345678901",
    "firm_sym": "12345678",
    "efirm_sym": "[REDACTED]",
    "firm_name": "예시 주식회사",
    "goji_chasu": "1",
    "finance_code": "00",
    "unit_firm_sym": "000",
    "firm_management_no": "12345678901",
    "representative_name": "홍길동",
    "representative_jumin_no": "0000000000000",
    "business_registration_no": "1234567890"
  },
  "screen_id": "...",
  "error_code": null,
  "route_kind": "live_session_context",
  "feature_name": "...",
  "workflow_step": "business_basic_info_loaded",
  "source_evidence": {
    "screenshot": "...",
    "context_datasets": [
      "...",
      "...",
      "...",
      "..."
    ]
  },
  "insurance_symbols": {
    "health": "12345678901",
    "pension": "12345678901",
    "employment": "12345678901",
    "industrial_accident": "12345678901"
  },
  "implementation_status": null
}