개발자 문서
API 레퍼런스

증명서 - 국민연금공단 EDI

1. 증명서 문서 뷰 파라미터 준비nps_edi.b1.certificates.application_results.document_view

MCP 도구 이름 nps_edi__b1__certificates__application_results__document_view

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

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

증명서 신청 처리결과 검색에서 고른 한 건을 넣으면 처리 상태와 열람 사전 확인 결과를, 상세 화면이 있는 증명서는 여는 값까지 돌려줍니다.

  • 증명서 신청 결과 목록을 먼저 조회하거나, 세션에 남아 있는 결과 행을 사용합니다. [국민연금공단 EDI 로그인]
  • select와 달리 첫 행 자동 선택 없음. selector 1개 이상으로 1건을 지정해야 합니다.

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.certificates.application_results.document_view이 API 고정값 (기본값)

예시 : nps_edi.b1.certificates.application_results.document_view

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
row_indexnumberNsearch options[].row_index
row_keystringNsearch options[].row_key
document_nostringN전자문서번호 docNo. 캐시 없을 때 template_code와 함께 search 자동 실행
receipt_nostringN접수 전자문서번호 rcvDocNo
template_codestringN양식 코드 필터 (예 EC02, EC15)
row_text_containsstringN행 텍스트 부분 일치 필터
run_precheckbooleanNgetOHJC0014M01 사전검증 호출. 기본 true
include_ec15_report_rowsbooleanNEC15일 때 getOHJC0020M0 read-only 행 포함. 인쇄 차단. 기본 false
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: document_view-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nps_edi",
  "action": "nps_edi.b1.certificates.application_results.document_view",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • view_action·detail_params를 확인합니다. error_code는 null.
순번변수명타입설명
view_actionobject문서 뷰 액션 코드
detail_paramsobject인쇄·저장용 상세 파라미터 객체
selected_optionobject선택한 처리결과 행 정보
documentobject선택 문서 정보 (문서번호, 접수번호, 서식 코드와 이름, 처리상태, 통지일시)
workplaceobject사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수)
precheckobject인쇄와 저장 전 사전 점검 결과
ec15_report_rowsarrayEC15 보고서 행
ec15_report_row_countnumberEC15 보고서 행 수
workflow_contractobject연동 방식 정보 (전송 방식과 화면 호출 경로)
json
// result.data
{
  "view_action": {},
  "detail_params": {},
  "selected_option": {},
  "document": {},
  "workplace": {},
  "precheck": {},
  "ec15_report_rows": [],
  "ec15_report_row_count": 1,
  "workflow_contract": {}
}
순번오류 코드발생 조건
PROVIDER_VALIDATION_ERROR행 없음 — 조건에 맞는 행을 찾지 못했습니다.

MCP 도구 이름 nps_edi__b1__certificates__application_results__search

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

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

접수 기간과 증명서 종류, 처리 상태를 넣으면 국민연금 증명서 신청 건마다 접수번호, 문서번호, 처리 상태를 돌려줍니다. 결과 행은 세션에 캐시되어 document_view에서 재사용됩니다.

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

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.certificates.application_results.search이 API 고정값 (기본값)

예시 : nps_edi.b1.certificates.application_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

template_codestring-N증명서 양식 코드. A·빈값=전체
member_namestring-N가입자(신청인) 성명 jnprNm
member_resident_nostring-N가입자 주민등록번호 jnprErrno
processing_status_codestring-N처리상태. A=전체, C=정상, S=오류
confirm_status_codestring-N확인상태 wediSnrSttsCd2
row_text_containsstring-N행 텍스트 부분 일치 필터 (서버측 후처리)
page_nonumber-N페이지 번호. 기본 1
page_per_countnumber-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: real_test' \
  --header "Idempotency-Key: search-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nps_edi",
  "action": "nps_edi.b1.certificates.application_results.search",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • options·rows를 확인합니다.
순번변수명타입설명
optionsarray증명서 신청결과 행 배열
rowsarray처리결과 행 배열 (options와 동일)
row_countnumber반환 행 수
source_row_countnumber기관 응답 원본 행 수
workplaceobject사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수)
searchobject이번 조회에 쓰인 조회 조건
pageobject페이지 정보
template_optionsarray증명서 서식 선택지
processing_status_optionsarray처리상태 선택지
workflow_contractobject연동 방식 정보 (전송 방식과 화면 호출 경로)
json
// result.data
{
  "page": {
    "jnprNm": "",
    "pageNo": "1",
    "rowCnt": "",
    "loginIp": "",
    "rcvEndDt": "20261003",
    "rowMsgId": "",
    "sortType": "",
    "jnprErrno": "",
    "sortColId": "",
    "totRowCnt": "1",
    "pagePerCnt": "10",
    "rcvStartDt": "20260705",
    "wediUserId": "user01",
    "wediTmpltCd": "A",
    "wediSnrSttsCd": "A",
    "wediSnrSttsCd2": ""
  },
  "rows": [
    {
      "fmCd": "EC02",
      "fmNm": "국민연금 가입자 가입증명(한글/영문) - 홍길동",
      "page": "1",
      "docNo": "20261003-131026-453756",
      "regYmd": "20261003131026",
      "dataNocs": "1",
      "rcvDocNo": "NPS12345678901234",
      "rcvNmbrNm": "읽지않음",
      "snrSttsCd": "C",
      "snrSttsNm": "정상",
      "frstRegTmst": "2026-10-03 13:10:26"
    }
  ],
  "phase": "search",
  "search": {
    "page_no": 1,
    "end_date": "20261003",
    "start_date": "20260705",
    "member_name": "",
    "template_code": "A",
    "page_per_count": 10,
    "total_row_count": 1,
    "row_text_contains": "",
    "confirm_status_code": "",
    "business_management_no": "12345678901",
    "processing_status_code": "A",
    "business_management_no_display": "123-45-67890-1"
  },
  "options": [
    {
      "raw": {
        "fmCd": "EC02",
        "fmNm": "국민연금 가입자 가입증명(한글/영문) - 홍길동",
        "page": "1",
        "docNo": "20261003-131026-453756",
        "regYmd": "20261003131026",
        "dataNocs": "1",
        "rcvDocNo": "NPS12345678901234",
        "rcvNmbrNm": "읽지않음",
        "snrSttsCd": "C",
        "snrSttsNm": "정상",
        "frstRegTmst": "2026-10-03 13:10:26"
      },
      "row_key": "20261003-131026-453756",
      "row_index": 1,
      "data_count": 1,
      "receipt_no": "NPS12345678901234",
      "document_no": "20261003-131026-453756",
      "template_code": "EC02",
      "template_name": "국민연금 가입자 가입증명(한글/영문) - 홍길동",
      "can_preview_report": false,
      "can_open_detail_menu": true,
      "notification_datetime": "2026-10-03 13:10:26",
      "processing_status_code": "C",
      "processing_status_name": "정상",
      "workplace_confirm_name": "읽지않음"
    }
  ],
  "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": "certificate_application_result_search",
  "source_evidence": {
    "results": {
      "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://...",
          "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": [
        "...",
        "..."
      ]
    }
  },
  "source_row_count": 1,
  "template_options": [
    {
      "template_code": "A",
      "template_name": "전체"
    },
    {
      "template_code": "EC02",
      "template_name": "국민연금 가입자 가입증명"
    },
    {
      "template_code": "EC06",
      "template_name": "국민연금 사업장 가입증명"
    },
    {
      "template_code": "EC07",
      "template_name": "사업장 국민연금보험료 월별 납부확인서"
    },
    {
      "template_code": "EC09",
      "template_name": "연금산정용 가입내역확인서"
    },
    {
      "template_code": "EC10",
      "template_name": "국민연금보험료 결정내역서"
    },
    {
      "template_code": "EC15",
      "template_name": "자격변동 확인통지서"
    },
    {
      "template_code": "EC16",
      "template_name": "국민연금 사업장가입자 명부"
    },
    {
      "template_code": "EC17",
      "template_name": "국민연금보험료 결정금액 변동통지서"
    },
    {
      "template_code": "EC18",
      "template_name": "퇴직전환금 부과내역서"
    },
    {
      "template_code": "EC19",
      "template_name": "사용자부담금 납부확인서"
    },
    {
      "template_code": "EC21",
      "template_name": "국민연금보험료 지원내역 사업장가입자별"
    },
    {
      "template_code": "EC22",
      "template_name": "국민연금보험료 지원내역 사업장월별"
    }
  ],
  "workflow_contract": {
    "endpoints": {
      "results": "...",
      "view_precheck": "...",
      "ec15_report_rows": "...",
      "blocked_print_or_save": [
        "...",
        "..."
      ]
    },
    "transport": "nexacro_xml_request_json_response",
    "input_datasets": {
      "results": [
        "...",
        "..."
      ],
      "view_precheck": [
        "..."
      ],
      "ec15_report_rows": [
        "...",
        "..."
      ]
    },
    "response_datasets": {
      "results": [
        "...",
        "..."
      ],
      "view_precheck": [
        "...",
        "..."
      ],
      "ec15_report_rows": [
        "..."
      ]
    }
  },
  "implementation_status": null,
  "processing_status_options": [
    {
      "source": "....default",
      "status_code": "A",
      "status_name": "전체"
    },
    {
      "source": "....screen",
      "status_code": "C",
      "status_name": "정상"
    },
    {
      "source": "....screen",
      "status_code": "S",
      "status_name": "오류"
    }
  ]
}

3. 가입증명 신청서 발송nps_edi.b1.certificates.membership.apply

MCP 도구 이름 nps_edi__b1__certificates__membership__apply

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

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

가입증명서를 발급하기 전에 대상 가입자 1명에서 100명의 가입증명 신청서를 기관에 보냅니다. 보낸 신청서는 취소할 수 없는 쓰기 액션입니다.

  • 로그인 뒤 같은 account_link_id 로 호출합니다. 대상자마다 성명(member_name)과 주민등록번호 13자리(rrno)를 보냅니다. 주민등록번호는 응답에 싣지 않습니다. [국민연금공단 EDI 로그인]
  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).

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.certificates.membership.apply이 API 고정값 (기본값)

예시 : nps_edi.b1.certificates.membership.apply

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

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

  • 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
순번변수명타입필수설명
subscribersarrayY신청 대상자 1~100명. 한 명이라도 가입 확인에 실패하면 신청서를 보내지 않는다
subscribers[].member_namestringY대상자 성명. 기관이 확인한 성명과 다르면 신청서를 보내지 않는다
subscribers[].rrnostringY대상자 주민등록번호(외국인등록번호) 13자리. 하이픈을 넣어도 된다. 응답과 증적에는 싣지 않는다
confirmation_tokenstringN1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: apply-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nps_edi",
  "action": "nps_edi.b1.certificates.membership.apply",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "subscribers": [
      {
        "member_name": "<필수>",
        "rrno": "<필수>"
      }
    ]
  }
}'

Response

  • result.rspnsRsltCd 가 S 또는 B 이면 접수입니다. applicants 에 확인된 성명과 취득일이 실립니다. 이어서 가입자 목록 조회 → 가입증명서 발급 순서로 호출합니다.
순번변수명타입설명
outcomestring기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다
actionstring요청한 액션 이름
template_codestring증명서 서식 코드 (EC02 가입자 가입증명)
doc_typestring신청서 서식 코드 (EB0301)
message_ctrl_idstring이번 신청서의 전송 관리 번호
applicant_countnumber신청한 대상자 수
applicantsarray확인된 대상자 배열 (순번, 성명, 취득일). 주민등록번호는 싣지 않습니다
resultobject접수 결과 (응답 코드 rspnsRsltCd, 응답 문장, 상태, 오류 코드와 문장)
workplaceobject사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수)
workflow_contractobject연동 방식 정보 (전송 방식과 화면 호출 경로)
messagestring | null접수를 확인하지 못했을 때의 안내 문장 (정상이면 null)
json
// result.data
{
  "success": true,
  "outcome": "confirmed",
  "action": "nps_edi.b1.certificates.membership.apply",
  "template_code": "EC02",
  "doc_type": "EB0301",
  "message_ctrl_id": "EB0301...",
  "applicant_count": 1,
  "applicants": [
    {
      "index": 1,
      "member_name": "...",
      "acquired_at": "..."
    }
  ],
  "result": {
    "rspnsRsltCd": "S"
  },
  "workplace": {},
  "workflow_contract": {},
  "message": null
}
순번오류 코드발생 조건
VALIDATION_INVALID_FIELD대상자 누락 — subscribers 를 보내지 않았습니다.
VALIDATION_INVALID_FIELD대상자 입력 오류 — 대상자가 비었거나 100명을 넘었거나, 성명이 비었거나, 주민등록번호가 13자리가 아니거나, 같은 번호가 두 번 들어 있습니다. 신청서는 보내지 않습니다.
PROVIDER_VALIDATION_ERROR가입 확인 실패 — 한 명이라도 가입 정보를 조회하지 못했거나, 성명이 일치하지 않거나, 가입 내역이 없으면 신청서를 보내지 않습니다. 메시지가 몇 번째 대상자인지 알려 줍니다.
PROVIDER_BUSINESS_ERROR접수 거절 — 신청서가 접수되지 않았습니다. 응답 사유가 메시지에 함께 실립니다. 잠시 후 다시 신청합니다.
PROVIDER_OUTCOME_UNCONFIRMED결과 확인 불가 — 신청서는 보냈지만 접수 여부를 확인하지 못했습니다. 다시 신청하지 말고 증명서 신청 처리결과 조회에서 목록을 먼저 확인합니다.
POLICY_FEATURE_DISABLED기능 꺼짐 — 지금은 신청서를 보낼 수 없습니다. 가입자 목록 조회와 처리결과 조회는 그대로 쓸 수 있습니다.

4. 가입증명서 발급nps_edi.b1.certificates.membership.issue

MCP 도구 이름 nps_edi__b1__certificates__membership__issue

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

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

선택한 가입자의 국민연금 가입증명서를 한글로 발급합니다. 발급 이력이 남고 취소할 수 없는 쓰기 액션입니다.

  • 가입증명 신청서가 접수된 뒤, 가입자 목록 조회로 대상을 고르고 같은 account_link_id 로 호출합니다. [국민연금공단 EDI 로그인]
  • 요청 거절(HTTP 400, 작업은 만들어지지 않음).
  • 요청 거절(HTTP 409, 작업은 만들어지지 않음).

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.certificates.membership.issue이 API 고정값 (기본값)

예시 : nps_edi.b1.certificates.membership.issue

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

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 row_index, row_key 또는 member_name 중 하나 이상을 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
row_indexnumber조건부가입자 목록 조회 결과 options[].row_index
row_keystring조건부가입자 목록 조회 결과 options[].row_key
member_namestring조건부가입자 성명. 동명이인이면 row_index 나 row_key 로 한 명을 지정
languagestringN증명서 언어. ko 한글. 기본 ko
confirmation_tokenstringN1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: issue-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nps_edi",
  "action": "nps_edi.b1.certificates.membership.issue",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "row_index": "<필수: number>"
  }
}'

Response

  • issued_document.doc_no 에 새 문서번호가 실립니다. 증명서 신청 처리결과 조회와 문서 보기로 이어서 확인합니다.
순번변수명타입설명
outcomestring기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다
actionstring요청한 액션 이름
template_codestring증명서 서식 코드 (EC02 가입자 가입증명)
languagestring발급 언어 (ko 한글)
subscriberobject발급 대상 가입자 행 (row_index, row_key, 성명과 영문 성명, 가입일, 처리일, 신청 문서번호)
issued_documentobject발급된 증명서 (문서번호 doc_no, 서식 코드)
gap_checkobject24시간 발급 제한 검사 결과 (가능 여부, 상태, 건수)
report_dataset_namesarray증명서 생성 응답에 들어 있던 데이터 묶음 이름
report_response_shapeobject증명서 생성 응답의 모양 (kind 는 pdf, json, other 중 하나이고 content_type, size_bytes, sha256 등이 함께 실립니다). 본문은 싣지 않습니다
new_result_doc_nosarray발급 뒤 처리결과 목록에 새로 생긴 문서번호
workplaceobject사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수)
workflow_contractobject연동 방식 정보 (전송 방식과 화면 호출 경로)
messagestring | null발급을 확인하지 못했을 때의 안내 문장 (정상이면 null)
json
// result.data
{
  "success": true,
  "outcome": "confirmed",
  "action": "nps_edi.b1.certificates.membership.issue",
  "template_code": "EC02",
  "language": "ko",
  "subscriber": {
    "row_index": 1,
    "row_key": "...",
    "member_name": "..."
  },
  "issued_document": {
    "doc_no": "...",
    "template_code": "EC02"
  },
  "gap_check": {
    "one_day_flag": "Y"
  },
  "report_dataset_names": [],
  "report_response_shape": {},
  "new_result_doc_nos": [],
  "workplace": {},
  "workflow_contract": {},
  "message": null
}
순번오류 코드발생 조건
VALIDATION_INVALID_FIELD가입자 지정 오류 — row_index · row_key · member_name 중 하나로 가입자를 지정하지 않았거나, 같은 성명이 여러 명이거나, language 가 ko · en 이 아닙니다.
RESOURCE_NOT_FOUND가입자 없음 — 지정한 가입자가 목록에 없습니다. 가입자 목록 조회를 다시 실행해 확인합니다.
PROVIDER_PREREQUISITE_REQUIRED신청 내역 없음 — 가입증명 신청 내역이 없습니다. 가입증명 신청서 발송을 먼저 호출합니다.
PROVIDER_VALIDATION_ERROR24시간 제한 — 발급한 지 24시간이 지난 가입증명이라 기관이 다시 출력하지 못하게 막았습니다. error.message 는 기관 문장 뒤에 「가입증명 신청서를 새로 보낸 뒤 발급해 주세요.」 가 붙은 문장입니다. 가입증명 신청서 발송부터 다시 호출한 뒤 발급합니다.
PROVIDER_OUTCOME_UNCONFIRMED결과 확인 불가 — 발급 요청은 보냈지만 새 문서번호를 확인하지 못했습니다. 이미 발급됐을 수 있어 다시 발급하지 않습니다. error.message 끝에 「가입증명 발급은 증명서 신청 처리결과 목록에 새 줄로 남지 않아 그 목록으로는 발급 여부를 확인할 수 없습니다.」 가 붙습니다.
POLICY_FEATURE_DISABLED기능 꺼짐 — 지금은 발급할 수 없습니다. 가입자 목록 조회와 처리결과 조회는 그대로 쓸 수 있습니다.

MCP 도구 이름 nps_edi__b1__certificates__membership__subscribers__search

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

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

가입증명 신청서를 보낸 가장 최근 건에 딸린 가입자를 이름으로 찾아 성명, 가입 기간 표시와 행 번호, 행 키를 돌려줍니다. 결과 행은 세션에 남아 가입증명서 발급에서 다시 씁니다.

  • 로그인 뒤 같은 account_link_id 로 호출합니다. 가입증명 신청서가 먼저 접수되어 있어야 합니다 - 가장 최근 가입증명 신청 아래의 가입자를 보여 줍니다. [국민연금공단 EDI 로그인]
  • 작업은 성공으로 끝나고 row_count=0, options 는 빈 배열입니다.
  • search_text 를 비우면 전체 가입자를 조회합니다. page_no 기본 1, page_per_count 기본 10.

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.certificates.membership.subscribers.search이 API 고정값 (기본값)

예시 : nps_edi.b1.certificates.membership.subscribers.search

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
search_textstringN가입자 검색어 srchData(성명 등). 미입력 시 전체
page_nonumberN페이지 번호. 기본 1
page_per_countnumberN페이지당 행 수. 기본 10
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.certificates.membership.subscribers.search",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • options 의 row_index · row_key · member_name 으로 발급할 가입자를 고릅니다.
순번변수명타입설명
template_codestring증명서 서식 코드 (EC02 가입자 가입증명)
row_countnumber반환 행 수
optionsarray가입자 행 배열 (row_index, row_key, 성명과 영문 성명, 가입일, 처리일, 신청 문서번호, raw). 주민등록번호는 싣지 않습니다
workplaceobject사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수)
searchobject이번 조회에 쓰인 조회 조건 (검색어, 페이지)
workflow_contractobject연동 방식 정보 (전송 방식과 화면 호출 경로)
json
// result.data
{
  "success": true,
  "template_code": "EC02",
  "row_count": 1,
  "options": [
    {
      "row_index": 1,
      "row_key": "...",
      "member_name": "..."
    }
  ],
  "workplace": {},
  "search": {
    "search_text": "",
    "page_no": 1,
    "page_per_count": 10
  },
  "workflow_contract": {}
}
순번오류 코드발생 조건
PROVIDER_PREREQUISITE_REQUIRED신청 내역 없음 — 가입증명 신청 내역이 없습니다. 가입증명 신청서 발송을 먼저 호출합니다.