REST API 빠른 시작

API 키를 받아 첫 작업 결과를 가져오기까지, 처음 연동에 필요한 순서만 모았습니다.

연동 흐름

새로 가입하면 데모(실제 기관 호출) 환경이 바로 열립니다. 환경별 차이와 한도는 환경에 있습니다.

XBOSS 는 기관마다 다른 API 를 두지 않습니다. 모든 요청은 작업 하나로 제출하고, 끝나면 결과를 가져옵니다.

주소는 환경이 달라도 같습니다. X-Env-Scope 헤더 값으로 어느 환경에서 실행할지 고릅니다.

STEP 01
API 키 발급
콘솔 키 관리에서 client_id 와 client_secret 을 받습니다.
STEP 02
자격증명 등록
기관 로그인에 쓸 공동인증서나 아이디를 콘솔에 등록합니다.
STEP 03
작업 제출
POST /v1/jobs 로 기관·작업·파라미터를 보냅니다.
STEP 04
결과 조회
상태가 SUCCEEDED 가 되면 결과를 가져옵니다.

처음 연동 순서

API 키 발급
새로 가입하면 키가 자동으로 발급됩니다. 콘솔 키 관리에 가입 직후 한 번 보이는 client_secret 을 그 자리에서 저장합니다.
인증 헤더 만들기
client_id:client_secret 을 Base64 로 인코딩해 Authorization: Basic {인코딩 값} 으로 보냅니다.
환경 고르기
처음에는 real_test(데모)로 시작합니다. 가입하면 데모가 자동으로 승인되며 승인 전이면 콘솔에서 신청합니다.
서비스 운영은 현재 공개 요금제의 production(정식)입니다.
환경에서 차이를 확인합니다.
자격증명 등록
기관에 로그인하려면 공동인증서나 기관 아이디가 필요합니다. 콘솔 자격증명 등록에서 등록합니다.
API 키로는 등록할 수 없습니다. 자격증명 등록을 봅니다.
작업 제출과 결과 조회
POST /v1/jobs 로 제출하고, 받은 job_id 로 상태를 확인한 뒤 결과를 가져옵니다. 작업 처리 흐름에 상태 값과 폴링 방법이 있습니다.

주소

용도	주소
API 호출	https://api.xdata.kr
작업 제출	POST https://api.xdata.kr/v1/jobs
OpenAPI 명세·테스트 화면	https://api.xdata.kr/docs
콘솔 — 키 발급·자격증명 등록	https://console.xdata.kr

작업 제출 요청 헤더

헤더	필수	설명
Authorization	필수	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식: Basic base64("{client_id}:{client_secret}")
X-Env-Scope	필수	호출 환경입니다. 값: real_test · production
Idempotency-Key	필수	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. 길이: 1-128
Content-Type	필수	요청 본문 형식입니다. 값: application/json
X-Trace-Id	선택	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

작업 제출 예시

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: demo-search_list-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "hometax",
  "action": "hometax.etax.invoice.search_list",
  "params": {
    "from_date": "2026-01-01",
    "to_date": "2026-01-31"
  }
}'

이 예시의 홈택스는 등록한 자격증명이 필요해, 등록하기 전에 보내면 제출이 400 VALIDATION_INVALID_FIELD 로 거절되고 작업이 만들어지지 않습니다.

제출 응답

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "hometax",
    "action": "hometax.etax.invoice.search_list",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

새 작업이면 HTTP 202, 이미 접수된 작업을 돌려받으면 HTTP 200 입니다.

같은 Idempotency-Key 와 같은 본문으로 다시 보내면 그 작업을 돌려받습니다(확인값을 받는 쓰기 작업도 접수된 뒤에는 같습니다 - 재시도).
응답의 status 는 새 작업이면 QUEUED, 돌려받은 작업이면 그 작업의 지금 상태입니다.

결과 받기

작업은 비동기로 처리되므로 GET /v1/jobs/{job_id} 로 상태를 확인합니다.

응답의 retry_after_seconds 만큼 기다렸다 다시 확인합니다.
조회 요청에는 Authorization 과 X-Env-Scope 두 헤더만 넣습니다.

status 가 SUCCEEDED 가 되면 GET /v1/jobs/{job_id}/result 로 결과를 가져옵니다. 끝나기 전에 결과를 조회하면 409 입니다.

bash

curl --request GET \
  --url 'https://api.xdata.kr/v1/jobs/{job_id}' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test'

서버 연동은 API 키로 HTTP Basic 인증을 합니다.

MCP 의 OAuth 토큰으로 REST API 를 부르면 403 이 돌아옵니다.
client_secret 은 서버에만 두고 브라우저나 모바일 앱 코드에는 넣지 마세요.