개발자 문서
API 레퍼런스

연금보험료 - 국민연금공단 EDI

1. 국민연금 결정내역 안내 문구nps_edi.b1.national_pension_premiums.guide

MCP 도구 이름 nps_edi__b1__national_pension_premiums__guide

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

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

고지나 기간을 고르지 않고 부르면 국민연금보험료 2차 결정내역 화면에 붙은 기관 안내 문구를 화면 이름과 본문으로 돌려줍니다. 고지 선택과 무관합니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [국민연금공단 EDI 로그인]
  • 기관이 데이터셋을 주었는데 안내 행이 비면 success=true, error_code=null, implementation_status=pension_guide_dataset_empty.
  • 기관이 데이터셋을 하나도 주지 않으면 success=false, error_code=null, implementation_status=pension_guide_dataset_empty.
  • 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.b1.national_pension_premiums.guide이 API 고정값 (기본값)

예시 : nps_edi.b1.national_pension_premiums.guide

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: guide-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nps_edi",
  "action": "nps_edi.b1.national_pension_premiums.guide",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • rows를 확인합니다.
순번변수명타입설명
rowsarray안내·도움말 텍스트 행 배열
json
// result.data
{
  "rows": [
    {
      "gdbk1": "○ [가입자내역]-[보험료지원금 공제 후] 의 금액은 당월분 지원금 기준으로 작성되었으며 납기내 완납시 다음달(익월) 보험료 지원예정금액이 적용된 금액이니 참고바랍니다.\n\n○ 대표자인 경우 '보험료(원)'만 표기됩니다. (근로자기여금/사업자부담금 미표출)",
      "useYn": "Y",
      "menuId": "M08010200",
      "prgrmId": "...",
      "wediMenuNm": "국민연금보험료 2차 결정내역",
      "frstRegWediUserId": "user01",
      "lastRegWediUserId": "user01"
    }
  ],
  "phase": "guide",
  "success": true,
  "error_code": null,
  "route_kind": "live",
  "feature_name": "...",
  "workflow_step": "national_pension_notice_guide",
  "source_evidence": {
    "url": "https://...",
    "status_code": 200,
    "wire_format": "...",
    "content_type": "...",
    "expected_datasets": [
      "...",
      "..."
    ],
    "dataset_row_counts": {
      "...": 1,
      "...2": 1
    },
    "response_parameters": {
      "ErrorCode": "..."
    },
    "transaction_contract": {
      "tags": [
        "..."
      ],
      "endpoint": "...",
      "page_per_count": 10,
      "source_scripts": [],
      "contract_source": "...",
      "page_dataset_name": null,
      "private_program_id": null,
      "input_dataset_names": [
        "..."
      ],
      "source_execution_id": "...",
      "private_wedi_dmnd_cd": "",
      "business_dataset_names": [
        "..."
      ],
      "response_dataset_names": [
        "...",
        "..."
      ]
    },
    "response_dataset_names": [
      "...",
      "..."
    ]
  },
  "implementation_status": null
}

2. 국민연금 납부와 징수 이력nps_edi.b1.national_pension_premiums.payment_history

MCP 도구 이름 nps_edi__b1__national_pension_premiums__payment_history

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

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

고지 연월과 차수 같은 값으로 고른 고지의 납부와 징수 이력이 있으면 기관이 준 줄을 돌려줍니다.

  • 요약 조회와 선행 조건이 같습니다. 대상을 먼저 선택하거나 선택 조건을 함께 보냅니다. [국민연금공단 EDI 로그인]
  • 기관이 데이터셋을 주었는데 납부 이력 행이 비면 success=true, error_code=null, implementation_status=pension_payment_history_empty.
  • 기관이 데이터셋을 하나도 주지 않으면 success=false, error_code=null, implementation_status=pension_payment_history_empty.

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.b1.national_pension_premiums.payment_history이 API 고정값 (기본값)

예시 : nps_edi.b1.national_pension_premiums.payment_history

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

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-조건부작업 파라미터입니다. 아래 params 파라미터 표의 row_index, row_key, notice_year_month, installment_round, template_code, row_text_contains 또는 cell_text_contains 중 하나 이상을 보냅니다. 앞 단계에서 고른 항목이 같은 연동 계정의 세션에 남아 있으면 빈 객체로 보내 그 항목을 씁니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
row_indexnumber-조건부search/select 결과 options[].row_index. 지정 시 세션 cached selected_notice 재선택
row_keystring-조건부search/select 결과 options[].row_key
notice_year_monthstring6조건부고지 연월. cached selected_notice와 불일치 시 재선택

형식 : YYYYMM

installment_roundstring-조건부고지 차수. 1=1차(ED02), 2=2차(ED08). 정수 · 문자열 모두 허용
template_codestring-조건부고지 양식 코드 (예: ED02)
row_text_containsstring-조건부행 텍스트 부분 일치 필터
cell_text_containsstring-조건부칸 하나 안의 텍스트 부분 일치 필터
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: payment_history-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nps_edi",
  "action": "nps_edi.b1.national_pension_premiums.payment_history",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "row_index": "<필수: number>"
  }
}'

Response

  • rows·page를 확인합니다.
순번변수명타입설명
rowsarray납부·징수 이력 행 배열. 서버가 페이지를 끝까지 읽어 모든 페이지의 행을 싣습니다
pageobject첫 페이지의 페이지 정보 객체
workplaceobject사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수)
noticeobject선택한 고지 정보 (귀속 연월, 회차, 서식, 문서번호, 접수일)
row_coverageobject전체 행 수신 범위 (total_row_count, received_row_count, pages_read, complete, stop_reason). complete 가 false 면 행이 더 있을 수 있습니다
json
// result.data
{
  "rows": [],
  "page": {},
  "workplace": {},
  "notice": {},
  "row_coverage": {}
}
순번오류 코드발생 조건
PROVIDER_VALIDATION_ERROR선택 오류 — 고지 내역을 먼저 선택(select)해야 하거나, 조건에 맞는 행을 찾지 못했습니다.

3. 국민연금 소급분 내역nps_edi.b1.national_pension_premiums.retro_payments

MCP 도구 이름 nps_edi__b1__national_pension_premiums__retro_payments

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

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

고지 연월과 차수 같은 값으로 고른 고지에 소급분 내역이 있으면 기관이 준 줄을 돌려줍니다.

  • 요약 조회와 선행 조건이 같습니다. 대상을 먼저 선택하거나 선택 조건을 함께 보냅니다. [국민연금공단 EDI 로그인]
  • 기관이 데이터셋을 주었는데 소급분 행이 비면 success=true, error_code=null, implementation_status=pension_retro_payments_empty.
  • 기관이 데이터셋을 하나도 주지 않으면 success=false, error_code=null, implementation_status=pension_retro_payments_empty.

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.b1.national_pension_premiums.retro_payments이 API 고정값 (기본값)

예시 : nps_edi.b1.national_pension_premiums.retro_payments

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

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-조건부작업 파라미터입니다. 아래 params 파라미터 표의 row_index, row_key, notice_year_month, installment_round, template_code, row_text_contains 또는 cell_text_contains 중 하나 이상을 보냅니다. 앞 단계에서 고른 항목이 같은 연동 계정의 세션에 남아 있으면 빈 객체로 보내 그 항목을 씁니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
row_indexnumber-조건부search/select 결과 options[].row_index. 지정 시 세션 cached selected_notice 재선택
row_keystring-조건부search/select 결과 options[].row_key
notice_year_monthstring6조건부고지 연월. cached selected_notice와 불일치 시 재선택

형식 : YYYYMM

installment_roundstring-조건부고지 차수. 1=1차(ED02), 2=2차(ED08). 정수 · 문자열 모두 허용
template_codestring-조건부고지 양식 코드 (예: ED02)
row_text_containsstring-조건부행 텍스트 부분 일치 필터
cell_text_containsstring-조건부칸 하나 안의 텍스트 부분 일치 필터
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: retro_payments-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nps_edi",
  "action": "nps_edi.b1.national_pension_premiums.retro_payments",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "row_index": "<필수: number>"
  }
}'

Response

  • rows를 확인합니다.
순번변수명타입설명
rowsarray소급분 행 배열. 서버가 페이지를 끝까지 읽어 모든 페이지의 행을 싣습니다
pageobject첫 페이지의 페이지 정보 객체
workplaceobject사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수)
noticeobject선택한 고지 정보 (귀속 연월, 회차, 서식, 문서번호, 접수일)
row_coverageobject전체 행 수신 범위 (total_row_count, received_row_count, pages_read, complete, stop_reason). complete 가 false 면 행이 더 있을 수 있습니다
json
// result.data
{
  "rows": [],
  "page": {},
  "workplace": {},
  "notice": {},
  "row_coverage": {}
}
순번오류 코드발생 조건
PROVIDER_VALIDATION_ERROR선택 오류 — 고지 내역을 먼저 선택(select)해야 하거나, 조건에 맞는 행을 찾지 못했습니다.

4. 국민연금 가입자별 보험료 내역nps_edi.b1.national_pension_premiums.subscribers

MCP 도구 이름 nps_edi__b1__national_pension_premiums__subscribers

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

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

고지 연월과 차수로 고른 고지의 가입자별 기준소득월액과 연금보험료, 부담금을 줄마다 돌려주고 받은 줄의 가입자 수와 합계도 줍니다.

  • 요약 조회와 선행 조건이 같습니다. 대상을 먼저 선택하거나 선택 조건을 함께 보냅니다. [국민연금공단 EDI 로그인]
  • 기관이 데이터셋을 주었는데 가입자 행이 비면 success=true, error_code=null, implementation_status=pension_subscriber_dataset_empty.
  • 기관이 데이터셋을 하나도 주지 않으면 success=false, error_code=null, implementation_status=pension_subscriber_dataset_empty.

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.b1.national_pension_premiums.subscribers이 API 고정값 (기본값)

예시 : nps_edi.b1.national_pension_premiums.subscribers

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

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-조건부작업 파라미터입니다. 아래 params 파라미터 표의 row_index, row_key, notice_year_month, installment_round, template_code, row_text_contains 또는 cell_text_contains 중 하나 이상을 보냅니다. 앞 단계에서 고른 항목이 같은 연동 계정의 세션에 남아 있으면 빈 객체로 보내 그 항목을 씁니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
row_indexnumber-조건부search/select 결과 options[].row_index. 지정 시 세션 cached selected_notice 재선택
row_keystring-조건부search/select 결과 options[].row_key
notice_year_monthstring6조건부고지 연월. cached selected_notice와 불일치 시 재선택

형식 : YYYYMM

installment_roundstring-조건부고지 차수. 1=1차(ED02), 2=2차(ED08). 정수 · 문자열 모두 허용
template_codestring-조건부고지 양식 코드 (예: ED02)
row_text_containsstring-조건부행 텍스트 부분 일치 필터
cell_text_containsstring-조건부칸 하나 안의 텍스트 부분 일치 필터
output_formatsarray-N이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: subscribers-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nps_edi",
  "action": "nps_edi.b1.national_pension_premiums.subscribers",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "row_index": "<필수: number>"
  }
}'

Response

  • members를 확인합니다.
  • 아래 표의 members[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 엑셀 파일 맨 윗줄의 머리글입니다.
  • 아래 표의 줄은 엑셀로 내보내는 열이라 응답 행의 칸 전부가 아닐 수 있습니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
membersarray가입자별 보험료 내역 배열
members[].sequencestring | number | boolean | object | array | null순번
members[].namestring | number | boolean | object | array | null가입자명
members[].standard_monthly_incomestring | number | boolean | object | array | null기준소득월액
members[].pension_premiumstring | number | boolean | object | array | null연금보험료
members[].employee_contributionstring | number | boolean | object | array | null가입자 부담금
members[].employer_contributionstring | number | boolean | object | array | null사용자 부담금
members[].support_after_employee_contributionstring | number | boolean | object | array | null지원 후 가입자 부담금
members[].support_after_employer_contributionstring | number | boolean | object | array | null지원 후 사용자 부담금
workplaceobject사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수)
noticeobject선택한 고지 정보 (귀속 연월, 회차, 서식, 문서번호, 접수일)
summaryobject가입자 합계 (인원수, 기준소득월액, 연금보험료, 근로자와 사업주 부담금). 모든 페이지의 가입자로 계산합니다
row_coverageobject전체 행 수신 범위 (total_row_count, received_row_count, pages_read, complete, stop_reason). 서버가 페이지를 끝까지 읽어 members 에 모두 싣고, complete 가 false 면 가입자가 더 있을 수 있습니다
json
// result.data
{
  "members": [
    {
      "sequence": "1",
      "name": "...",
      "identifiers": {},
      "standard_monthly_income": 0,
      "pension_premium": 0,
      "employee_contribution": 0,
      "employer_contribution": 0,
      "support_after_employee_contribution": 0,
      "support_after_employer_contribution": 0,
      "raw": {}
    }
  ],
  "workplace": {},
  "notice": {},
  "summary": {},
  "row_coverage": {
    "total_row_count": 1,
    "received_row_count": 1,
    "pages_read": 1,
    "complete": true,
    "stop_reason": "total_reached"
  }
}
순번오류 코드발생 조건
PROVIDER_VALIDATION_ERROR선택 오류 — 고지 내역을 먼저 선택(select)해야 하거나, 조건에 맞는 행을 찾지 못했습니다.

5. 국민연금 보험료 결정 요약nps_edi.b1.national_pension_premiums.summary

MCP 도구 이름 nps_edi__b1__national_pension_premiums__summary

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

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

고지 연월과 차수로 고른 고지의 보험료 결정 요약을 한 건으로 돌려줍니다.

  • 고지 선택을 먼저 호출하거나, 선택 조건으로 고지를 지정합니다. [국민연금공단 EDI 로그인]
  • 기관이 데이터셋을 주었는데 요약 행이 비면 success=true, error_code=null, implementation_status=pension_summary_dataset_empty.
  • 기관이 데이터셋을 하나도 주지 않으면 success=false, error_code=null, implementation_status=pension_summary_dataset_empty.
  • 선택을 먼저 하면 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.b1.national_pension_premiums.summary이 API 고정값 (기본값)

예시 : nps_edi.b1.national_pension_premiums.summary

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

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-조건부작업 파라미터입니다. 아래 params 파라미터 표의 row_index, row_key, notice_year_month, installment_round, template_code, row_text_contains 또는 cell_text_contains 중 하나 이상을 보냅니다. 앞 단계에서 고른 항목이 같은 연동 계정의 세션에 남아 있으면 빈 객체로 보내 그 항목을 씁니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
row_indexnumber-조건부search/select 결과 options[].row_index. 지정 시 세션 cached selected_notice 재선택
row_keystring-조건부search/select 결과 options[].row_key
notice_year_monthstring6조건부고지 연월. cached selected_notice와 불일치 시 재선택

형식 : YYYYMM

installment_roundstring-조건부고지 차수. 1=1차(ED02), 2=2차(ED08). 정수 · 문자열 모두 허용
template_codestring-조건부고지 양식 코드 (예: ED02)
row_text_containsstring-조건부행 텍스트 부분 일치 필터
cell_text_containsstring-조건부칸 하나 안의 텍스트 부분 일치 필터
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: summary-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nps_edi",
  "action": "nps_edi.b1.national_pension_premiums.summary",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "row_index": "<필수: number>"
  }
}'

Response

  • summary·notice를 확인합니다.
순번변수명타입설명
summaryobject고지 결정 요약 객체
noticeobject고지 기본정보 객체
workplaceobject사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수)
selected_optionobject선택한 고지 행 정보 (문서번호, 서식, 귀속 연월, 회차, 접수일)
json
// result.data
{
  "summary": {},
  "notice": {},
  "workplace": {},
  "selected_option": {}
}
순번오류 코드발생 조건
PROVIDER_VALIDATION_ERROR선택 오류 — 고지 내역을 먼저 선택(select)해야 하거나, 조건에 맞는 행을 찾지 못했습니다.

6. 국민연금 지원금과 보조 내역nps_edi.b1.national_pension_premiums.support_details

MCP 도구 이름 nps_edi__b1__national_pension_premiums__support_details

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

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

고지 연월과 차수를 넣거나 앞서 고른 고지가 있으면, 그 고지의 가입자 목록과 지원내역 목록, 지원금액 합계를 돌려줍니다.

  • 요약 조회와 선행 조건이 같습니다. 대상을 먼저 선택하거나 선택 조건을 함께 보냅니다. [국민연금공단 EDI 로그인]
  • 기관이 데이터셋을 주었는데 가입자 행과 지원 상세 행이 비면 success=true, error_code=null, implementation_status=pension_support_dataset_empty.
  • 기관이 데이터셋을 하나도 주지 않으면 success=false, error_code=null, implementation_status=pension_support_dataset_empty.

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.b1.national_pension_premiums.support_details이 API 고정값 (기본값)

예시 : nps_edi.b1.national_pension_premiums.support_details

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

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-조건부작업 파라미터입니다. 아래 params 파라미터 표의 row_index, row_key, notice_year_month, installment_round, template_code, row_text_contains 또는 cell_text_contains 중 하나 이상을 보냅니다. 앞 단계에서 고른 항목이 같은 연동 계정의 세션에 남아 있으면 빈 객체로 보내 그 항목을 씁니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
row_indexnumber-조건부search/select 결과 options[].row_index. 지정 시 세션 cached selected_notice 재선택
row_keystring-조건부search/select 결과 options[].row_key
notice_year_monthstring6조건부고지 연월. cached selected_notice와 불일치 시 재선택

형식 : YYYYMM

installment_roundstring-조건부고지 차수. 1=1차(ED02), 2=2차(ED08). 정수 · 문자열 모두 허용
template_codestring-조건부고지 양식 코드 (예: ED02)
row_text_containsstring-조건부행 텍스트 부분 일치 필터
cell_text_containsstring-조건부칸 하나 안의 텍스트 부분 일치 필터
output_formatsarray-N이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: support_details-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nps_edi",
  "action": "nps_edi.b1.national_pension_premiums.support_details",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "row_index": "<필수: number>"
  }
}'

Response

  • members·support_details를 확인합니다.
  • 아래 표의 members[], support_details[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 엑셀 파일 맨 윗줄의 머리글입니다.
  • 아래 표의 줄은 엑셀로 내보내는 열이라 응답 행의 칸 전부가 아닐 수 있습니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
membersarray가입자 목록 배열 (가입자별 보험료 내역과 같은 칸)
members[].sequencestring | number | boolean | object | array | null순번
members[].namestring | number | boolean | object | array | null가입자명
members[].standard_monthly_incomestring | number | boolean | object | array | null기준소득월액
members[].pension_premiumstring | number | boolean | object | array | null연금보험료
members[].employee_contributionstring | number | boolean | object | array | null가입자 부담금
members[].employer_contributionstring | number | boolean | object | array | null사용자 부담금
members[].support_after_employee_contributionstring | number | boolean | object | array | null지원 후 가입자 부담금
members[].support_after_employer_contributionstring | number | boolean | object | array | null지원 후 사용자 부담금
support_detailsarray지원내역 목록 배열 (가입자별 결정년월, 지원금액, 지원율)
support_details[].sequencestring | number | boolean | object | array | null순번
support_details[].namestring | number | boolean | object | array | null가입자명
support_details[].decision_year_monthstring | number | boolean | object | array | null결정년월
support_details[].pension_premiumstring | number | boolean | object | array | null연금보험료
support_details[].support_amountstring | number | boolean | object | array | null지원금액
support_details[].support_ratestring | number | boolean | object | array | null지원율
support_details[].planned_employer_contributionstring | number | boolean | object | array | null예정 사용자 부담금
support_details[].planned_employee_contributionstring | number | boolean | object | array | null예정 가입자 부담금
workplaceobject사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수)
noticeobject선택한 고지 정보 (귀속 연월, 회차, 서식, 문서번호, 접수일)
summaryobject지원 요약 (가입자 수, 지원 내역 수, 지원금 합계)
json
// result.data
{
  "members": [
    {
      "sequence": "1",
      "name": "...",
      "identifiers": {},
      "standard_monthly_income": 0,
      "pension_premium": 0,
      "employee_contribution": 0,
      "employer_contribution": 0,
      "support_after_employee_contribution": 0,
      "support_after_employer_contribution": 0,
      "raw": {}
    }
  ],
  "support_details": [
    {
      "sequence": "1",
      "name": "...",
      "identifiers": {},
      "decision_year_month": "...",
      "pension_premium": 0,
      "support_amount": 0,
      "support_rate": "...",
      "planned_employer_contribution": 0,
      "planned_employee_contribution": 0,
      "raw": {}
    }
  ],
  "workplace": {},
  "notice": {},
  "summary": {}
}
순번오류 코드발생 조건
PROVIDER_VALIDATION_ERROR선택 오류 — 고지 내역을 먼저 선택(select)해야 하거나, 조건에 맞는 행을 찾지 못했습니다.