연금보험료 - 국민연금공단 EDI
1. 국민연금 결정내역 안내 문구nps_ edi. b1. national_ pension_ premiums. guide
MCP 도구 이름 nps_
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
고지나 기간을 고르지 않고 부르면 국민연금보험료 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
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| 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 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
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를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| rows | array | 안내·도움말 텍스트 행 배열 |
// 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 로그인]
- 기관이 데이터셋을 주었는데 납부 이력 행이 비면 success=true, error_code=null, implementation_status=pension_payment_history_empty.
- 기관이 데이터셋을 하나도 주지 않으면 success=false, error_code=null, implementation_status=pension_payment_history_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 | - | 조건부 | 작업 파라미터입니다. 아래 params 파라미터 표의 row_index, row_key, notice_year_month, installment_round, template_code, row_text_contains 또는 cell_text_contains 중 하나 이상을 보냅니다. 앞 단계에서 고른 항목이 같은 연동 계정의 세션에 남아 있으면 빈 객체로 보내 그 항목을 씁니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| row_ | number | - | 조건부 | search/select 결과 options[].row_index. 지정 시 세션 cached selected_notice 재선택 | |
| row_ | string | - | 조건부 | search/select 결과 options[].row_key | |
| notice_ | string | 6 | 조건부 | 고지 연월. cached selected_notice와 불일치 시 재선택 | |
| installment_ | string | - | 조건부 | 고지 차수. 1=1차(ED02), 2=2차(ED08). 정수 · 문자열 모두 허용 | |
| template_ | string | - | 조건부 | 고지 양식 코드 (예: ED02) | |
| row_ | string | - | 조건부 | 행 텍스트 부분 일치 필터 | |
| cell_ | string | - | 조건부 | 칸 하나 안의 텍스트 부분 일치 필터 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| rows | array | 납부·징수 이력 행 배열. 서버가 페이지를 끝까지 읽어 모든 페이지의 행을 싣습니다 | |
| page | object | 첫 페이지의 페이지 정보 객체 | |
| workplace | object | 사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수) | |
| notice | object | 선택한 고지 정보 (귀속 연월, 회차, 서식, 문서번호, 접수일) | |
| row_ | object | 전체 행 수신 범위 (total_row_count, received_row_count, pages_read, complete, stop_reason). complete 가 false 면 행이 더 있을 수 있습니다 |
// result.data
{
"rows": [],
"page": {},
"workplace": {},
"notice": {},
"row_coverage": {}
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 선택 오류 — 고지 내역을 먼저 선택(select)해야 하거나, 조건에 맞는 행을 찾지 못했습니다. |
3. 국민연금 소급분 내역nps_ edi. b1. national_ pension_ premiums. retro_ payments
MCP 도구 이름 nps_
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
고지 연월과 차수 같은 값으로 고른 고지에 소급분 내역이 있으면 기관이 준 줄을 돌려줍니다.
- 요약 조회와 선행 조건이 같습니다. 대상을 먼저 선택하거나 선택 조건을 함께 보냅니다. [국민연금공단 EDI 로그인]
- 기관이 데이터셋을 주었는데 소급분 행이 비면 success=true, error_code=null, implementation_status=pension_retro_payments_empty.
- 기관이 데이터셋을 하나도 주지 않으면 success=false, error_code=null, implementation_status=pension_retro_payments_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 | - | 조건부 | 작업 파라미터입니다. 아래 params 파라미터 표의 row_index, row_key, notice_year_month, installment_round, template_code, row_text_contains 또는 cell_text_contains 중 하나 이상을 보냅니다. 앞 단계에서 고른 항목이 같은 연동 계정의 세션에 남아 있으면 빈 객체로 보내 그 항목을 씁니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| row_ | number | - | 조건부 | search/select 결과 options[].row_index. 지정 시 세션 cached selected_notice 재선택 | |
| row_ | string | - | 조건부 | search/select 결과 options[].row_key | |
| notice_ | string | 6 | 조건부 | 고지 연월. cached selected_notice와 불일치 시 재선택 | |
| installment_ | string | - | 조건부 | 고지 차수. 1=1차(ED02), 2=2차(ED08). 정수 · 문자열 모두 허용 | |
| template_ | string | - | 조건부 | 고지 양식 코드 (예: ED02) | |
| row_ | string | - | 조건부 | 행 텍스트 부분 일치 필터 | |
| cell_ | string | - | 조건부 | 칸 하나 안의 텍스트 부분 일치 필터 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| rows | array | 소급분 행 배열. 서버가 페이지를 끝까지 읽어 모든 페이지의 행을 싣습니다 | |
| page | object | 첫 페이지의 페이지 정보 객체 | |
| workplace | object | 사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수) | |
| notice | object | 선택한 고지 정보 (귀속 연월, 회차, 서식, 문서번호, 접수일) | |
| row_ | object | 전체 행 수신 범위 (total_row_count, received_row_count, pages_read, complete, stop_reason). complete 가 false 면 행이 더 있을 수 있습니다 |
// result.data
{
"rows": [],
"page": {},
"workplace": {},
"notice": {},
"row_coverage": {}
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 선택 오류 — 고지 내역을 먼저 선택(select)해야 하거나, 조건에 맞는 행을 찾지 못했습니다. |
4. 국민연금 가입자별 보험료 내역nps_ edi. b1. national_ pension_ premiums. subscribers
MCP 도구 이름 nps_
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
고지 연월과 차수로 고른 고지의 가입자별 기준소득월액과 연금보험료, 부담금을 줄마다 돌려주고 받은 줄의 가입자 수와 합계도 줍니다.
- 요약 조회와 선행 조건이 같습니다. 대상을 먼저 선택하거나 선택 조건을 함께 보냅니다. [국민연금공단 EDI 로그인]
- 기관이 데이터셋을 주었는데 가입자 행이 비면 success=true, error_code=null, implementation_status=pension_subscriber_dataset_empty.
- 기관이 데이터셋을 하나도 주지 않으면 success=false, error_code=null, implementation_status=pension_subscriber_dataset_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 | - | 조건부 | 작업 파라미터입니다. 아래 params 파라미터 표의 row_index, row_key, notice_year_month, installment_round, template_code, row_text_contains 또는 cell_text_contains 중 하나 이상을 보냅니다. 앞 단계에서 고른 항목이 같은 연동 계정의 세션에 남아 있으면 빈 객체로 보내 그 항목을 씁니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| row_ | number | - | 조건부 | search/select 결과 options[].row_index. 지정 시 세션 cached selected_notice 재선택 | |
| row_ | string | - | 조건부 | search/select 결과 options[].row_key | |
| notice_ | string | 6 | 조건부 | 고지 연월. cached selected_notice와 불일치 시 재선택 | |
| installment_ | string | - | 조건부 | 고지 차수. 1=1차(ED02), 2=2차(ED08). 정수 · 문자열 모두 허용 | |
| template_ | string | - | 조건부 | 고지 양식 코드 (예: ED02) | |
| row_ | string | - | 조건부 | 행 텍스트 부분 일치 필터 | |
| cell_ | string | - | 조건부 | 칸 하나 안의 텍스트 부분 일치 필터 | |
| 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: 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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| members | array | 가입자별 보험료 내역 배열 | |
| members[]. | string | number | boolean | object | array | null | 순번 | |
| members[]. | string | number | boolean | object | array | null | 가입자명 | |
| members[]. | string | number | boolean | object | array | null | 기준소득월액 | |
| members[]. | string | number | boolean | object | array | null | 연금보험료 | |
| members[]. | string | number | boolean | object | array | null | 가입자 부담금 | |
| members[]. | string | number | boolean | object | array | null | 사용자 부담금 | |
| members[]. | string | number | boolean | object | array | null | 지원 후 가입자 부담금 | |
| members[]. | string | number | boolean | object | array | null | 지원 후 사용자 부담금 | |
| workplace | object | 사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수) | |
| notice | object | 선택한 고지 정보 (귀속 연월, 회차, 서식, 문서번호, 접수일) | |
| summary | object | 가입자 합계 (인원수, 기준소득월액, 연금보험료, 근로자와 사업주 부담금). 모든 페이지의 가입자로 계산합니다 | |
| row_ | object | 전체 행 수신 범위 (total_row_count, received_row_count, pages_read, complete, stop_reason). 서버가 페이지를 끝까지 읽어 members 에 모두 싣고, complete 가 false 면 가입자가 더 있을 수 있습니다 |
// 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_ | 선택 오류 — 고지 내역을 먼저 선택(select)해야 하거나, 조건에 맞는 행을 찾지 못했습니다. |
5. 국민연금 보험료 결정 요약nps_ edi. b1. national_ pension_ premiums. summary
MCP 도구 이름 nps_
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
고지 연월과 차수로 고른 고지의 보험료 결정 요약을 한 건으로 돌려줍니다.
- 고지 선택을 먼저 호출하거나, 선택 조건으로 고지를 지정합니다. [국민연금공단 EDI 로그인]
- 기관이 데이터셋을 주었는데 요약 행이 비면 success=true, error_code=null, implementation_status=pension_summary_dataset_empty.
- 기관이 데이터셋을 하나도 주지 않으면 success=false, error_code=null, implementation_status=pension_summary_dataset_empty.
- 선택을 먼저 하면 params 를 빈 객체로 보낼 수 있습니다.선택 칸(row_text_contains 와 cell_text_contains 포함)을 보내면 앞서 고른 고지가 그 칸에 맞을 때는 그대로 쓰고, 맞지 않으면 그 칸에 맞는 고지를 다시 고릅니다.
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 | - | 조건부 | 작업 파라미터입니다. 아래 params 파라미터 표의 row_index, row_key, notice_year_month, installment_round, template_code, row_text_contains 또는 cell_text_contains 중 하나 이상을 보냅니다. 앞 단계에서 고른 항목이 같은 연동 계정의 세션에 남아 있으면 빈 객체로 보내 그 항목을 씁니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| row_ | number | - | 조건부 | search/select 결과 options[].row_index. 지정 시 세션 cached selected_notice 재선택 | |
| row_ | string | - | 조건부 | search/select 결과 options[].row_key | |
| notice_ | string | 6 | 조건부 | 고지 연월. cached selected_notice와 불일치 시 재선택 | |
| installment_ | string | - | 조건부 | 고지 차수. 1=1차(ED02), 2=2차(ED08). 정수 · 문자열 모두 허용 | |
| template_ | string | - | 조건부 | 고지 양식 코드 (예: ED02) | |
| row_ | string | - | 조건부 | 행 텍스트 부분 일치 필터 | |
| cell_ | string | - | 조건부 | 칸 하나 안의 텍스트 부분 일치 필터 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| summary | object | 고지 결정 요약 객체 | |
| notice | object | 고지 기본정보 객체 | |
| workplace | object | 사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수) | |
| selected_ | object | 선택한 고지 행 정보 (문서번호, 서식, 귀속 연월, 회차, 접수일) |
// result.data
{
"summary": {},
"notice": {},
"workplace": {},
"selected_option": {}
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 선택 오류 — 고지 내역을 먼저 선택(select)해야 하거나, 조건에 맞는 행을 찾지 못했습니다. |
6. 국민연금 지원금과 보조 내역nps_ edi. b1. national_ pension_ premiums. support_ details
MCP 도구 이름 nps_
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
고지 연월과 차수를 넣거나 앞서 고른 고지가 있으면, 그 고지의 가입자 목록과 지원내역 목록, 지원금액 합계를 돌려줍니다.
- 요약 조회와 선행 조건이 같습니다. 대상을 먼저 선택하거나 선택 조건을 함께 보냅니다. [국민연금공단 EDI 로그인]
- 기관이 데이터셋을 주었는데 가입자 행과 지원 상세 행이 비면 success=true, error_code=null, implementation_status=pension_support_dataset_empty.
- 기관이 데이터셋을 하나도 주지 않으면 success=false, error_code=null, implementation_status=pension_support_dataset_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 | - | 조건부 | 작업 파라미터입니다. 아래 params 파라미터 표의 row_index, row_key, notice_year_month, installment_round, template_code, row_text_contains 또는 cell_text_contains 중 하나 이상을 보냅니다. 앞 단계에서 고른 항목이 같은 연동 계정의 세션에 남아 있으면 빈 객체로 보내 그 항목을 씁니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| row_ | number | - | 조건부 | search/select 결과 options[].row_index. 지정 시 세션 cached selected_notice 재선택 | |
| row_ | string | - | 조건부 | search/select 결과 options[].row_key | |
| notice_ | string | 6 | 조건부 | 고지 연월. cached selected_notice와 불일치 시 재선택 | |
| installment_ | string | - | 조건부 | 고지 차수. 1=1차(ED02), 2=2차(ED08). 정수 · 문자열 모두 허용 | |
| template_ | string | - | 조건부 | 고지 양식 코드 (예: ED02) | |
| row_ | string | - | 조건부 | 행 텍스트 부분 일치 필터 | |
| cell_ | string | - | 조건부 | 칸 하나 안의 텍스트 부분 일치 필터 | |
| 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: 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 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.예시 값의 타입으로 단정하지 말고 실제 값의 타입을 확인해 주세요. null은 값이 비어 있다는 뜻이며, 필드 자체의 생략 여부는 필수 여부와 설명을 확인해 주세요.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| members | array | 가입자 목록 배열 (가입자별 보험료 내역과 같은 칸) | |
| members[]. | string | number | boolean | object | array | null | 순번 | |
| members[]. | string | number | boolean | object | array | null | 가입자명 | |
| members[]. | string | number | boolean | object | array | null | 기준소득월액 | |
| members[]. | string | number | boolean | object | array | null | 연금보험료 | |
| members[]. | string | number | boolean | object | array | null | 가입자 부담금 | |
| members[]. | string | number | boolean | object | array | null | 사용자 부담금 | |
| members[]. | string | number | boolean | object | array | null | 지원 후 가입자 부담금 | |
| members[]. | string | number | boolean | object | array | null | 지원 후 사용자 부담금 | |
| support_ | array | 지원내역 목록 배열 (가입자별 결정년월, 지원금액, 지원율) | |
| support_ | string | number | boolean | object | array | null | 순번 | |
| support_ | string | number | boolean | object | array | null | 가입자명 | |
| support_ | string | number | boolean | object | array | null | 결정년월 | |
| support_ | string | number | boolean | object | array | null | 연금보험료 | |
| support_ | string | number | boolean | object | array | null | 지원금액 | |
| support_ | string | number | boolean | object | array | null | 지원율 | |
| support_ | string | number | boolean | object | array | null | 예정 사용자 부담금 | |
| support_ | string | number | boolean | object | array | null | 예정 가입자 부담금 | |
| workplace | object | 사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수) | |
| notice | object | 선택한 고지 정보 (귀속 연월, 회차, 서식, 문서번호, 접수일) | |
| summary | object | 지원 요약 (가입자 수, 지원 내역 수, 지원금 합계) |
// 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_ | 선택 오류 — 고지 내역을 먼저 선택(select)해야 하거나, 조건에 맞는 행을 찾지 못했습니다. |