연금고지

1. 국민연금 보험료 고지 목록 검색nps_edi.b1.pension_notices.search

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

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

국민연금 보험료 고지(결정) 목록을 검색합니다.

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

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_notices.search`이 API 고정값 (기본값) 예시 : nps_edi.b1.pension_notices.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
notice_year_month	string	6	N	고지 연월 입력 시 수신일 기준 검색창 자동 확장. 형식 오류 시 INVALID_NOTICE_YEAR_MONTH 형식 : YYYYMM
installment_round	string	-	N	고지 차수. 1=1차(ED02), 2=2차(ED08). 정수 · 문자열 모두 허용
template_code	string	-	N	고지 양식 코드 (예: ED02)
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_notices.search",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

options를 확인합니다.

순번	변수명	설명
	options	고지 목록 행 배열
	row_count	반환 행 수
	workplace	사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수)
	workflow_contract	연동 방식 정보 (전송 방식과 화면 호출 경로)

json

// result.data
{
  "options": [
    {
      "row_index": 0,
      "row_key": "..."
    }
  ],
  "row_count": 1,
  "workplace": {},
  "workflow_contract": {}
}

순번	오류 코드	발생 조건
	PROVIDER_VALIDATION_ERROR	형식 오류 — notice_year_month 는 YYYYMM 형식의 실제 연월이어야 하고, start_date 는 end_date 보다 늦을 수 없습니다.

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

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

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

검색된 고지 목록에서 1건을 선택해 세션에 저장합니다. 이후 보험료 상세 API에서 재사용됩니다.

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

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_notices.select`이 API 고정값 (기본값) 예시 : nps_edi.b1.pension_notices.select
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
row_key	string	-	N	search 결과 options[].row_key
notice_year_month	string	6	N	고지 연월 필터 형식 : YYYYMM
installment_round	string	-	N	고지 차수. 1=1차, 2=2차. 정수 · 문자열 모두 허용
template_code	string	-	N	고지 양식 코드 필터
row_text_contains	string	-	N	행 텍스트 부분 일치 필터
cell_text_contains	string	-	N	칸 하나 안의 텍스트 부분 일치 필터

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-select-001' \
  --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_option	선택된 고지 행 정보
	selection	선택 컨텍스트 (이후 상세 API에서 재사용)
	next_steps	다음 단계 힌트 배열

json

// result.data
{
  "selected_option": {},
  "selection": {},
  "next_steps": []
}

순번	오류 코드	발생 조건
	PROVIDER_VALIDATION_ERROR	후보 0건 — 조건에 맞는 행을 찾지 못했습니다.