인증 - 국민연금공단 EDI
1. 국민연금공단 EDI NPKI 세션 로그인nps_ edi. auth. npki_ session. login
MCP 도구 이름 nps_
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
사업장관리번호 11자리와 등록한 공동인증서로 국민연금 EDI에 로그인해 세션을 만들고, 로그인 성공 여부와 그 사업장관리번호를 돌려줍니다.
- 콘솔에서 발급한 API 키와 등록한 공동인증서가 필요합니다.
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 | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| business_ | string | Y | 11자리 사업장관리번호. params 별칭: businessManagementNo, business_no |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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": "nps_edi",
"action": "nps_edi.auth.npki_session.login",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"business_management_no": "<필수>"
}
}'Response
- account_link_id에 live cookie 재료가 저장됩니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| success | boolean | 요청 처리 성공 여부 | |
| authenticated | boolean | 세션 인증 완료 여부 | |
| live_ | boolean | live cookie 재료 준비 여부 | |
| cookie_ | number | 저장된 쿠키 수 | |
| business_ | string | 사업장관리번호 | |
| auth_ | string | 인증 방식 - 등록한 공동인증서(npki_ksbiz) | |
| missing_ | array | 누락된 live cookie 키 목록 | |
| has_ | boolean | 세션에 브라우저 저장 상태가 저장됐는지 여부 | |
| business_ | string | 사업장관리번호 - 000-00-00000-0 표기 | |
| generation_ | string | 세션 생성 상태 |
// result.data
{
"success": true,
"authenticated": true,
"live_cookie_material_ready": true,
"cookie_count": 8,
"business_management_no": "12345678901"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 사이트 비밀번호 미등록 — 기관 사이트에 사용자 비밀번호가 아직 등록되어 있지 않은 경우입니다. 같은 요청을 다시 보내도 풀리지 않아 자동 재시도 대상이 아니니, error.message 안내대로 기관 사이트에서 비밀번호를 먼저 등록한 뒤 콘솔 연동 화면에 입력하고 다시 호출합니다. | |
| VALIDATION_ | 사이트 비밀번호 오류 — 사이트 비밀번호가 필요한 사업장인데 저장된 사이트 비밀번호가 없거나, 저장된 값을 기관이 받지 않은 경우입니다. 같은 요청을 다시 보내도 풀리지 않아 자동 재시도 대상이 아니니, error.message 안내대로 콘솔 연동 화면에서 사이트 비밀번호를 입력하거나 고친 뒤 다시 호출합니다. | |
| VALIDATION_ | 사업장관리번호 오류 — 사업장관리번호가 없거나 형식이 틀렸습니다. 같은 값으로는 다시 호출해도 결과가 같아 자동 재시도 대상이 아니니, 숫자 열한 자리의 사업장관리번호를 보내 다시 호출합니다. | |
| PROVIDER_ | 로그인 실패 — 기관 로그인을 마치지 못했습니다. 공동인증서 정보를 읽지 못했거나, 인증서를 열거나 서명하지 못했거나, 기관의 응답을 처리하지 못했거나, 지금은 로그인을 진행할 수 없는 경우입니다. 재시도 가능으로 표시되지만 error.message 가 인증서 비밀번호를 확인하라고 안내하면 같은 인증서로 다시 호출해도 풀리지 않으니 콘솔에서 인증서를 다시 등록한 뒤 호출하고, 잠시 후 다시 시도하라고 안내하면 잠시 뒤 다시 호출하며, 다시 로그인하라고 안내하면 로그인을 다시 호출하고, 서비스문의를 안내하면 문의합니다. | |
| PROVIDER_ | 통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| PROVIDER_ | 통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| PROVIDER_ | 통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| PROVIDER_ | 통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| PROVIDER_ | 통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| PROVIDER_ | 통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다. | |
| PROVIDER_ | 세션 저장 실패 — 로그인은 됐지만 세션을 저장하지 못했습니다. 재시도 가능으로 표시되니 error.message 안내대로 잠시 후 다시 호출합니다. | |
| POLICY_ | 개인사업자 — 로그인 뒤 사업자등록번호가 개인사업자 번호로 확인되면 방금 저장한 로그인 세션을 닫고 멈춥니다. error.message 는 「지금은 법인 사업자만 이용할 수 있습니다. 개인사업자는 서비스 안정화 뒤에 열 예정입니다.」 입니다. 재시도 불가로 표시되며, 다시 보내도 같은 답입니다. |
2. 국민연금공단 EDI 세션 상태 조회nps_ edi. auth. session. status
MCP 도구 이름 nps_
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
연동 계정 하나로 부르면 저장된 국민연금 EDI 세션이 있는지, 인증이 갖춰졌는지, 어느 사업장관리번호로 로그인했는지를 돌려줍니다.
- 로그인을 먼저 호출하거나, 이미 세션이 등록된 account_link_id 를 사용합니다. [국민연금공단 EDI 로그인]
- params 는 빈 객체로 보냅니다.
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": "nps_edi",
"action": "nps_edi.auth.session.status",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- exists·authenticated·live_cookie_material_ready 필드를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| exists | boolean | 세션 존재 여부 (false이면 login 필요) | |
| authenticated | boolean | 인증 완료 여부 | |
| live_ | boolean | live cookie 재료 준비 여부 | |
| missing_ | array | 누락된 live cookie 키 목록 | |
| has_ | boolean | 세션에 쿠키 묶음이 저장됐는지 여부 | |
| has_ | boolean | 세션에 브라우저 저장 상태가 저장됐는지 여부 | |
| business_ | string | 사업장관리번호 | |
| business_ | string | 사업장관리번호 - 000-00-00000-0 표기 | |
| flow_ | object | 로그인 출처 - 서명기는 종류(signer_mode) 한 값만 담습니다 |
// result.data
{
"exists": true,
"authenticated": true,
"live_cookie_material_ready": true
}