개발자 문서
API 레퍼런스

연금고지 - 국민연금공단 EDI

MCP 도구 이름 nps_edi__b1__pension_notices__search

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

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

기간이나 고지 연월을 넣으면 사업장에 온 국민연금 보험료 고지를 연월, 차수, 접수일, 열람 상태와 함께 목록으로 돌려줍니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [국민연금공단 EDI 로그인]
  • result.data.error_code=PENSION_NOTICE_SEARCH_EMPTY.
  • notice_year_month 입력 시 수신일 기준 검색창이 자동 확장됩니다.

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.pension_notices.search이 API 고정값 (기본값)

예시 : nps_edi.b1.pension_notices.search

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

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
start_datestring8N검색 시작일. 미입력 시 오늘 기준 90일 전

형식 : YYYYMMDD

end_datestring8N검색 종료일. 미입력 시 오늘

형식 : YYYYMMDD

notice_year_monthstring6N고지 연월. 입력 시 수신일 기준 검색창 자동 확장. 형식 오류 시 INVALID_NOTICE_YEAR_MONTH

형식 : YYYYMM

installment_roundstring-N고지 차수. 1=1차(ED02), 2=2차(ED08). 정수 · 문자열 모두 허용
template_codestring-N고지 양식 코드 (예: ED02)
row_text_containsstring-N행 텍스트 부분 일치 필터 (서버측 후처리)
page_nonumber-N페이지 번호. 기본 1
page_per_countnumber-N페이지당 행 수. 기본 10
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: search-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nps_edi",
  "action": "nps_edi.b1.pension_notices.search",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • options를 확인합니다.
순번변수명타입설명
optionsarray고지 목록 행 배열
row_countnumber반환 행 수
workplaceobject사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수)
workflow_contractobject연동 방식 정보 (전송 방식과 화면 호출 경로)
json
// result.data
{
  "phase": "notice_search",
  "options": [
    {
      "title": "(2026.09월) 국민연금보험료 결정내역 통보서(2차)",
      "row_key": "20260921-095545-890845",
      "row_index": 1,
      "selection": {
        "row_key": "20260921-095545-890845",
        "row_index": 1,
        "row_text_contains": "(2026.09월) 국민연금보험료 결정내역 통보서(2차)"
      },
      "data_count": 3,
      "document_no": "20260921-095545-890845",
      "read_status": "읽지않음",
      "received_at": "2026-09-21 09:55:45",
      "received_date": "20260919",
      "template_code": "ED08",
      "template_name": "(2026.09월) 국민연금보험료 결정내역 통보서(2차)",
      "installment_round": "2",
      "notice_year_month": "202609",
      "received_document_no": "NPS12345678901234"
    },
    {
      "title": "(2026.09월) 국민연금보험료 결정내역 통보서(1차)",
      "row_key": "20260917-091307-097412",
      "row_index": 2,
      "selection": {
        "row_key": "20260917-091307-097412",
        "row_index": 2,
        "row_text_contains": "(2026.09월) 국민연금보험료 결정내역 통보서(1차)"
      },
      "data_count": 3,
      "document_no": "20260917-091307-097412",
      "read_status": "읽지않음",
      "received_at": "2026-09-17 09:13:07",
      "received_date": "20260917",
      "template_code": "ED02",
      "template_name": "(2026.09월) 국민연금보험료 결정내역 통보서(1차)",
      "installment_round": "1",
      "notice_year_month": "202609",
      "received_document_no": "NPS12345678901234"
    },
    {
      "title": "(2026.08월) 국민연금보험료 결정내역 통보서(2차)",
      "row_key": "20260824-094232-722425",
      "row_index": 3,
      "selection": {
        "row_key": "20260824-094232-722425",
        "row_index": 3,
        "row_text_contains": "(2026.08월) 국민연금보험료 결정내역 통보서(2차)"
      },
      "data_count": 3,
      "document_no": "20260824-094232-722425",
      "read_status": "읽지않음",
      "received_at": "2026-08-24 09:42:32",
      "received_date": "20260822",
      "template_code": "ED08",
      "template_name": "(2026.08월) 국민연금보험료 결정내역 통보서(2차)",
      "installment_round": "2",
      "notice_year_month": "202608",
      "received_document_no": "NPS12345678901234"
    },
    {
      "title": "(2026.08월) 국민연금보험료 결정내역 통보서(1차)",
      "row_key": "20260820-104603-752615",
      "row_index": 4,
      "selection": {
        "row_key": "20260820-104603-752615",
        "row_index": 4,
        "row_text_contains": "(2026.08월) 국민연금보험료 결정내역 통보서(1차)"
      },
      "data_count": 3,
      "document_no": "20260820-104603-752615",
      "read_status": "읽지않음",
      "received_at": "2026-08-20 10:46:03",
      "received_date": "20260820",
      "template_code": "ED02",
      "template_name": "(2026.08월) 국민연금보험료 결정내역 통보서(1차)",
      "installment_round": "1",
      "notice_year_month": "202608",
      "received_document_no": "NPS12345678901234"
    },
    {
      "title": "(2026.07월) 국민연금보험료 결정내역 통보서(2차)",
      "row_key": "20260721-100732-138722",
      "row_index": 5,
      "selection": {
        "row_key": "20260721-100732-138722",
        "row_index": 5,
        "row_text_contains": "(2026.07월) 국민연금보험료 결정내역 통보서(2차)"
      },
      "data_count": 3,
      "document_no": "20260721-100732-138722",
      "read_status": "읽지않음",
      "received_at": "2026-07-21 10:07:32",
      "received_date": "20260721",
      "template_code": "ED08",
      "template_name": "(2026.07월) 국민연금보험료 결정내역 통보서(2차)",
      "installment_round": "2",
      "notice_year_month": "202607",
      "received_document_no": "NPS12345678901234"
    },
    {
      "title": "(2026.07월) 국민연금보험료 결정내역 통보서(1차)",
      "row_key": "20260720-103348-965849",
      "row_index": 6,
      "selection": {
        "row_key": "20260720-103348-965849",
        "row_index": 6,
        "row_text_contains": "(2026.07월) 국민연금보험료 결정내역 통보서(1차)"
      },
      "data_count": 3,
      "document_no": "20260720-103348-965849",
      "read_status": "읽지않음",
      "received_at": "2026-07-20 10:33:48",
      "received_date": "20260717",
      "template_code": "ED02",
      "template_name": "(2026.07월) 국민연금보험료 결정내역 통보서(1차)",
      "installment_round": "1",
      "notice_year_month": "202607",
      "received_document_no": "NPS12345678901234"
    }
  ],
  "success": true,
  "row_count": 6,
  "workplace": {
    "nps_no": "12345678901",
    "branch_tel": "02-1234-5678",
    "branch_code": "1124",
    "branch_name": "강서",
    "business_no": "1234567890",
    "workplace_name": "예시 주식회사",
    "subscriber_count": 3,
    "business_management_no": "12345678901",
    "business_management_no_display": "123-45-67890-1"
  },
  "error_code": null,
  "route_kind": "live",
  "feature_name": "...",
  "workflow_step": "national_pension_notice_search",
  "source_evidence": {
    "url": "https://...",
    "status_code": 200,
    "wire_format": "...",
    "content_type": "...",
    "expected_datasets": [
      "...",
      "..."
    ],
    "dataset_row_counts": {
      "...": 6,
      "...2": 1
    },
    "response_parameters": {
      "ErrorCode": "..."
    },
    "transaction_contract": {
      "tags": [
        "..."
      ],
      "endpoint": "...",
      "page_per_count": 10,
      "source_scripts": [
        "https://...",
        "https://..."
      ],
      "contract_source": "...",
      "page_dataset_name": "...",
      "private_program_id": "...",
      "input_dataset_names": [
        "...",
        "...",
        "..."
      ],
      "source_execution_id": "...",
      "private_wedi_dmnd_cd": "...",
      "business_dataset_names": [
        "..."
      ],
      "response_dataset_names": [
        "...",
        "..."
      ]
    },
    "response_dataset_names": [
      "...",
      "..."
    ]
  },
  "workflow_contract": {
    "endpoints": {
      "guide": "...",
      "notices": "...",
      "summary": "...",
      "workplace": "...",
      "subscribers": "...",
      "retro_payments": "...",
      "payment_history": "...",
      "support_details": [
        "...",
        "..."
      ],
      "loss_check_counts": "..."
    },
    "transport": "nexacro_xml_request_json_response",
    "recorded_sets": [
      "business_management_no_login",
      "national_pension_notice_search",
      "notice_row_selection",
      "decision_summary",
      "subscriber_details",
      "payment_history",
      "retro_payments",
      "support_details"
    ],
    "hidden_script_urls": [
      "https://...",
      "https://...",
      "https://...",
      "https://...",
      "https://...",
      "https://...",
      "https://...",
      "https://...",
      "https://...",
      "https://...",
      "https://...",
      "https://...",
      "https://...",
      "https://...",
      "https://...",
      "https://...",
      "https://..."
    ],
    "source_execution_id": "7b3dbbe5-6b3c-48cd-8cc7-756d00725584"
  },
  "implementation_status": null
}
순번오류 코드발생 조건
VALIDATION_INVALID_FIELD형식 오류 — notice_year_month 는 YYYYMM 형식의 실제 연월이어야 하고, start_date 는 end_date 보다 늦을 수 없습니다.

2. 국민연금 보험료 고지 선택nps_edi.b1.pension_notices.select

MCP 도구 이름 nps_edi__b1__pension_notices__select

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

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

행 번호나 고지 연월과 차수를 넣어 고지 한 건을 고르면, 그 고지를 같은 세션에 기억해 두고 고지 정보를 돌려줍니다. 이후 보험료 상세 API에서 재사용됩니다.

  • 고지 목록 조회로 후보를 먼저 만들거나, 선택 조건으로 목록에서 직접 지정합니다. [국민연금공단 EDI 로그인]
  • selector를 생략하면 필터에 맞는 첫 행이 자동 선택됩니다.

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.pension_notices.select이 API 고정값 (기본값)

예시 : nps_edi.b1.pension_notices.select

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

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
row_indexnumber-Nsearch 결과 options[].row_index
row_keystring-Nsearch 결과 options[].row_key
notice_year_monthstring6N고지 연월 필터

형식 : YYYYMM

installment_roundstring-N고지 차수. 1=1차, 2=2차. 정수 · 문자열 모두 허용
template_codestring-N고지 양식 코드 필터
row_text_containsstring-N행 텍스트 부분 일치 필터
cell_text_containsstring-N칸 하나 안의 텍스트 부분 일치 필터
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: select-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nps_edi",
  "action": "nps_edi.b1.pension_notices.select",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • selected_option·selection·next_steps를 확인합니다.
순번변수명타입설명
selected_optionobject선택된 고지 행 정보
selectionobject선택 컨텍스트 (이후 상세 API에서 재사용)
next_stepsarray다음 단계 힌트 배열
json
// result.data
{
  "selected_option": {},
  "selection": {},
  "next_steps": []
}
순번오류 코드발생 조건
PROVIDER_VALIDATION_ERROR후보 0건 — 조건에 맞는 행을 찾지 못했습니다.