연금통지

1. 연금 통지문서 상세 조회nps_edi.b1.pension_notification_documents.detail

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

통지문서 1건의 상세 본문·멤버 목록을 조회합니다. ED33 양식만 지원합니다.

목록 조회로 행을 찾거나, document_no 로 문서를 직접 지정합니다. [국민연금공단 EDI 로그인]
result.data.error_code=PENSION_NOTIFICATION_DOCUMENT_DETAIL_EMPTY.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `nps_edi`이 API 고정값 (기본값) 예시 : nps_edi
action	string	-	Y	호출할 작업입니다. `nps_edi.b1.pension_notification_documents.detail`이 API 고정값 (기본값) 예시 : nps_edi.b1.pension_notification_documents.detail
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	필수	설명
row_index	number	N	search 결과 options[].row_index. search 선행 또는 동일 세션 내 search 직후
row_key	string	N	search 결과 options[].row_key (wediDocNo 등)
document_no	string	N	전자문서번호 wediDocNo
receipt_no	string	N	접수 전자문서번호 rcptnWediDocNo
template_code	string	N	양식 코드. 상세 조회는 ED33만 지원 (그 외 UNSUPPORTED_PENSION_NOTIFICATION_TEMPLATE)
row_text_contains	string	N	행 텍스트 부분 일치 필터
member_name	string	N	상세 멤버 검색용 성명
member_resident_no	string	N	상세 멤버 검색용 주민등록번호
search_type_code	string	N	상세 멤버 검색 유형 코드
page_no	number	N	멤버 목록 페이지. 기본 1
page_per_count	number	N	멤버 목록 페이지당 행 수. 기본 10
mark_as_read	boolean	N	조회 시 읽음 처리. 기본 true
include_export_rows	boolean	N	export_rows 포함. 기본 true
include_guide	boolean	N	guide_rows 포함. 기본 true

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-detail-001' \
  --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	통지문서 메타정보 객체
	members	대상 멤버 목록 배열
	rows	상세 행 배열
	selected_option	선택한 통지문서 행 정보
	workplace	사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수)
	search	이번 조회에 쓰인 조회 조건 (문서번호, 접수번호, 서식)
	summary	대상자 요약 (인원수, 소득 합계, 결정 기준소득월액과 월 보험료 합계)
	row_count	대상자 행 수
	page	페이지 정보
	export_rows	내보내기용 행
	export_row_count	내보내기용 행 수
	guide_rows	화면 안내 문구 행
	read_update	열람 처리 결과
	workflow_contract	연동 방식 정보 (전송 방식과 화면 호출 경로)

json

// result.data
{
  "document": {},
  "members": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "rows": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "selected_option": {},
  "workplace": {},
  "search": {},
  "summary": {},
  "row_count": 1,
  "page": {},
  "export_rows": [],
  "export_row_count": 1,
  "guide_rows": [],
  "read_update": {},
  "workflow_contract": {}
}

순번	오류 코드	발생 조건
	PROVIDER_VALIDATION_ERROR	양식·행 오류 — 지원하지 않는 통지서 양식이거나, 조건에 맞는 행을 찾지 못했습니다.

2. 연금 통지문서 목록 검색nps_edi.b1.pension_notification_documents.search

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

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

연금 전자 통지 문서 목록을 검색합니다.

로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [국민연금공단 EDI 로그인]
result.data.error_code=PENSION_NOTIFICATION_DOCUMENTS_EMPTY.
날짜 미입력 시 최근 90일.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `nps_edi`이 API 고정값 (기본값) 예시 : nps_edi
action	string	-	Y	호출할 작업입니다. `nps_edi.b1.pension_notification_documents.search`이 API 고정값 (기본값) 예시 : nps_edi.b1.pension_notification_documents.search
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	길이	필수	설명
start_date	string	8	N	검색 시작일 미입력 시 오늘 기준 90일 전 형식 : YYYYMMDD
end_date	string	8	N	검색 종료일 미입력 시 오늘 형식 : YYYYMMDD
template_code	string	-	N	통지문서 양식 코드. A·ALL·전체는 전체 조회로 처리
member_name	string	-	N	가입자 성명
member_resident_no	string	-	N	가입자 주민등록번호
read_status_code	string	-	N	열람 상태. 01=읽지않음, 05=읽음, 10=전체(읽음+읽지않음), 빈값=전체
row_text_contains	string	-	N	행 텍스트 부분 일치 필터 (서버측 후처리)
page_no	number	-	N	페이지 번호. 기본 1
page_per_count	number	-	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: sandbox' \
  --header 'Idempotency-Key: demo-search-001' \
  --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	연금 전자통지 문서 행 배열
	rows	목록 행 배열 (options와 동일)
	row_count	반환 행 수
	source_row_count	기관 응답 원본 행 수
	workplace	사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수)
	search	이번 조회에 쓰인 조회 조건
	page	페이지 정보
	template_options	서식 선택지
	read_status_options	열람 상태 선택지
	workflow_contract	연동 방식 정보 (전송 방식과 화면 호출 경로)

json

// result.data
{
  "options": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "rows": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "row_count": 1,
  "source_row_count": 1,
  "workplace": {},
  "search": {},
  "page": {},
  "template_options": [],
  "read_status_options": [],
  "workflow_contract": {}
}