개발자 문서
서비스 소개키 관리자격증명 등록OpenAPI콘솔
API 레퍼런스

사업자등록

1. 국세청 사업자등록 상태 조회opendata.nts.status

MCP 도구 이름 opendata__nts__status

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

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

사업자등록번호로 휴업과 폐업 여부, 과세유형을 국세청 자료에서 조회합니다.

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

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

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

[참고] 재시도

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

예시 : opendata

actionstringY호출할 작업입니다.
  • opendata.nts.status이 API 고정값 (기본값)

예시 : opendata.nts.status

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

[참고] 암호화

순번변수명타입필수설명
b_noarrayY사업자등록번호 목록 - 각 10자리 숫자(예: ["1234567890"]). 최대 100건
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-status-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "opendata",
  "action": "opendata.nts.status",
  "params": {
    "b_no": "<필수: array>"
  }
}'
Response

이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.

json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "opendata",
    "action": "opendata.nts.status",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

2. 국세청 사업자등록 진위 확인opendata.nts.validate

MCP 도구 이름 opendata__nts__validate

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

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

사업자등록번호와 개업일자, 대표자명이 국세청 자료와 맞는지 대조합니다.

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

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

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

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

[참고] 재시도

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

예시 : opendata

actionstringY호출할 작업입니다.
  • opendata.nts.validate이 API 고정값 (기본값)

예시 : opendata.nts.validate

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

[참고] 암호화

순번변수명타입길이필수설명
businessesarray8Y진위 확인 대상 사업자 목록. 항목마다 b_no, start_dt(), p_nm 이 필수

형식 : YYYYMMDD

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-validate-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "opendata",
  "action": "opendata.nts.validate",
  "params": {
    "businesses": "<필수: array>"
  }
}'
Response

이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.

json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "opendata",
    "action": "opendata.nts.validate",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}