API 공통 사항

인증

모든 API 요청에는 Bearer Token 인증이 필요합니다. 파트너 포털에서 발급받은 API Key를 Authorization 헤더에 포함하세요.

Authorization: Bearer SB{prefix}.{secret}

API Key는 SB 접두사로 시작하며, .으로 구분된 prefix와 secret으로 구성됩니다. Sandbox 키와 Live 키가 분리되어 있으므로 환경에 맞는 키를 사용하세요.

Base URL

SweetBook API는 Sandbox와 Live 두 가지 환경을 제공합니다.

요청 형식

대부분의 API 요청은 JSON 형식을 사용합니다. 파일 업로드가 필요한 엔드포인트는 multipart/form-data를 사용합니다.

응답 형식

모든 API 응답은 동일한 JSON 구조를 따릅니다.

성공 응답

{
  "success": true,
  "message": "Success",
  "data": { ... }
}

에러 응답

{
  "success": false,
  "message": "Validation failed",
  "data": null,
  "errors": ["잔액이 부족합니다."],
  "fieldErrors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

응답 필드

페이지네이션

목록 조회 API는 limit/offset 기반 페이지네이션을 사용합니다.

요청 파라미터

응답 구조

{
  "success": true,
  "message": "Success",
  "data": {
    "total": 85,
    "limit": 20,
    "offset": 0,
    "hasNext": true,
    "items": [ ... ]
  }
}

Rate Limiting

API의 안정적인 운영을 위해 엔드포인트별로 요청 빈도를 제한합니다.

Rate Limit을 초과하면 429 Too Many Requests 응답이 반환됩니다. 응답의 Retry-After 헤더(60초)를 확인한 뒤 재시도하세요.

{
  "success": false,
  "message": "Rate limit exceeded. Please retry after 60 seconds.",
  "data": null
}

멱등성 (Idempotency)

네트워크 오류 등으로 동일한 요청이 중복 실행되는 것을 방지하기 위해 Idempotency-Key 헤더를 지원합니다. 특히 주문 생성 시 반드시 사용하는 것을 권장합니다.

curl -X POST 'https://api.sweetbook.com/v1/orders' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-request-id-12345' \
  -d '{ ... }'

동일한 Idempotency-Key로 동일한 요청을 보내면 이전 응답이 반환됩니다. 동일한 키로 다른 내용의 요청을 보내면 409 Conflict 에러가 발생합니다.

날짜 형식

모든 날짜/시간 필드는 ISO 8601 형식(UTC)을 사용합니다.

2026-03-17T09:30:00Z

관련 문서

• 인증 (API Key) — API Key 발급 및 인증 상세
• 환경 (Sandbox / Live) — 환경별 Base URL 및 전환 안내
• Rate Limiting — 요청 빈도 제한 상세 안내
• 페이지네이션 — 목록 조회 페이징 상세
• 멱등성 (Idempotency) — 멱등성 키 상세 동작 원리
• 에러 코드 레퍼런스 — HTTP 상태 코드 및 에러 응답