증명서 - 국민연금공단 EDI
1. 증명서 문서 뷰 파라미터 준비nps_ edi. b1. certificates. application_ results. document_ view
MCP 도구 이름 nps_
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
증명서 신청 처리결과 검색에서 고른 한 건을 넣으면 처리 상태와 열람 사전 확인 결과를, 상세 화면이 있는 증명서는 여는 값까지 돌려줍니다.실제 인쇄 API는 호출하지 않습니다(read-only).
- 증명서 신청 결과 목록을 먼저 조회하거나, 세션에 남아 있는 결과 행을 사용합니다. [국민연금공단 EDI 로그인]
- select와 달리 첫 행 자동 선택 없음. selector 1개 이상으로 1건을 지정해야 합니다.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| row_ | number | N | search options[].row_index | |
| row_ | string | N | search options[].row_key | |
| document_ | string | N | 전자문서번호 docNo. 캐시 없을 때 template_code와 함께 search 자동 실행 | |
| receipt_ | string | N | 접수 전자문서번호 rcvDocNo | |
| template_ | string | N | 양식 코드 필터 (예 EC02, EC15) | |
| row_ | string | N | 행 텍스트 부분 일치 필터 | |
| run_ | boolean | N | getOHJC0014M01 사전검증 호출. 기본 true | |
| include_ | boolean | N | EC15일 때 getOHJC0020M0 read-only 행 포함. 인쇄 차단. 기본 false |
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_ | object | 문서 뷰 액션 코드 | |
| detail_ | object | 인쇄·저장용 상세 파라미터 객체 | |
| selected_ | object | 선택한 처리결과 행 정보 | |
| document | object | 선택 문서 정보 (문서번호, 접수번호, 서식 코드와 이름, 처리상태, 통지일시) | |
| workplace | object | 사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수) | |
| precheck | object | 인쇄와 저장 전 사전 점검 결과 | |
| ec15_ | array | EC15 보고서 행 | |
| ec15_ | number | EC15 보고서 행 수 | |
| workflow_ | object | 연동 방식 정보 (전송 방식과 화면 호출 경로) |
// result.data
{
"view_action": {},
"detail_params": {},
"selected_option": {},
"document": {},
"workplace": {},
"precheck": {},
"ec15_report_rows": [],
"ec15_report_row_count": 1,
"workflow_contract": {}
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 행 없음 — 조건에 맞는 행을 찾지 못했습니다. |
2. 증명서 신청 처리결과 검색nps_ edi. b1. certificates. application_ results. search
MCP 도구 이름 nps_
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
접수 기간과 증명서 종류, 처리 상태를 넣으면 국민연금 증명서 신청 건마다 접수번호, 문서번호, 처리 상태를 돌려줍니다. 결과 행은 세션에 캐시되어 document_view에서 재사용됩니다.
- 로그인을 먼저 호출해 세션을 만든 뒤, 같은 account_link_id 로 호출합니다. [국민연금공단 EDI 로그인]
- result.data.error_code=CERTIFICATE_APPLICATION_RESULTS_EMPTY.
- 날짜 미입력 시 최근 90일.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| start_ | string | 8 | N | 검색 시작일. 미입력 시 오늘 기준 90일 전 | |
| end_ | string | 8 | N | 검색 종료일. 미입력 시 오늘 | |
| template_ | string | - | N | 증명서 양식 코드. A·빈값=전체 | |
| member_ | string | - | N | 가입자(신청인) 성명 jnprNm | |
| member_ | string | - | N | 가입자 주민등록번호 jnprErrno | |
| processing_ | string | - | N | 처리상태. A=전체, C=정상, S=오류 | |
| confirm_ | string | - | N | 확인상태 wediSnrSttsCd2 | |
| row_ | string | - | N | 행 텍스트 부분 일치 필터 (서버측 후처리) | |
| page_ | number | - | N | 페이지 번호. 기본 1 | |
| page_ | number | - | N | 페이지당 행 수. 기본 10 |
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를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| options | array | 증명서 신청결과 행 배열 | |
| rows | array | 처리결과 행 배열 (options와 동일) | |
| row_ | number | 반환 행 수 | |
| source_ | number | 기관 응답 원본 행 수 | |
| workplace | object | 사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수) | |
| search | object | 이번 조회에 쓰인 조회 조건 | |
| page | object | 페이지 정보 | |
| template_ | array | 증명서 서식 선택지 | |
| processing_ | array | 처리상태 선택지 | |
| workflow_ | object | 연동 방식 정보 (전송 방식과 화면 호출 경로) |
// 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_
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
가입증명서를 발급하기 전에 대상 가입자 1명에서 100명의 가입증명 신청서를 기관에 보냅니다. 보낸 신청서는 취소할 수 없는 쓰기 액션입니다.
- 로그인 뒤 같은 account_link_id 로 호출합니다. 대상자마다 성명(member_name)과 주민등록번호 13자리(rrno)를 보냅니다. 주민등록번호는 응답에 싣지 않습니다. [국민연금공단 EDI 로그인]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 신청서를 보내지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이, error.preview 에 보낼 대상자(성명, 주민등록번호는 뒤 네 자리만)가 함께 옵니다.안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm 칸은 확인으로 쓰이지 않으며, 다시 보낼 때 더하면 본문이 달라져 확인 토큰 불일치로 끝납니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 신청서를 보내지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
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 | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
- 대괄호 []는 목록의 각 항목을, 점은 객체의 속성을, {key}는 실제 키로 바꿔 넣는 사전 항목을 뜻하며, 선택인 부모를 보낼 때 하위 필수 칸은 조건부로 표시합니다.
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| subscribers | array | Y | 신청 대상자 1~100명. 한 명이라도 가입 확인에 실패하면 신청서를 보내지 않는다 | |
| subscribers[]. | string | Y | 대상자 성명. 기관이 확인한 성명과 다르면 신청서를 보내지 않는다 | |
| subscribers[]. | string | Y | 대상자 주민등록번호(외국인등록번호) 13자리. 하이픈을 넣어도 된다. 응답과 증적에는 싣지 않는다 | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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 에 확인된 성명과 취득일이 실립니다. 이어서 가입자 목록 조회 → 가입증명서 발급 순서로 호출합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다 | |
| action | string | 요청한 액션 이름 | |
| template_ | string | 증명서 서식 코드 (EC02 가입자 가입증명) | |
| doc_ | string | 신청서 서식 코드 (EB0301) | |
| message_ | string | 이번 신청서의 전송 관리 번호 | |
| applicant_ | number | 신청한 대상자 수 | |
| applicants | array | 확인된 대상자 배열 (순번, 성명, 취득일). 주민등록번호는 싣지 않습니다 | |
| result | object | 접수 결과 (응답 코드 rspnsRsltCd, 응답 문장, 상태, 오류 코드와 문장) | |
| workplace | object | 사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수) | |
| workflow_ | object | 연동 방식 정보 (전송 방식과 화면 호출 경로) | |
| message | string | null | 접수를 확인하지 못했을 때의 안내 문장 (정상이면 null) |
// 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_ | 대상자 누락 — subscribers 를 보내지 않았습니다. | |
| VALIDATION_ | 대상자 입력 오류 — 대상자가 비었거나 100명을 넘었거나, 성명이 비었거나, 주민등록번호가 13자리가 아니거나, 같은 번호가 두 번 들어 있습니다. 신청서는 보내지 않습니다. | |
| PROVIDER_ | 가입 확인 실패 — 한 명이라도 가입 정보를 조회하지 못했거나, 성명이 일치하지 않거나, 가입 내역이 없으면 신청서를 보내지 않습니다. 메시지가 몇 번째 대상자인지 알려 줍니다. | |
| PROVIDER_ | 접수 거절 — 신청서가 접수되지 않았습니다. 응답 사유가 메시지에 함께 실립니다. 잠시 후 다시 신청합니다. | |
| PROVIDER_ | 결과 확인 불가 — 신청서는 보냈지만 접수 여부를 확인하지 못했습니다. 다시 신청하지 말고 증명서 신청 처리결과 조회에서 목록을 먼저 확인합니다. | |
| POLICY_ | 기능 꺼짐 — 지금은 신청서를 보낼 수 없습니다. 가입자 목록 조회와 처리결과 조회는 그대로 쓸 수 있습니다. |
4. 가입증명서 발급nps_ edi. b1. certificates. membership. issue
MCP 도구 이름 nps_
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
선택한 가입자의 국민연금 가입증명서를 한글로 발급합니다. 발급 이력이 남고 취소할 수 없는 쓰기 액션입니다.
- 가입증명 신청서가 접수된 뒤, 가입자 목록 조회로 대상을 고르고 같은 account_link_id 로 호출합니다. [국민연금공단 EDI 로그인]
- 요청 거절(HTTP 400, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_REQUIRED — confirmation_token 없이 부르면 발급하지 않고 이 오류로 끝납니다.error.message 에 확인할 내용이, error.confirmation_token 에 1회용 토큰이, error.preview 에 발급할 가입자와 언어가 함께 옵니다.안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청의 params.confirmation_token 에 그 토큰을 넣어 다시 보냅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문에만 맞습니다.confirm 칸은 확인으로 쓰이지 않으며, 다시 보낼 때 더하면 본문이 달라져 확인 토큰 불일치로 끝납니다.
- 요청 거절(HTTP 409, 작업은 만들어지지 않음).error.code=WRITE_CONFIRMATION_INVALID — 토큰이 만료됐거나, 이미 썼거나, 다른 호출자나 다른 환경에서 받은 것이거나, 확인한 요청 본문과 달라졌으면 발급하지 않고 이 오류로 끝나며 어느 쪽인지는 알려 주지 않습니다.error.message 는 「확인이 만료됐거나 확인한 내용과 달라졌습니다. 다시 확인해 주세요.」 입니다. confirmation_token 없이 같은 요청을 다시 보내 새 토큰과 안내를 받은 뒤 사용자에게 다시 확인을 받습니다.
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 | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 row_index, row_key 또는 member_name 중 하나 이상을 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| row_ | number | 조건부 | 가입자 목록 조회 결과 options[].row_index | |
| row_ | string | 조건부 | 가입자 목록 조회 결과 options[].row_key | |
| member_ | string | 조건부 | 가입자 성명. 동명이인이면 row_index 나 row_key 로 한 명을 지정 | |
| language | string | N | 증명서 언어. ko 한글. 기본 ko | |
| confirmation_ | string | N | 1회용 확인 토큰입니다. 처음에는 보내지 않습니다. 토큰 없이 부르면 기관에 아무것도 보내지 않고 작업도 만들지 않은 채 확인이 필요하다는 오류(WRITE_CONFIRMATION_REQUIRED)로 끝나고, 응답의 error.confirmation_token 에 토큰이 옵니다. error.message 의 안내를 사용자에게 보여 주고 동의를 받은 뒤 같은 요청에 이 토큰을 넣어 다시 부릅니다. 토큰은 10분 안에 한 번만 쓸 수 있고 처음 요청과 같은 본문, 같은 호출자, 같은 환경에서만 맞으며, 아니면 확인이 만료됐거나 내용이 달라졌다는 오류로 거절합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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 에 새 문서번호가 실립니다. 증명서 신청 처리결과 조회와 문서 보기로 이어서 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| outcome | string | 기관 처리 판정. 성공 응답에서는 항상 confirmed 입니다 | |
| action | string | 요청한 액션 이름 | |
| template_ | string | 증명서 서식 코드 (EC02 가입자 가입증명) | |
| language | string | 발급 언어 (ko 한글) | |
| subscriber | object | 발급 대상 가입자 행 (row_index, row_key, 성명과 영문 성명, 가입일, 처리일, 신청 문서번호) | |
| issued_ | object | 발급된 증명서 (문서번호 doc_no, 서식 코드) | |
| gap_ | object | 24시간 발급 제한 검사 결과 (가능 여부, 상태, 건수) | |
| report_ | array | 증명서 생성 응답에 들어 있던 데이터 묶음 이름 | |
| report_ | object | 증명서 생성 응답의 모양 (kind 는 pdf, json, other 중 하나이고 content_type, size_bytes, sha256 등이 함께 실립니다). 본문은 싣지 않습니다 | |
| new_ | array | 발급 뒤 처리결과 목록에 새로 생긴 문서번호 | |
| workplace | object | 사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수) | |
| workflow_ | object | 연동 방식 정보 (전송 방식과 화면 호출 경로) | |
| message | string | null | 발급을 확인하지 못했을 때의 안내 문장 (정상이면 null) |
// 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_ | 가입자 지정 오류 — row_index · row_key · member_name 중 하나로 가입자를 지정하지 않았거나, 같은 성명이 여러 명이거나, language 가 ko · en 이 아닙니다. | |
| RESOURCE_ | 가입자 없음 — 지정한 가입자가 목록에 없습니다. 가입자 목록 조회를 다시 실행해 확인합니다. | |
| PROVIDER_ | 신청 내역 없음 — 가입증명 신청 내역이 없습니다. 가입증명 신청서 발송을 먼저 호출합니다. | |
| PROVIDER_ | 24시간 제한 — 발급한 지 24시간이 지난 가입증명이라 기관이 다시 출력하지 못하게 막았습니다. error.message 는 기관 문장 뒤에 「가입증명 신청서를 새로 보낸 뒤 발급해 주세요.」 가 붙은 문장입니다. 가입증명 신청서 발송부터 다시 호출한 뒤 발급합니다. | |
| PROVIDER_ | 결과 확인 불가 — 발급 요청은 보냈지만 새 문서번호를 확인하지 못했습니다. 이미 발급됐을 수 있어 다시 발급하지 않습니다. error.message 끝에 「가입증명 발급은 증명서 신청 처리결과 목록에 새 줄로 남지 않아 그 목록으로는 발급 여부를 확인할 수 없습니다.」 가 붙습니다. | |
| POLICY_ | 기능 꺼짐 — 지금은 발급할 수 없습니다. 가입자 목록 조회와 처리결과 조회는 그대로 쓸 수 있습니다. |
5. 가입증명 발급 대상자 조회nps_ edi. b1. certificates. membership. subscribers. search
MCP 도구 이름 nps_
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
가입증명 신청서를 보낸 가장 최근 건에 딸린 가입자를 이름으로 찾아 성명, 가입 기간 표시와 행 번호, 행 키를 돌려줍니다. 결과 행은 세션에 남아 가입증명서 발급에서 다시 씁니다.
- 로그인 뒤 같은 account_link_id 로 호출합니다. 가입증명 신청서가 먼저 접수되어 있어야 합니다 - 가장 최근 가입증명 신청 아래의 가입자를 보여 줍니다. [국민연금공단 EDI 로그인]
- 작업은 성공으로 끝나고 row_count=0, options 는 빈 배열입니다.
- search_text 를 비우면 전체 가입자를 조회합니다. page_no 기본 1, page_per_count 기본 10.
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 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| search_ | string | N | 가입자 검색어 srchData(성명 등). 미입력 시 전체 | |
| page_ | number | N | 페이지 번호. 기본 1 | |
| page_ | number | N | 페이지당 행 수. 기본 10 |
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_ | string | 증명서 서식 코드 (EC02 가입자 가입증명) | |
| row_ | number | 반환 행 수 | |
| options | array | 가입자 행 배열 (row_index, row_key, 성명과 영문 성명, 가입일, 처리일, 신청 문서번호, raw). 주민등록번호는 싣지 않습니다 | |
| workplace | object | 사업장 정보 (사업장관리번호, 사업자번호, 연금번호, 사업장명, 지사, 가입자 수) | |
| search | object | 이번 조회에 쓰인 조회 조건 (검색어, 페이지) | |
| workflow_ | object | 연동 방식 정보 (전송 방식과 화면 호출 경로) |
// 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_ | 신청 내역 없음 — 가입증명 신청 내역이 없습니다. 가입증명 신청서 발송을 먼저 호출합니다. |