개발자 문서
API 레퍼런스

사업장 - 국민연금공단 EDI

1. 사업장 기본정보 조회nps_edi.b1.workplace.main_basic_info

MCP 도구 이름 nps_edi__b1__workplace__main_basic_info

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

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

로그인한 사업장의 기본정보와 가입자 수, 관할 지사, 기준소득월액 상하한 정보, 메인 화면의 공지와 배너가 있으면 함께 돌려줍니다.

  • 로그인으로 세션을 등록한 뒤 같은 account_link_id 로 호출합니다. [국민연금공단 EDI 로그인]
  • result.data 의 success=false · error_code=WORKPLACE_BASIC_INFO_EMPTY — 사업장 기본정보가 비어 있습니다. 작업은 실패로 끝나지 않습니다.
  • params 는 빈 객체로 보내도 호출됩니다. include_main_widgets 와 include_declaration_auxiliary 는 기본값이 true 입니다.

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.workplace.main_basic_info이 API 고정값 (기본값)

예시 : nps_edi.b1.workplace.main_basic_info

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
target_yearstring4N기준 연도. 표준월소득 한도 조회 시 미입력이면 당해 연도

형식 : YYYY

include_main_widgetsboolean-N메인 위젯(알림·배너·팝업·공지) 포함. 기본 true
include_declaration_auxiliaryboolean-N신고 보조(건강보험 단위·표준월소득 한도) 포함. 기본 true
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: main_basic_info-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "nps_edi",
  "action": "nps_edi.b1.workplace.main_basic_info",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • workplace·main_widgets·declaration_page_auxiliary를 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
workplaceobject사업장 기본정보 객체
main_widgetsobject알림 위젯 배열 (include_main_widgets=true 시)
declaration_page_auxiliaryobject신고 보조 데이터 (include_declaration_auxiliary=true 시)
workflow_contractobject연동 방식 정보 (전송 방식과 화면 호출 경로)
json
// result.data
{
  "success": true,
  "workplace": { "business_name": "..." },
  "main_widgets": {},
  "declaration_page_auxiliary": {}
}