인증
1. 국민연금공단 EDI NPKI 세션 로그인nps_
MCP 도구 이름 nps_edi__auth__npki_session__login
POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox
샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.
사업장관리번호와 NPKI(KSBiz) 인증서로 국민연금 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 | N | 등록한 자격증명을 가리키는 아이디입니다. 이 API 는 자격증명 없이도 호출할 수 있습니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| business_ | string | Y | 11자리 사업장관리번호. Job params 별칭: businessManagementNo, business_no | |
| auth_ | string | N | 인증 방식. 기본 npki_ksbiz. Job params 별칭: provider |
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": "nps_edi",
"action": "nps_edi.auth.npki_session.login",
"params": {
"business_management_no": "<필수>"
}
}'Response
- account_link_id에 live cookie 재료가 저장됩니다.
| 순번 | 변수명 | 설명 |
|---|---|---|
| success | 요청 처리 성공 여부 | |
| authenticated | 세션 인증 완료 여부 | |
| live_ | live cookie 재료 준비 여부 | |
| cookie_ | 저장된 쿠키 수 | |
| business_ | 사업장관리번호 | |
| auth_ | 인증 방식 - 등록한 공동인증서(npki_anysign) | |
| missing_ | 누락된 live cookie 키 목록 | |
| has_ | 세션에 쿠키 묶음이 저장됐는지 여부 | |
| has_ | 세션에 브라우저 저장 상태가 저장됐는지 여부 | |
| business_ | 사업장관리번호 - 000-00-00000-0 표기 | |
| generation_ | 세션 생성 상태 | |
| flow_ | 로그인 출처 - 서명기는 종류(signer_mode) 한 값만 담습니다 |
json
// result.data
{
"success": true,
"authenticated": true,
"live_cookie_material_ready": true,
"cookie_count": 8,
"business_management_no": "1234567890"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 로그인 실패 — 기관 로그인에 실패했습니다. 등록한 공동인증서를 확인합니다. | |
| VALIDATION_ | 사업장관리번호 오류 — 사업장관리번호가 없거나 형식이 틀렸습니다. | |
| PROVIDER_ | 세션 저장 실패 — 로그인 뒤 세션을 저장하지 못했습니다. |
2. 국민연금공단 EDI 세션 상태 조회nps_
MCP 도구 이름 nps_edi__auth__session__status
POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox
샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.
등록된 NPS EDI 세션의 인증 준비 상태와 live cookie 재료 유무를 확인합니다.
- 로그인을 먼저 호출하거나, 이미 세션이 등록된 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 | N | 등록한 자격증명을 가리키는 아이디입니다. 이 API 는 자격증명 없이도 호출할 수 있습니다. | |
| params | object | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | 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": "nps_edi",
"action": "nps_edi.auth.session.status",
"params": {}
}'Response
- exists·authenticated·live_cookie_material_ready 필드를 확인합니다.
| 순번 | 변수명 | 설명 |
|---|---|---|
| exists | 세션 존재 여부 (false이면 login 필요) | |
| authenticated | 인증 완료 여부 | |
| live_ | live cookie 재료 준비 여부 | |
| missing_ | 누락된 live cookie 키 목록 | |
| live_ | live cookie 키별 보유 여부 | |
| has_ | 세션에 쿠키 묶음이 저장됐는지 여부 | |
| has_ | 세션에 브라우저 저장 상태가 저장됐는지 여부 | |
| business_ | 사업장관리번호 | |
| business_ | 사업장관리번호 - 000-00-00000-0 표기 | |
| login_ | 로그인 확인 요청 결과 | |
| flow_ | 로그인 출처 - 서명기는 종류(signer_mode) 한 값만 담습니다 | |
| cookie_ | 저장된 쿠키 키 이름 목록 | |
| workflow_ | 업무 화면 진행 상태 |
json
// result.data
{
"exists": true,
"authenticated": true,
"live_cookie_material_ready": true
}