개발자 문서
API 레퍼런스

인증 - 국민건강보험공단 EDI

1. 국민건강보험공단 EDI 세션 로그인nhis_edi.session.login

MCP 도구 이름 nhis_edi__session__login

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

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

등록한 공동인증서로 건강보험 EDI에 로그인해 세션을 만들고, 로그인 성공 여부와 이번에 쓴 연동 계정 ID를 돌려줍니다.

  • 콘솔에서 발급한 API 키와 등록한 공동인증서가 필요합니다. 정식 환경은 현재 공개 요금제를 이용 중일 때만 호출할 수 있습니다.
  • 로그인은 콘솔에 등록한 공동인증서로만 합니다. params 는 빈 객체로 보내면 되고, auth_provider 같은 다른 값을 보내도 결과는 같습니다.

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

예시 : nhis_edi.session.login

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

Response

  • authenticated·live_cookie_material_ready·cookie_count를 확인합니다. 이후 조회 API는 동일 account_link_id를 사용합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
authenticatedboolean세션 인증 완료 여부
live_cookie_material_readybooleanlive cookie 재료 준비 여부
cookie_countnumber저장된 쿠키 수
auth_providerstring인증 방식 - 등록한 공동인증서(npki_anysign)
has_storage_stateboolean세션에 브라우저 저장 상태가 저장됐는지 여부
generation_statusstring세션 생성 상태
json
// result.data
{
  "success": true,
  "authenticated": true,
  "live_cookie_material_ready": true,
  "cookie_count": 5
}
순번오류 코드발생 조건
PROVIDER_AUTH_FAILED로그인 인증 실패 — 등록한 공동인증서의 개인키를 열지 못했습니다(인증서 비밀번호가 틀렸을 수 있습니다). 같은 인증서로는 다시 호출해도 결과가 같아 재시도 불가로 표시되니, error.message 안내대로 공동인증서와 비밀번호를 확인해 콘솔에서 인증서를 다시 등록한 뒤 호출합니다.
PROVIDER_UNAVAILABLE로그인 실패 — 그 밖의 이유로 기관 로그인을 마치지 못했습니다. 재시도 가능으로 표시되니 error.message 안내대로 잠시 후 다시 호출하고, 계속되면 서비스문의로 알립니다. 다만 error.provider_error_ref 가 nhis_edi.login_anysign_ 으로 시작하면 등록한 인증서가 서명 단계에서 거절된 경우라 같은 인증서로는 풀리지 않으니, 콘솔에서 인증서를 확인해 다시 등록한 뒤 호출합니다.
PROVIDER_UNAVAILABLE기관 연결 실패 — 기관에 연결하지 못해 로그인 요청을 보내지 못했습니다. error.provider_error_ref 는 nhis_edi.connection_error 입니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다.
PROVIDER_TIMEOUT_CONNECT연결 지연 — 기관 접속 자체가 시간 안에 되지 않았습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다.
PROVIDER_TIMEOUT_READ응답 지연 — 로그인 요청은 보냈지만 기관의 응답이 시간 안에 오지 않았습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR기관 일시 오류 — 기관이 서버 오류(500 번대) 상태로 답했습니다. error.provider_error_ref 끝의 숫자가 그 상태 코드입니다(예: nhis_edi.upstream_http_503). 재시도 가능으로 표시되니 잠시 후 다시 호출합니다.
PROVIDER_VALIDATION_ERROR기관 요청 거절 — 기관이 로그인 요청을 400 번대 오류 상태로 거절했습니다(403 과 429 는 「접근 제한」 행입니다). 재시도 불가로 표시되니 등록한 인증서를 확인하고, 계속되면 서비스문의로 알립니다.
PROVIDER_IP_REJECTED접근 제한 — 기관이 접근을 제한했습니다(403 이나 429 상태로 답했거나 접속을 끊음). 재시도 가능으로 표시되니 잠시 후 다시 호출하고, 계속되면 서비스문의로 알립니다.
PROVIDER_UNAVAILABLE세션 저장 실패 — 로그인은 됐지만 세션을 저장하지 못했습니다. 재시도 가능으로 표시되니 error.message 안내대로 잠시 후 다시 호출합니다.
POLICY_FEATURE_DISABLED개인사업자 — 로그인 뒤 사업자등록번호가 개인사업자 번호로 확인되면 방금 저장한 로그인 세션을 닫고 멈춥니다. error.message 는 「지금은 법인 사업자만 이용할 수 있습니다. 개인사업자는 서비스 안정화 뒤에 열 예정입니다.」 입니다. 재시도 불가로 표시되며, 다시 보내도 같은 답입니다.

2. 국민건강보험공단 EDI 세션 상태 조회nhis_edi.session.status

MCP 도구 이름 nhis_edi__session__status

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

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

연동 계정을 넣으면 저장된 건강보험 EDI 세션에 접속 정보가 모두 있는지와 로그인 확인 결과를 읽어 인증 여부와 업무 화면 준비 기록을 돌려줍니다.

  • 로그인을 먼저 호출하거나, 이미 세션이 등록된 account_link_id 를 사용합니다. [국민건강보험공단 EDI 로그인]
  • exists=false — 오류가 아닙니다. 로그인 작업을 먼저 호출하세요.
  • exists=true이나 live_cookie_material_ready=false — missing_live_cookie_keys·missing_reasons를 확인합니다.
  • params 는 빈 객체로 보냅니다. 조회할 세션은 요청 본문의 account_link_id 로 지정합니다.

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

예시 : nhis_edi.session.status

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

Response

  • exists·authenticated·live_cookie_material_ready·target_view_ready·post_login_probe_success를 확인합니다.
순번변수명타입설명
existsboolean세션 존재 여부 (false이면 login 필요)
authenticatedboolean인증 완료 여부
live_cookie_material_readybooleanlive cookie 재료 준비 여부
target_view_readyboolean업무 화면 진입 준비 여부
post_login_probe_successboolean로그인 후 probe 성공 여부
missing_live_cookie_keysarray누락된 live cookie 키 목록
has_cookie_jarboolean세션에 쿠키 묶음이 저장됐는지 여부
has_storage_stateboolean세션에 브라우저 저장 상태가 저장됐는지 여부
target_context_readyboolean업무 화면 기준 정보 준비 여부
target_context_keysarray업무 화면 기준 정보 키 이름 목록
missing_reasonsarray준비되지 않은 사유 목록
firm_context_bootstrap_successboolean사업장 정보 준비 요청이 성공했는지 여부
json
// result.data
{
  "exists": true,
  "authenticated": true,
  "live_cookie_material_ready": true,
  "target_view_ready": true,
  "post_login_probe_success": true
}