연금통지 - 국민연금공단 EDI
1. 연금 통지문서 상세 조회nps_ edi. b1. pension_ notification_ documents. detail
MCP 도구 이름 nps_
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
연금 통지문서 목록 검색에서 고른 문서를 넣으면 가입자별 근무기간, 소득총액, 결정 기준소득월액과 월 보험료를 돌려줍니다. ED33 양식만 지원합니다.
- 목록 조회로 행을 찾거나, document_no 로 문서를 직접 지정합니다. [국민연금공단 EDI 로그인]
- result.data.error_code=PENSION_NOTIFICATION_DOCUMENT_DETAIL_EMPTY.
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. search 선행 또는 동일 세션 내 search 직후 | |
| row_ | string | N | search 결과 options[].row_key (wediDocNo 등) | |
| document_ | string | N | 전자문서번호 wediDocNo | |
| receipt_ | string | N | 접수 전자문서번호 rcptnWediDocNo | |
| template_ | string | N | 양식 코드. 상세 조회는 ED33만 지원 (그 외 UNSUPPORTED_PENSION_NOTIFICATION_TEMPLATE) | |
| row_ | string | N | 행 텍스트 부분 일치 필터 | |
| member_ | string | N | 상세 멤버 검색용 성명 | |
| member_ | string | N | 상세 멤버 검색용 주민등록번호 | |
| search_ | string | N | 상세 멤버 검색 유형 코드 | |
| page_ | number | N | 멤버 목록 페이지. 기본 1 | |
| page_ | number | N | 멤버 목록 페이지당 행 수. 기본 10 | |
| mark_ | boolean | N | 조회 시 읽음 처리. 기본 true | |
| include_ | boolean | N | export_rows 포함. 기본 true | |
| include_ | boolean | N | guide_rows 포함. 기본 true |
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: detail-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "nps_edi",
"action": "nps_edi.b1.pension_notification_documents.detail",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- document·members·rows를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| document | object | 통지문서 메타정보 객체 | |
| members | array | 대상 멤버 목록 배열 | |
| rows | array | 상세 행 배열 | |
| selected_ | object | 선택한 통지문서 행 정보 | |
| workplace | object | 사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수) | |
| search | object | 이번 조회에 쓰인 조회 조건 (문서번호, 접수번호, 서식) | |
| summary | object | 대상자 요약 (인원수, 소득 합계, 결정 기준소득월액과 월 보험료 합계) | |
| row_ | number | 대상자 행 수 | |
| page | object | 페이지 정보 | |
| export_ | array | 내보내기용 행 | |
| export_ | number | 내보내기용 행 수 | |
| guide_ | array | 화면 안내 문구 행 | |
| read_ | object | 열람 처리 결과 | |
| workflow_ | object | 연동 방식 정보 (전송 방식과 화면 호출 경로) |
// result.data
{
"page": {
"pageNo": "1",
"totRowCnt": "3",
"pagePerCnt": "10"
},
"rows": [
{
"rnum": "1",
"jnprNm": "홍길동",
"prcsYmd": "20260507",
"rcptnTm": "132452",
"bfchIsfe": "289740",
"crrnMamt": "2960000",
"rcptnYmd": "20260513",
"snrDocSn": "984944",
"spnoDcnt": "0",
"workTnds": "34",
"earnGramt": "3355000",
"jnprErrno": "[REDACTED]",
"rcptnNocs": "34",
"wediDocNo": "20260518-132452-836036",
"crtrMmIsfe": "281200",
"lastTrsmTm": "132452 ",
"bfrCrrnMamt": "3050000",
"lastTrsmYmd": "20260518",
"wediTmpltCd": "ED33",
"prstWorkPrdCn": "2025-11-28~2025-12-31",
"wediSnrSttsCd": "C",
"rcptnWediDocNo": "NPS12345678901234",
"txtnDataSeCdNm": "Y",
"oriPrstWorkPrdCn": "20251128"
},
{
"rnum": "2",
"jnprNm": "홍길동",
"prcsYmd": "20260507",
"rcptnTm": "132452",
"bfchIsfe": "186760",
"crrnMamt": "1920000",
"rcptnYmd": "20260513",
"snrDocSn": "984945",
"spnoDcnt": "0",
"workTnds": "43",
"earnGramt": "2753334",
"jnprErrno": "[REDACTED]",
"rcptnNocs": "34",
"wediDocNo": "20260518-132452-836036",
"crtrMmIsfe": "182400",
"lastTrsmTm": "132452 ",
"bfrCrrnMamt": "1966000",
"lastTrsmYmd": "20260518",
"wediTmpltCd": "ED33",
"prstWorkPrdCn": "2025-11-19~2025-12-31",
"wediSnrSttsCd": "C",
"rcptnWediDocNo": "NPS12345678901234",
"txtnDataSeCdNm": "Y",
"oriPrstWorkPrdCn": "20251119"
},
{
"rnum": "3",
"jnprNm": "홍길동",
"prcsYmd": "20260507",
"rcptnTm": "132452",
"bfchIsfe": "137740",
"crrnMamt": "2915000",
"rcptnYmd": "20260513",
"snrDocSn": "984946",
"spnoDcnt": "0",
"workTnds": "214",
"earnGramt": "20800000",
"jnprErrno": "[REDACTED]",
"rcptnNocs": "34",
"wediDocNo": "20260518-132452-836036",
"crtrMmIsfe": "276920",
"lastTrsmTm": "132452 ",
"bfrCrrnMamt": "1450000",
"lastTrsmYmd": "20260518",
"wediTmpltCd": "ED33",
"prstWorkPrdCn": "2025-06-01~2025-12-31",
"wediSnrSttsCd": "C",
"rcptnWediDocNo": "NPS12345678901234",
"txtnDataSeCdNm": "Y",
"oriPrstWorkPrdCn": "20250601"
}
],
"phase": "detail",
"search": {
"page_no": 1,
"receipt_no": "",
"document_no": "20260518-132452-836036",
"member_name": "",
"mark_as_read": true,
"include_guide": true,
"template_code": "ED33",
"template_name": "",
"page_per_count": 10,
"total_row_count": 3,
"search_type_code": "",
"include_export_rows": true
},
"members": [
{
"raw": {
"rnum": "1",
"jnprNm": "홍길동",
"prcsYmd": "20260507",
"rcptnTm": "132452",
"bfchIsfe": "289740",
"crrnMamt": "2960000",
"rcptnYmd": "20260513",
"snrDocSn": "984944",
"spnoDcnt": "0",
"workTnds": "34",
"earnGramt": "3355000",
"jnprErrno": "[REDACTED]",
"rcptnNocs": "34",
"wediDocNo": "20260518-132452-836036",
"crtrMmIsfe": "281200",
"lastTrsmTm": "132452 ",
"bfrCrrnMamt": "3050000",
"lastTrsmYmd": "20260518",
"wediTmpltCd": "ED33",
"prstWorkPrdCn": "2025-11-28~2025-12-31",
"wediSnrSttsCd": "C",
"rcptnWediDocNo": "NPS12345678901234",
"txtnDataSeCdNm": "Y",
"oriPrstWorkPrdCn": "20251128"
},
"name": "홍길동",
"decision": {
"monthly_premium": 281200,
"standard_monthly_income": 2960000
},
"previous": {
"monthly_premium": 289740,
"standard_monthly_income": 3050000
},
"sequence": 1,
"receipt_no": "NPS12345678901234",
"document_no": "20260518-132452-836036",
"identifiers": {
"resident_no_masked": "[REDACTED]"
},
"work_period": {
"raw": "2025-11-28~2025-12-31",
"work_days": 34,
"leave_days": 0,
"start_date": "20251128"
},
"income_total": 3355000,
"template_code": "ED33",
"processed_date": "20260507",
"taxable_data_decision": "Y"
},
{
"raw": {
"rnum": "2",
"jnprNm": "홍길동",
"prcsYmd": "20260507",
"rcptnTm": "132452",
"bfchIsfe": "186760",
"crrnMamt": "1920000",
"rcptnYmd": "20260513",
"snrDocSn": "984945",
"spnoDcnt": "0",
"workTnds": "43",
"earnGramt": "2753334",
"jnprErrno": "[REDACTED]",
"rcptnNocs": "34",
"wediDocNo": "20260518-132452-836036",
"crtrMmIsfe": "182400",
"lastTrsmTm": "132452 ",
"bfrCrrnMamt": "1966000",
"lastTrsmYmd": "20260518",
"wediTmpltCd": "ED33",
"prstWorkPrdCn": "2025-11-19~2025-12-31",
"wediSnrSttsCd": "C",
"rcptnWediDocNo": "NPS12345678901234",
"txtnDataSeCdNm": "Y",
"oriPrstWorkPrdCn": "20251119"
},
"name": "홍길동",
"decision": {
"monthly_premium": 182400,
"standard_monthly_income": 1920000
},
"previous": {
"monthly_premium": 186760,
"standard_monthly_income": 1966000
},
"sequence": 2,
"receipt_no": "NPS12345678901234",
"document_no": "20260518-132452-836036",
"identifiers": {
"resident_no_masked": "[REDACTED]"
},
"work_period": {
"raw": "2025-11-19~2025-12-31",
"work_days": 43,
"leave_days": 0,
"start_date": "20251119"
},
"income_total": 2753334,
"template_code": "ED33",
"processed_date": "20260507",
"taxable_data_decision": "Y"
},
{
"raw": {
"rnum": "3",
"jnprNm": "홍길동",
"prcsYmd": "20260507",
"rcptnTm": "132452",
"bfchIsfe": "137740",
"crrnMamt": "2915000",
"rcptnYmd": "20260513",
"snrDocSn": "984946",
"spnoDcnt": "0",
"workTnds": "214",
"earnGramt": "20800000",
"jnprErrno": "[REDACTED]",
"rcptnNocs": "34",
"wediDocNo": "20260518-132452-836036",
"crtrMmIsfe": "276920",
"lastTrsmTm": "132452 ",
"bfrCrrnMamt": "1450000",
"lastTrsmYmd": "20260518",
"wediTmpltCd": "ED33",
"prstWorkPrdCn": "2025-06-01~2025-12-31",
"wediSnrSttsCd": "C",
"rcptnWediDocNo": "NPS12345678901234",
"txtnDataSeCdNm": "Y",
"oriPrstWorkPrdCn": "20250601"
},
"name": "홍길동",
"decision": {
"monthly_premium": 276920,
"standard_monthly_income": 2915000
},
"previous": {
"monthly_premium": 137740,
"standard_monthly_income": 1450000
},
"sequence": 3,
"receipt_no": "NPS12345678901234",
"document_no": "20260518-132452-836036",
"identifiers": {
"resident_no_masked": "[REDACTED]"
},
"work_period": {
"raw": "2025-06-01~2025-12-31",
"work_days": 214,
"leave_days": 0,
"start_date": "20250601"
},
"income_total": 20800000,
"template_code": "ED33",
"processed_date": "20260507",
"taxable_data_decision": "Y"
}
],
"success": true,
"summary": {
"income_total": 26908334,
"member_count": 3,
"decision_monthly_premium_total": 740520,
"previous_monthly_premium_total": 614240,
"decision_standard_monthly_income_total": 7795000,
"previous_standard_monthly_income_total": 6466000
},
"document": {
"raw": {
"rnum": 1,
"wediDocNo": "20260518-132452-836036",
"wediSnrSeCd": "O",
"wediTmpltCd": "ED33",
"wediTmpltNm": "",
"regWediUserId": "user01",
"rcptnWediDocNo": ""
},
"direction": "O",
"row_index": 1,
"data_count": 0,
"receipt_no": "",
"document_no": "20260518-132452-836036",
"received_at": null,
"received_date": null,
"template_code": "ED33",
"template_name": "",
"confirmed_date": null,
"last_sent_date": null,
"last_sent_time": "",
"verification_no": null,
"read_status_code": null,
"read_status_name": null
},
"row_count": 3,
"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,
"guide_rows": [
{
"gdbk2": "○ 근로소득 과세자료보유자는 별도의 사업장 신고 없이 과세소득자료로 사업장가입자의 2026년도 기준소득월액을 결정합니다.\n○ 본 조회 내용은 \"2025년 근로소득 과세자료를 활용한 기준소득월액 결정내용\" 입니다.\n - 해당 사업장의 근로소득 과세자료가 확인되지 않는 가입자는 소득총액신고대상입니다.\n - 조회 후 이상이 있는 대상은 5월 18일 이후 정정신고가 가능합니다.\n\n○ EDI 수정신고 방법\n 1. 하단의 '정정신고용 파일저장' 선택 후 이용자 PC에 파일 저장\n 2. 저장된 파일을 열어 수정 후 저장\n 3. 국민연금 웹EDI 접속 -> (상단메뉴)연금고유 신고 -> (좌측메뉴)연금고유 신고 -> 소득총액 신고 선택",
"useYn": "Y",
"menuId": "M07011100",
"prgrmId": "...",
"wediMenuNm": "기준소득월액 정기결정내용 사전 안내 통지서",
"frstRegWediUserId": "user01",
"lastRegWediUserId": "user01"
}
],
"route_kind": "live",
"export_rows": [
{
"rnum": "1",
"jnprNm": "홍길동",
"prcsYmd": "20260507",
"rcptnTm": "132452",
"bfchIsfe": "289740",
"crrnMamt": "2960000",
"rcptnYmd": "20260513",
"snrDocSn": "984944",
"spnoDcnt": "0",
"workTnds": "34",
"earnGramt": "3355000",
"jnprErrno": "[REDACTED]",
"rcptnNocs": "34",
"wediDocNo": "20260518-132452-836036",
"crtrMmIsfe": "281200",
"lastTrsmTm": "132452 ",
"bfrCrrnMamt": "3050000",
"lastTrsmYmd": "20260518",
"wediTmpltCd": "ED33",
"prstWorkPrdCn": "2025-11-28~2025-12-31",
"wediSnrSttsCd": "C",
"rcptnWediDocNo": "NPS12345678901234",
"txtnDataSeCdNm": "Y",
"oriPrstWorkPrdCn": "20251128"
},
{
"rnum": "2",
"jnprNm": "홍길동",
"prcsYmd": "20260507",
"rcptnTm": "132452",
"bfchIsfe": "186760",
"crrnMamt": "1920000",
"rcptnYmd": "20260513",
"snrDocSn": "984945",
"spnoDcnt": "0",
"workTnds": "43",
"earnGramt": "2753334",
"jnprErrno": "[REDACTED]",
"rcptnNocs": "34",
"wediDocNo": "20260518-132452-836036",
"crtrMmIsfe": "182400",
"lastTrsmTm": "132452 ",
"bfrCrrnMamt": "1966000",
"lastTrsmYmd": "20260518",
"wediTmpltCd": "ED33",
"prstWorkPrdCn": "2025-11-19~2025-12-31",
"wediSnrSttsCd": "C",
"rcptnWediDocNo": "NPS12345678901234",
"txtnDataSeCdNm": "Y",
"oriPrstWorkPrdCn": "20251119"
},
{
"rnum": "3",
"jnprNm": "홍길동",
"prcsYmd": "20260507",
"rcptnTm": "132452",
"bfchIsfe": "137740",
"crrnMamt": "2915000",
"rcptnYmd": "20260513",
"snrDocSn": "984946",
"spnoDcnt": "0",
"workTnds": "214",
"earnGramt": "20800000",
"jnprErrno": "[REDACTED]",
"rcptnNocs": "34",
"wediDocNo": "20260518-132452-836036",
"crtrMmIsfe": "276920",
"lastTrsmTm": "132452 ",
"bfrCrrnMamt": "1450000",
"lastTrsmYmd": "20260518",
"wediTmpltCd": "ED33",
"prstWorkPrdCn": "2025-06-01~2025-12-31",
"wediSnrSttsCd": "C",
"rcptnWediDocNo": "NPS12345678901234",
"txtnDataSeCdNm": "Y",
"oriPrstWorkPrdCn": "20250601"
}
],
"read_update": {
"rows": [
{
"status": "S"
}
],
"status": "S",
"skipped": false,
"source_evidence": {
"url": "https://...",
"status_code": 200,
"wire_format": "...",
"content_type": "...",
"expected_datasets": [
"..."
],
"dataset_row_counts": {
"...": 1
},
"response_parameters": {
"ErrorCode": "..."
},
"transaction_contract": {
"tags": [
"...",
"...",
"..."
],
"endpoint": "...",
"page_per_count": 10,
"source_scripts": [
"https://..."
],
"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": [
"..."
]
}
},
"feature_name": "...",
"workflow_step": "pension_notification_document_detail_lookup",
"selected_option": {
"raw": {
"rnum": 1,
"wediDocNo": "20260518-132452-836036",
"wediSnrSeCd": "O",
"wediTmpltCd": "ED33",
"wediTmpltNm": "",
"regWediUserId": "user01",
"rcptnWediDocNo": ""
},
"row_key": "20260518-132452-836036",
"direction": null,
"notice_at": null,
"row_index": 1,
"data_count": 0,
"receipt_no": "",
"document_no": "20260518-132452-836036",
"template_code": "ED33",
"template_name": "",
"confirmed_date": null,
"last_sent_date": null,
"last_sent_time": "",
"verification_no": null,
"read_status_code": null,
"read_status_name": null,
"transaction_date": null,
"processing_status_code": null
},
"source_evidence": {
"guide": {
"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": [
"https://..."
],
"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": [
"...",
"..."
]
},
"detail": {
"url": "https://...",
"status_code": 200,
"wire_format": "...",
"content_type": "...",
"expected_datasets": [
"...",
"..."
],
"dataset_row_counts": {
"...": 3,
"...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": [
"...",
"..."
]
},
"workplace": {
"url": "https://...",
"status_code": 200,
"wire_format": "...",
"content_type": "...",
"expected_datasets": [
"..."
],
"dataset_row_counts": {
"...": 1
},
"response_parameters": {
"ErrorCode": "..."
},
"transaction_contract": {
"tags": [
"...",
"...",
"..."
],
"endpoint": "...",
"page_per_count": 10,
"source_scripts": [
"https://..."
],
"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": [
"..."
]
},
"export_rows": {
"url": "https://...",
"status_code": 200,
"wire_format": "...",
"content_type": "...",
"expected_datasets": [
"..."
],
"dataset_row_counts": {
"...": 3
},
"response_parameters": {
"ErrorCode": "..."
},
"transaction_contract": {
"tags": [
"...",
"...",
"...",
"..."
],
"endpoint": "...",
"page_per_count": 10,
"source_scripts": [
"https://..."
],
"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": [
"..."
]
},
"read_update": {
"url": "https://...",
"status_code": 200,
"wire_format": "...",
"content_type": "...",
"expected_datasets": [
"..."
],
"dataset_row_counts": {
"...": 1
},
"response_parameters": {
"ErrorCode": "..."
},
"transaction_contract": {
"tags": [
"...",
"...",
"..."
],
"endpoint": "...",
"page_per_count": 10,
"source_scripts": [
"https://..."
],
"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": [
"..."
]
}
},
"export_row_count": 3,
"workflow_contract": {
"endpoints": {
"guide": "...",
"detail": "...",
"workplace": "...",
"export_rows": "...",
"read_update": "..."
},
"transport": "nexacro_xml_request_json_response",
"input_datasets": {
"guide": [
"..."
],
"detail": [
"...",
"...",
"..."
],
"workplace": [
"..."
],
"export_rows": [
"..."
],
"read_update": [
"..."
]
},
"response_datasets": {
"guide": [
"...",
"..."
],
"detail": [
"...",
"..."
],
"workplace": [
"..."
],
"export_rows": [
"..."
],
"read_update": [
"..."
]
}
},
"implementation_status": null
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 양식·행 오류 — 지원하지 않는 통지서 양식이거나, 조건에 맞는 행을 찾지 못했습니다. |
2. 연금 통지문서 목록 검색nps_ edi. b1. pension_ notification_ documents. search
MCP 도구 이름 nps_
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
기간과 통지 서식을 넣으면 사업장에 온 연금 통지문서를 서식명, 송수신 구분, 열람 상태, 통지일시와 함께 목록으로 돌려줍니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [국민연금공단 EDI 로그인]
- result.data.error_code=PENSION_NOTIFICATION_DOCUMENTS_EMPTY.
- 날짜 미입력 시 최근 90일.
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 | 검색 종료일. 미입력 시 오늘 | |
| template_ | string | - | N | 통지문서 양식 코드. A·ALL·전체는 전체 조회로 처리 | |
| member_ | string | - | N | 가입자 성명 | |
| member_ | string | - | N | 가입자 주민등록번호 | |
| read_ | string | - | N | 열람 상태. 01=읽지않음, 05=읽음, 10=전체(읽음+읽지않음), 빈값=전체 | |
| row_ | string | - | N | 행 텍스트 부분 일치 필터 (서버측 후처리) | |
| page_ | number | - | N | 페이지 번호. 기본 1 | |
| page_ | number | - | N | 페이지당 행 수. 기본 10 | |
| output_ | array | - | N | 이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다 |
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_notification_documents.search",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- options·rows를 확인합니다.
- 아래 표의 options[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 엑셀 파일 맨 윗줄의 머리글입니다.
- 아래 표의 줄은 엑셀로 내보내는 열이라 응답 행의 칸 전부가 아닐 수 있습니다.
- 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| options | array | 연금 전자통지 문서 행 배열 | |
| options[]. | string | number | boolean | object | array | null | 순번 | |
| options[]. | string | number | boolean | object | array | null | 문서번호 | |
| options[]. | string | number | boolean | object | array | null | 접수번호 | |
| options[]. | string | number | boolean | object | array | null | 통지문서 코드 | |
| options[]. | string | number | boolean | object | array | null | 통지문서명 | |
| options[]. | string | number | boolean | object | array | null | 송수신 구분 | |
| options[]. | string | number | boolean | object | array | null | 읽음상태 | |
| options[]. | string | number | boolean | object | array | null | 통지일시 | |
| options[]. | string | number | boolean | object | array | null | 최종전송일자 | |
| options[]. | string | 최종전송시각 | |
| options[]. | string | number | boolean | object | array | null | 거래일자 | |
| options[]. | string | number | boolean | object | array | null | 확인일자 | |
| options[]. | string | number | boolean | object | array | null | 자료 건수 | |
| options[]. | string | number | boolean | object | array | null | 검증번호 | |
| rows | array | 목록 행 배열 (options와 동일) | |
| row_ | number | 반환 행 수 | |
| source_ | number | 기관 응답 원본 행 수 | |
| workplace | object | 사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수) | |
| search | object | 이번 조회에 쓰인 조회 조건 | |
| page | object | 페이지 정보 | |
| template_ | array | 서식 선택지 | |
| read_ | array | 열람 상태 선택지 | |
| workflow_ | object | 연동 방식 정보 (전송 방식과 화면 호출 경로) |
// result.data
{
"page": {
"pageNo": "1",
"totRowCnt": "1",
"pagePerCnt": "10"
},
"rows": [
{
"brno": " ",
"rnum": "1",
"trDt": "20260513",
"delYn": "N",
"regYmd": "2026-05-13 13:24:52",
"gdbkTtl": " ",
"rcptnTm": "132452",
"dataNocs": "3",
"confirmDt": "20260518",
"rcptnNocs": "읽음",
"wediDocNo": "20260518-132452-836036",
"lastTrsmTm": "132452 ",
"tkcgBrofCd": "x",
"wediVrfcNo": "E4Mj",
"frstRegTmst": "2026-05-18 13:24:52",
"lastRegTmst": "2026-05-18 13:24:52",
"lastTrsmYmd": "20260518",
"wediSnrSeNm": "수신",
"wediTmpltCd": "ED33",
"wediTmpltNm": "기준소득월액 정기결정내용 사전 안내 통지서(2026.05월) ",
"frstRegBrofCd": "9999",
"lastRegBrofCd": "9999",
"regWediUserId": "user01",
"wediSnrSttsCd": "C",
"rcptnWediDocNo": "NPS12345678901234",
"frstRegWediUserId": "user01",
"lastRegWediUserId": "user01",
"wediTaskPrcsSttsCd": "W",
"wediCvlcptPrcsInstCd": "x"
}
],
"phase": "search",
"search": {
"page_no": 1,
"end_date": "20260604",
"start_date": "20260304",
"member_name": "",
"template_code": "ED33",
"page_per_count": 10,
"total_row_count": 1,
"read_status_code": "",
"row_text_contains": "",
"business_management_no": "12345678901",
"business_management_no_display": "123-45-67890-1"
},
"options": [
{
"raw": {
"brno": " ",
"rnum": "1",
"trDt": "20260513",
"delYn": "N",
"regYmd": "2026-05-13 13:24:52",
"gdbkTtl": " ",
"rcptnTm": "132452",
"dataNocs": "3",
"confirmDt": "20260518",
"rcptnNocs": "읽음",
"wediDocNo": "20260518-132452-836036",
"lastTrsmTm": "132452 ",
"tkcgBrofCd": "x",
"wediVrfcNo": "E4Mj",
"frstRegTmst": "2026-05-18 13:24:52",
"lastRegTmst": "2026-05-18 13:24:52",
"lastTrsmYmd": "20260518",
"wediSnrSeNm": "수신",
"wediTmpltCd": "ED33",
"wediTmpltNm": "기준소득월액 정기결정내용 사전 안내 통지서(2026.05월) ",
"frstRegBrofCd": "9999",
"lastRegBrofCd": "9999",
"regWediUserId": "user01",
"wediSnrSttsCd": "C",
"rcptnWediDocNo": "NPS12345678901234",
"frstRegWediUserId": "user01",
"lastRegWediUserId": "user01",
"wediTaskPrcsSttsCd": "W",
"wediCvlcptPrcsInstCd": "x"
},
"row_key": "20260518-132452-836036",
"direction": "수신",
"notice_at": "2026-05-13 13:24:52",
"row_index": 1,
"data_count": 3,
"receipt_no": "NPS12345678901234",
"document_no": "20260518-132452-836036",
"template_code": "ED33",
"template_name": "기준소득월액 정기결정내용 사전 안내 통지서(2026.05월) ",
"confirmed_date": "20260518",
"last_sent_date": "20260518",
"last_sent_time": "132452",
"verification_no": "E4Mj",
"read_status_code": "C",
"read_status_name": "읽음",
"transaction_date": "20260513",
"processing_status_code": "W"
}
],
"success": true,
"row_count": 1,
"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": "pension_notification_document_search",
"source_evidence": {
"documents": {
"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": [
"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": [
"...",
"..."
]
},
"template_codes": {
"url": "https://...",
"status_code": 200,
"wire_format": "...",
"content_type": "...",
"expected_datasets": [
"..."
],
"dataset_row_counts": {
"...": 27
},
"response_parameters": {
"ErrorCode": "..."
},
"transaction_contract": {
"tags": [
"...",
"..."
],
"endpoint": "...",
"page_per_count": 10,
"source_scripts": [
"https://..."
],
"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": [
"..."
]
}
},
"source_row_count": 1,
"template_options": [
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07010100",
"wediMenuNm": "(1) 건설일용직사업장 일괄경정내역 통지서",
"wediTmpltCd": "ED12"
},
"menu_id": "M07010100",
"source_path": "...",
"template_code": "ED12",
"template_name": "(1) 건설일용직사업장 일괄경정내역 통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07010200",
"wediMenuNm": "(2) 정기자료 확인대상자 통지서",
"wediTmpltCd": "ED16"
},
"menu_id": "M07010200",
"source_path": "...",
"template_code": "ED16",
"template_name": "(2) 정기자료 확인대상자 통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07010300",
"wediMenuNm": "(3) 소득총액신고 대상자 통지서",
"wediTmpltCd": "ED24"
},
"menu_id": "M07010300",
"source_path": "...",
"template_code": "ED24",
"template_name": "(3) 소득총액신고 대상자 통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07010400",
"wediMenuNm": "(4) 기준소득월액 정기결정 통지서",
"wediTmpltCd": "ED25"
},
"menu_id": "M07010400",
"source_path": "...",
"template_code": "ED25",
"template_name": "(4) 기준소득월액 정기결정 통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07010500",
"wediMenuNm": "(5) 기준소득월액 상(하)한액 조정대상자 통지서",
"wediTmpltCd": "ED28"
},
"menu_id": "M07010500",
"source_path": "...",
"template_code": "ED28",
"template_name": "(5) 기준소득월액 상(하)한액 조정대상자 통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07010600",
"wediMenuNm": "(6) 기준소득월액 소급정정 및 보험료 추가고지 대상자 통지서",
"wediTmpltCd": "ED26"
},
"menu_id": "M07010600",
"source_path": "...",
"template_code": "ED26",
"template_name": "(6) 기준소득월액 소급정정 및 보험료 추가고지 대상자 통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07010700",
"wediMenuNm": "(7) 기준소득월액 조정결정 통지서",
"wediTmpltCd": "ED90"
},
"menu_id": "M07010700",
"source_path": "...",
"template_code": "ED90",
"template_name": "(7) 기준소득월액 조정결정 통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07010800",
"wediMenuNm": "(8) 타 신고방법 or 지사 재 처리결과 통지서",
"wediTmpltCd": "ED30"
},
"menu_id": "M07010800",
"source_path": "...",
"template_code": "ED30",
"template_name": "(8) 타 신고방법 or 지사 재 처리결과 통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07010900",
"wediMenuNm": "(9) 과오납 충당 통지서",
"wediTmpltCd": "ED31"
},
"menu_id": "M07010900",
"source_path": "...",
"template_code": "ED31",
"template_name": "(9) 과오납 충당 통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07011100",
"wediMenuNm": "(10) 기준소득월액 정기결정내용 사전 안내 통지서",
"wediTmpltCd": "ED33"
},
"menu_id": "M07011100",
"source_path": "...",
"template_code": "ED33",
"template_name": "(10) 기준소득월액 정기결정내용 사전 안내 통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07011200",
"wediMenuNm": "(11) 취득(재개)시 기준소득월액 확인(정정)대상자 통지서",
"wediTmpltCd": "ED50"
},
"menu_id": "M07011200",
"source_path": "...",
"template_code": "ED50",
"template_name": "(11) 취득(재개)시 기준소득월액 확인(정정)대상자 통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07011300",
"wediMenuNm": "(12) 소급분 분할납부 대상 사업장 사전안내 통지서",
"wediTmpltCd": "EB1304"
},
"menu_id": "M07011300",
"source_path": "...",
"template_code": "EB1304",
"template_name": "(12) 소급분 분할납부 대상 사업장 사전안내 통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07011400",
"wediMenuNm": "(13) 개인사업장 사용자 기준소득월액 정기결정 통지서",
"wediTmpltCd": "ED40"
},
"menu_id": "M07011400",
"source_path": "...",
"template_code": "ED40",
"template_name": "(13) 개인사업장 사용자 기준소득월액 정기결정 통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07011500",
"wediMenuNm": "(14) 지사안내문",
"wediTmpltCd": "EED221"
},
"menu_id": "M07011500",
"source_path": "...",
"template_code": "EED221",
"template_name": "(14) 지사안내문"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07011600",
"wediMenuNm": "(15) 연금보험료 경정처리 결과통지서(지사)",
"wediTmpltCd": "ED13"
},
"menu_id": "M07011600",
"source_path": "...",
"template_code": "ED13",
"template_name": "(15) 연금보험료 경정처리 결과통지서(지사)"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07011800",
"wediMenuNm": "(16) 업무대행기관 통지서",
"wediTmpltCd": "ED18"
},
"menu_id": "M07011800",
"source_path": "...",
"template_code": "ED18",
"template_name": "(16) 업무대행기관 통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07011900",
"wediMenuNm": "(17) 업무대행위탁 통지서",
"wediTmpltCd": "ED19"
},
"menu_id": "M07011900",
"source_path": "...",
"template_code": "ED19",
"template_name": "(17) 업무대행위탁 통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07012000",
"wediMenuNm": "(18) 당월 취득자 중 취득월 미결정자",
"wediTmpltCd": "ED0802"
},
"menu_id": "M07012000",
"source_path": "...",
"template_code": "ED0802",
"template_name": "(18) 당월 취득자 중 취득월 미결정자"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07012100",
"wediMenuNm": "(19) 자격변동확인통지서",
"wediTmpltCd": "ED0803"
},
"menu_id": "M07012100",
"source_path": "...",
"template_code": "ED0803",
"template_name": "(19) 자격변동확인통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07012200",
"wediMenuNm": "(20) 연금보험료 결정금액변동통지서",
"wediTmpltCd": "ED0804"
},
"menu_id": "M07012200",
"source_path": "...",
"template_code": "ED0804",
"template_name": "(20) 연금보험료 결정금액변동통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07012300",
"wediMenuNm": "(21) 연금보험료지원결정통지서",
"wediTmpltCd": "ED0805"
},
"menu_id": "M07012300",
"source_path": "...",
"template_code": "ED0805",
"template_name": "(21) 연금보험료지원결정통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07012400",
"wediMenuNm": "(22) 연금보험료 지원제외 결정통지서",
"wediTmpltCd": "ED0806"
},
"menu_id": "M07012400",
"source_path": "...",
"template_code": "ED0806",
"template_name": "(22) 연금보험료 지원제외 결정통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07012500",
"wediMenuNm": "(23) 보험료지원환수금결정통지서",
"wediTmpltCd": "ED0807"
},
"menu_id": "M07012500",
"source_path": "...",
"template_code": "ED0807",
"template_name": "(23) 보험료지원환수금결정통지서"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07012600",
"wediMenuNm": "(24) 연금보험료 경정처리결과 (일반/건설)",
"wediTmpltCd": "EB12"
},
"menu_id": "M07012600",
"source_path": "...",
"template_code": "EB12",
"template_name": "(24) 연금보험료 경정처리결과 (일반/건설)"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07012700",
"wediMenuNm": "(25) 건설일용직사업장 경정처리결과",
"wediTmpltCd": "EB15"
},
"menu_id": "M07012700",
"source_path": "...",
"template_code": "EB15",
"template_name": "(25) 건설일용직사업장 경정처리결과"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07012800",
"wediMenuNm": "(26) 국민연금 보험료지원(두루누리) 신청 안내문",
"wediTmpltCd": "ED0808"
},
"menu_id": "M07012800",
"source_path": "...",
"template_code": "ED0808",
"template_name": "(26) 국민연금 보험료지원(두루누리) 신청 안내문"
},
{
"raw": {
"srcPath": "...",
"wediMenuId": "M07012900",
"wediMenuNm": "(27) 납부예외시 근로소득보유자 확인대상자",
"wediTmpltCd": "ED20"
},
"menu_id": "M07012900",
"source_path": "...",
"template_code": "ED20",
"template_name": "(27) 납부예외시 근로소득보유자 확인대상자"
}
],
"workflow_contract": {
"endpoints": {
"documents": "...",
"template_codes": "..."
},
"transport": "nexacro_xml_request_json_response",
"input_datasets": {
"documents": [
"...",
"...",
"..."
],
"template_codes": [
"...",
"..."
]
},
"response_datasets": {
"documents": [
"...",
"..."
],
"template_codes": [
"..."
]
}
},
"read_status_options": [
{
"source": "captured_screen_default",
"status_code": "",
"status_name": "전체"
},
{
"source": "main_dashboard_status_counts",
"status_code": "01",
"status_name": "읽지않음"
},
{
"source": "main_dashboard_status_counts",
"status_code": "05",
"status_name": "읽음"
},
{
"source": "main_dashboard_status_counts",
"status_code": "10",
"status_name": "전체(읽음+읽지않음)"
}
],
"implementation_status": null
}