인증 - 국민건강보험공단 EDI
1. 국민건강보험공단 EDI 세션 로그인nhis_ edi. session. login
MCP 도구 이름 nhis_
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
등록한 공동인증서로 건강보험 EDI에 로그인해 세션을 만들고, 로그인 성공 여부와 이번에 쓴 연동 계정 ID를 돌려줍니다.
- 콘솔에서 발급한 API 키와 등록한 공동인증서가 필요합니다. 정식 환경은 현재 공개 요금제를 이용 중일 때만 호출할 수 있습니다.
- 로그인은 콘솔에 등록한 공동인증서로만 합니다. params 는 빈 객체로 보내면 되고, auth_provider 같은 다른 값을 보내도 결과는 같습니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
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를 사용합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| authenticated | boolean | 세션 인증 완료 여부 | |
| live_ | boolean | live cookie 재료 준비 여부 | |
| cookie_ | number | 저장된 쿠키 수 | |
| auth_ | string | 인증 방식 - 등록한 공동인증서(npki_anysign) | |
| has_ | boolean | 세션에 브라우저 저장 상태가 저장됐는지 여부 | |
| generation_ | string | 세션 생성 상태 |
// result.data
{
"success": true,
"authenticated": true,
"live_cookie_material_ready": true,
"cookie_count": 5
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 로그인 인증 실패 — 등록한 공동인증서의 개인키를 열지 못했습니다(인증서 비밀번호가 틀렸을 수 있습니다). 같은 인증서로는 다시 호출해도 결과가 같아 재시도 불가로 표시되니, error.message 안내대로 공동인증서와 비밀번호를 확인해 콘솔에서 인증서를 다시 등록한 뒤 호출합니다. | |
| PROVIDER_ | 로그인 실패 — 그 밖의 이유로 기관 로그인을 마치지 못했습니다. 재시도 가능으로 표시되니 error.message 안내대로 잠시 후 다시 호출하고, 계속되면 서비스문의로 알립니다. 다만 error.provider_error_ref 가 nhis_edi.login_anysign_ 으로 시작하면 등록한 인증서가 서명 단계에서 거절된 경우라 같은 인증서로는 풀리지 않으니, 콘솔에서 인증서를 확인해 다시 등록한 뒤 호출합니다. | |
| PROVIDER_ | 기관 연결 실패 — 기관에 연결하지 못해 로그인 요청을 보내지 못했습니다. error.provider_error_ref 는 nhis_edi.connection_error 입니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 연결 지연 — 기관 접속 자체가 시간 안에 되지 않았습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 응답 지연 — 로그인 요청은 보냈지만 기관의 응답이 시간 안에 오지 않았습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 기관 일시 오류 — 기관이 서버 오류(500 번대) 상태로 답했습니다. error.provider_error_ref 끝의 숫자가 그 상태 코드입니다(예: nhis_edi.upstream_http_503). 재시도 가능으로 표시되니 잠시 후 다시 호출합니다. | |
| PROVIDER_ | 기관 요청 거절 — 기관이 로그인 요청을 400 번대 오류 상태로 거절했습니다(403 과 429 는 「접근 제한」 행입니다). 재시도 불가로 표시되니 등록한 인증서를 확인하고, 계속되면 서비스문의로 알립니다. | |
| PROVIDER_ | 접근 제한 — 기관이 접근을 제한했습니다(403 이나 429 상태로 답했거나 접속을 끊음). 재시도 가능으로 표시되니 잠시 후 다시 호출하고, 계속되면 서비스문의로 알립니다. | |
| PROVIDER_ | 세션 저장 실패 — 로그인은 됐지만 세션을 저장하지 못했습니다. 재시도 가능으로 표시되니 error.message 안내대로 잠시 후 다시 호출합니다. | |
| POLICY_ | 개인사업자 — 로그인 뒤 사업자등록번호가 개인사업자 번호로 확인되면 방금 저장한 로그인 세션을 닫고 멈춥니다. error.message 는 「지금은 법인 사업자만 이용할 수 있습니다. 개인사업자는 서비스 안정화 뒤에 열 예정입니다.」 입니다. 재시도 불가로 표시되며, 다시 보내도 같은 답입니다. |
2. 국민건강보험공단 EDI 세션 상태 조회nhis_ edi. session. status
MCP 도구 이름 nhis_
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
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
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를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| exists | boolean | 세션 존재 여부 (false이면 login 필요) | |
| authenticated | boolean | 인증 완료 여부 | |
| live_ | boolean | live cookie 재료 준비 여부 | |
| target_ | boolean | 업무 화면 진입 준비 여부 | |
| post_ | boolean | 로그인 후 probe 성공 여부 | |
| missing_ | array | 누락된 live cookie 키 목록 | |
| has_ | boolean | 세션에 쿠키 묶음이 저장됐는지 여부 | |
| has_ | boolean | 세션에 브라우저 저장 상태가 저장됐는지 여부 | |
| target_ | boolean | 업무 화면 기준 정보 준비 여부 | |
| target_ | array | 업무 화면 기준 정보 키 이름 목록 | |
| missing_ | array | 준비되지 않은 사유 목록 | |
| firm_ | boolean | 사업장 정보 준비 요청이 성공했는지 여부 |
// result.data
{
"exists": true,
"authenticated": true,
"live_cookie_material_ready": true,
"target_view_ready": true,
"post_login_probe_success": true
}