개발자 문서
API 레퍼런스

신고·처리 - 국민연금공단 EDI

MCP 도구 이름 nps_edi__b1__declarations__processing_results__search

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

조회 기간과 신고 서식, 처리 상태를 넣으면 국민연금 EDI로 낸 신고마다 신고일자, 접수번호, 처리 상태, 보험별 확인 상태를 돌려줍니다. 조회 전용이며 신고 제출은 하지 않습니다.

  • 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [국민연금공단 EDI 로그인]
  • result.data.error_code=DECLARATION_PROCESSING_RESULTS_EMPTY.
  • 날짜 미입력 시 최근 90일. status_code·template_code에 A/ALL/전체는 전체 조회.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • nps_edi이 API 고정값 (기본값)

예시 : nps_edi

actionstring-Y호출할 작업입니다.
  • nps_edi.b1.declarations.processing_results.search이 API 고정값 (기본값)

예시 : nps_edi.b1.declarations.processing_results.search

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
start_datestring8N검색 시작일. 미입력 시 오늘 기준 90일 전

형식 : YYYYMMDD

end_datestring8N검색 종료일. 미입력 시 오늘

형식 : YYYYMMDD

status_codestring-N처리상태 wediSnrSttsCd. A·ALL·전체는 빈값(전체)
template_codestring-N신고 양식 코드. A·ALL·전체는 빈값(전체)
document_nostring-N전자문서번호 wediDocNo
row_text_containsstring-N행 텍스트 부분 일치 필터 (서버측 후처리)
page_nonumber-N페이지 번호. 기본 1
page_per_countnumber-N페이지당 행 수. 기본 5
output_formatsarray-N이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다
bash
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.declarations.processing_results.search",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • options·rows·template_options를 확인합니다.
  • 아래 표의 options[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 엑셀 파일 맨 윗줄의 머리글입니다.
  • 아래 표의 줄은 엑셀로 내보내는 열이라 응답 행의 칸 전부가 아닐 수 있습니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
optionsarray신고 처리결과 행 배열
options[].row_indexstring | number | boolean | object | array | null순번
options[].declaration_datestring | number | boolean | object | array | null신고일자
options[].receipt_nostring | number | boolean | object | array | null접수번호
options[].document_nostring | number | boolean | object | array | null문서번호
options[].template_codestring | number | boolean | object | array | null신고서 서식 코드
options[].template_namestring | number | boolean | object | array | null신고서명
options[].processing_status_namestring | number | boolean | object | array | null처리상태
options[].confirmation.national_pensionstring | number | boolean | object | array | null국민연금 확인
options[].confirmation.health_insurancestring | number | boolean | object | array | null건강보험 확인
options[].confirmation.employment_insurancestring | number | boolean | object | array | null고용보험 확인
options[].confirmation.industrial_accidentstring | number | boolean | object | array | null산재보험 확인
rowsarrayoptions 와 같은 처리결과 행의 기관 원본 (기관 열 이름 그대로)
template_optionsarray양식 코드·이름 옵션 배열
row_countnumber반환 행 수
source_row_countnumber기관 응답 원본 행 수
workplaceobject사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수)
searchobject이번 조회에 쓰인 조회 조건
pageobject페이지 정보
status_optionsarray처리상태 선택지
guide_rowsarray화면 안내 문구 행
workflow_contractobject연동 방식 정보 (전송 방식과 화면 호출 경로)
json
// result.data
{
  "options": [
    {
      "row_index": 1,
      "row_key": "...",
      "declaration_date": "20260901",
      "receipt_no": "...",
      "document_no": "...",
      "template_code": "AB01",
      "template_name": "사업장 내용변경신고",
      "processing_status_code": "정상",
      "processing_status_name": "정상",
      "confirmation": {
        "national_pension": "읽지않음",
        "health_insurance": "읽지않음",
        "employment_insurance": "읽지않음",
        "industrial_accident": "읽지않음"
      },
      "raw": {}
    }
  ],
  "rows": [
    { "rnum": "1", "wediDocNo": "...", "rcptnYmd": "20260901", "wediSnrSttsCd": "정상", "ntpsSttsCnt": "읽지않음" }
  ],
  "template_options": [],
  "row_count": 1,
  "source_row_count": 1,
  "workplace": {},
  "search": {},
  "page": {},
  "status_options": [],
  "guide_rows": [],
  "workflow_contract": {}
}