연금고지 - 국민연금공단 EDI
1. 국민연금 보험료 고지 목록 검색nps_ edi. b1. pension_ notices. search
MCP 도구 이름 nps_
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
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| 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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| start_ | string | 8 | N | 검색 시작일. 미입력 시 오늘 기준 90일 전 | |
| end_ | string | 8 | N | 검색 종료일. 미입력 시 오늘 | |
| notice_ | string | 6 | N | 고지 연월. 입력 시 수신일 기준 검색창 자동 확장. 형식 오류 시 INVALID_NOTICE_YEAR_MONTH | |
| installment_ | string | - | N | 고지 차수. 1=1차(ED02), 2=2차(ED08). 정수 · 문자열 모두 허용 | |
| template_ | string | - | N | 고지 양식 코드 (예: ED02) | |
| row_ | string | - | N | 행 텍스트 부분 일치 필터 (서버측 후처리) | |
| page_ | number | - | N | 페이지 번호. 기본 1 | |
| page_ | number | - | N | 페이지당 행 수. 기본 10 |
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를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| options | array | 고지 목록 행 배열 | |
| row_ | number | 반환 행 수 | |
| workplace | object | 사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수) | |
| workflow_ | object | 연동 방식 정보 (전송 방식과 화면 호출 경로) |
// 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_ | 형식 오류 — notice_year_month 는 YYYYMM 형식의 실제 연월이어야 하고, start_date 는 end_date 보다 늦을 수 없습니다. |
2. 국민연금 보험료 고지 선택nps_ edi. b1. pension_ notices. select
MCP 도구 이름 nps_
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
행 번호나 고지 연월과 차수를 넣어 고지 한 건을 고르면, 그 고지를 같은 세션에 기억해 두고 고지 정보를 돌려줍니다. 이후 보험료 상세 API에서 재사용됩니다.
- 고지 목록 조회로 후보를 먼저 만들거나, 선택 조건으로 목록에서 직접 지정합니다. [국민연금공단 EDI 로그인]
- selector를 생략하면 필터에 맞는 첫 행이 자동 선택됩니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| row_ | number | - | N | search 결과 options[].row_index | |
| row_ | string | - | N | search 결과 options[].row_key | |
| notice_ | string | 6 | N | 고지 연월 필터 | |
| installment_ | string | - | N | 고지 차수. 1=1차, 2=2차. 정수 · 문자열 모두 허용 | |
| template_ | string | - | N | 고지 양식 코드 필터 | |
| row_ | string | - | N | 행 텍스트 부분 일치 필터 | |
| cell_ | string | - | N | 칸 하나 안의 텍스트 부분 일치 필터 |
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_ | object | 선택된 고지 행 정보 | |
| selection | object | 선택 컨텍스트 (이후 상세 API에서 재사용) | |
| next_ | array | 다음 단계 힌트 배열 |
// result.data
{
"selected_option": {},
"selection": {},
"next_steps": []
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 후보 0건 — 조건에 맞는 행을 찾지 못했습니다. |