개발자 문서
API 레퍼런스

인증 - 국민연금공단 EDI

1. 국민연금공단 EDI NPKI 세션 로그인nps_edi.auth.npki_session.login

MCP 도구 이름 nps_edi__auth__npki_session__login

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

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

사업장관리번호 11자리와 등록한 공동인증서로 국민연금 EDI에 로그인해 세션을 만들고, 로그인 성공 여부와 그 사업장관리번호를 돌려줍니다.

  • 콘솔에서 발급한 API 키와 등록한 공동인증서가 필요합니다.

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호출할 기관입니다.
  • nps_edi이 API 고정값 (기본값)

예시 : nps_edi

actionstring-Y호출할 작업입니다.
  • nps_edi.auth.npki_session.login이 API 고정값 (기본값)

예시 : nps_edi.auth.npki_session.login

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
business_management_nostringY11자리 사업장관리번호. params 별칭: businessManagementNo, business_no
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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": "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 재료가 저장됩니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
authenticatedboolean세션 인증 완료 여부
live_cookie_material_readybooleanlive cookie 재료 준비 여부
cookie_countnumber저장된 쿠키 수
business_management_nostring사업장관리번호
auth_providerstring인증 방식 - 등록한 공동인증서(npki_ksbiz)
missing_live_cookie_keysarray누락된 live cookie 키 목록
has_storage_stateboolean세션에 브라우저 저장 상태가 저장됐는지 여부
business_management_no_displaystring사업장관리번호 - 000-00-00000-0 표기
generation_statusstring세션 생성 상태
json
// result.data
{
  "success": true,
  "authenticated": true,
  "live_cookie_material_ready": true,
  "cookie_count": 8,
  "business_management_no": "12345678901"
}
순번오류 코드발생 조건
PROVIDER_PREREQUISITE_REQUIRED사이트 비밀번호 미등록 — 기관 사이트에 사용자 비밀번호가 아직 등록되어 있지 않은 경우입니다. 같은 요청을 다시 보내도 풀리지 않아 자동 재시도 대상이 아니니, error.message 안내대로 기관 사이트에서 비밀번호를 먼저 등록한 뒤 콘솔 연동 화면에 입력하고 다시 호출합니다.
VALIDATION_INVALID_FIELD사이트 비밀번호 오류 — 사이트 비밀번호가 필요한 사업장인데 저장된 사이트 비밀번호가 없거나, 저장된 값을 기관이 받지 않은 경우입니다. 같은 요청을 다시 보내도 풀리지 않아 자동 재시도 대상이 아니니, error.message 안내대로 콘솔 연동 화면에서 사이트 비밀번호를 입력하거나 고친 뒤 다시 호출합니다.
VALIDATION_INVALID_FIELD사업장관리번호 오류 — 사업장관리번호가 없거나 형식이 틀렸습니다. 같은 값으로는 다시 호출해도 결과가 같아 자동 재시도 대상이 아니니, 숫자 열한 자리의 사업장관리번호를 보내 다시 호출합니다.
PROVIDER_UNAVAILABLE로그인 실패 — 기관 로그인을 마치지 못했습니다. 공동인증서 정보를 읽지 못했거나, 인증서를 열거나 서명하지 못했거나, 기관의 응답을 처리하지 못했거나, 지금은 로그인을 진행할 수 없는 경우입니다. 재시도 가능으로 표시되지만 error.message 가 인증서 비밀번호를 확인하라고 안내하면 같은 인증서로 다시 호출해도 풀리지 않으니 콘솔에서 인증서를 다시 등록한 뒤 호출하고, 잠시 후 다시 시도하라고 안내하면 잠시 뒤 다시 호출하며, 다시 로그인하라고 안내하면 로그인을 다시 호출하고, 서비스문의를 안내하면 문의합니다.
PROVIDER_IP_REJECTED통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
PROVIDER_TIMEOUT_CONNECT통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
PROVIDER_TIMEOUT_READ통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
PROVIDER_TIMEOUT_OVERALL통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
PROVIDER_UPSTREAM_ERROR통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
PROVIDER_VALIDATION_ERROR통신 오류 — 로그인하는 동안 기관과의 통신이 제한되거나 지연됐거나 기관이 오류로 답한 경우입니다. error.message 안내대로 잠시 후 다시 호출하거나 보낸 값과 연동 계정 권한을 확인합니다.
PROVIDER_UNAVAILABLE세션 저장 실패 — 로그인은 됐지만 세션을 저장하지 못했습니다. 재시도 가능으로 표시되니 error.message 안내대로 잠시 후 다시 호출합니다.
POLICY_FEATURE_DISABLED개인사업자 — 로그인 뒤 사업자등록번호가 개인사업자 번호로 확인되면 방금 저장한 로그인 세션을 닫고 멈춥니다. error.message 는 「지금은 법인 사업자만 이용할 수 있습니다. 개인사업자는 서비스 안정화 뒤에 열 예정입니다.」 입니다. 재시도 불가로 표시되며, 다시 보내도 같은 답입니다.

2. 국민연금공단 EDI 세션 상태 조회nps_edi.auth.session.status

MCP 도구 이름 nps_edi__auth__session__status

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

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

연동 계정 하나로 부르면 저장된 국민연금 EDI 세션이 있는지, 인증이 갖춰졌는지, 어느 사업장관리번호로 로그인했는지를 돌려줍니다.

  • 로그인을 먼저 호출하거나, 이미 세션이 등록된 account_link_id 를 사용합니다. [국민연금공단 EDI 로그인]
  • params 는 빈 객체로 보냅니다.

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호출할 기관입니다.
  • nps_edi이 API 고정값 (기본값)

예시 : nps_edi

actionstring-Y호출할 작업입니다.
  • nps_edi.auth.session.status이 API 고정값 (기본값)

예시 : nps_edi.auth.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": "nps_edi",
  "action": "nps_edi.auth.session.status",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • exists·authenticated·live_cookie_material_ready 필드를 확인합니다.
순번변수명타입설명
existsboolean세션 존재 여부 (false이면 login 필요)
authenticatedboolean인증 완료 여부
live_cookie_material_readybooleanlive cookie 재료 준비 여부
missing_live_cookie_keysarray누락된 live cookie 키 목록
has_cookie_jarboolean세션에 쿠키 묶음이 저장됐는지 여부
has_storage_stateboolean세션에 브라우저 저장 상태가 저장됐는지 여부
business_management_nostring사업장관리번호
business_management_no_displaystring사업장관리번호 - 000-00-00000-0 표기
flow_sourceobject로그인 출처 - 서명기는 종류(signer_mode) 한 값만 담습니다
json
// result.data
{
  "exists": true,
  "authenticated": true,
  "live_cookie_material_ready": true
}