인증

MCP 도구 이름 nhis_edi__session__login

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

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

NPKI(AnySign) 또는 수동 쿠키(manual_session)로 건강보험 EDI 급여 포털 세션을 등록합니다.

콘솔에서 발급한 API 키와 등록한 공동인증서가 필요합니다. 정식 환경은 유료 플랜을 이용 중일 때만 호출할 수 있습니다.
sandbox 환경에서는 실제 기관에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다. 실제 공동인증서 로그인은 데모(real_test)·정식(production) 환경에서 합니다.
인증 방식은 auth_provider 로 지정하며 기본값은 공동인증서입니다. 수동 세션을 쓰면 쿠키가 필요하고, 공동인증서 방식은 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.session.login`이 API 고정값 (기본값) 예시 : nhis_edi.session.login
account_link_id	string	36	N	등록한 자격증명을 가리키는 아이디입니다. 이 API 는 자격증명 없이도 호출할 수 있습니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

순번	변수명	타입	필수	설명
	auth_provider	string	N	인증 방식. 기본 npki_anysign. Job params 별칭: provider. npki도 동일

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-login-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nhis_edi",
  "action": "nhis_edi.session.login",
  "params": {}
}'

Response

authenticated·live_cookie_material_ready·cookie_count를 확인합니다. 이후 조회 API는 동일 account_link_id를 사용합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	authenticated	세션 인증 완료 여부
	live_cookie_material_ready	live cookie 재료 준비 여부
	cookie_count	저장된 쿠키 수
	auth_provider	인증 방식 - 공동인증서(npki_anysign) 또는 수동 세션(manual_session)
	has_cookie_jar	세션에 쿠키 묶음이 저장됐는지 여부
	has_storage_state	세션에 브라우저 저장 상태가 저장됐는지 여부
	generation_status	세션 생성 상태
	post_login_probe_success	로그인 후 probe 성공 여부
	flow_source	로그인 경로 정보 - 로그인 방식과 진입 지점
	html_js_contract	로그인 화면 계약 확인 결과 - 필수 표식과 전송 필드

json

// result.data
{
  "success": true,
  "authenticated": true,
  "live_cookie_material_ready": true,
  "cookie_count": 5
}

순번	오류 코드	발생 조건
	PROVIDER_UNAVAILABLE	로그인 실패 — 기관 로그인에 실패했습니다. auth_provider 값과 등록한 공동인증서(수동 세션이면 쿠키)를 확인합니다.
	PROVIDER_AUTH_FAILED	세션 저장 실패 — 로그인 뒤 세션을 저장하지 못했습니다.

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

MCP 도구 이름 nhis_edi__session__status

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

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

등록된 NHIS EDI 세션의 인증·live cookie·업무 화면(target_view) 진입 준비 상태를 확인합니다.

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

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.session.status`이 API 고정값 (기본값) 예시 : nhis_edi.session.status
account_link_id	string	36	N	등록한 자격증명을 가리키는 아이디입니다. 이 API 는 자격증명 없이도 호출할 수 있습니다. 형식 : 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-status-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nhis_edi",
  "action": "nhis_edi.session.status",
  "params": {}
}'

Response

exists·authenticated·live_cookie_material_ready·target_view_ready·post_login_probe_success를 확인합니다.

순번	변수명	설명
	exists	세션 존재 여부 (false이면 login 필요)
	authenticated	인증 완료 여부
	live_cookie_material_ready	live cookie 재료 준비 여부
	target_view_ready	업무 화면 진입 준비 여부
	post_login_probe_success	로그인 후 probe 성공 여부
	missing_live_cookie_keys	누락된 live cookie 키 목록
	live_cookie_keys_present	live cookie 키별 보유 여부
	has_cookie_jar	세션에 쿠키 묶음이 저장됐는지 여부
	has_storage_state	세션에 브라우저 저장 상태가 저장됐는지 여부
	login_probe	로그인 확인 요청 결과
	flow_source	로그인 경로 정보 - 로그인 방식과 진입 지점
	html_js_contract	로그인 화면 계약 확인 결과 - 필수 표식과 전송 필드
	cookie_key_names	저장된 쿠키 키 이름 목록
	workflow_state	업무 화면 진행 상태
	target_view_contract	업무 화면 진입 계약 확인 결과
	target_context_ready	업무 화면 기준 정보 준비 여부
	target_context_keys	업무 화면 기준 정보 키 이름 목록
	entry_probe	업무 화면 진입 확인 결과
	missing_reasons	준비되지 않은 사유 목록

json

// result.data
{
  "exists": true,
  "authenticated": true,
  "live_cookie_material_ready": true,
  "target_view_ready": true,
  "post_login_probe_success": true
}

인증

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

Request

Response

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

Request

Response