API 공통 사항

Book Print API의 인증, 요청/응답 형식, 페이지네이션, Rate Limiting 등 공통 규칙을 안내합니다.

인증

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

API Key는 SB로 시작하는 12자 prefix(SB + 10자 식별자)와 secret이 .으로 연결된 형식입니다. Sandbox 키와 Live 키가 분리되어 있으므로 환경에 맞는 키를 사용하세요.

Authorization: Bearer SB{10자 식별자}.{secret}

예시 (더미):
Authorization: Bearer SBXXXXXXXXXX.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Base URL

요청 / 응답 형식

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

응답 필드

성공/실패 모두 공통 shape을 사용합니다. 실패 응답은 6필드 고정(success·errorCode·message·data·errors·fieldErrors)이며 errorCode·errors·fieldErrors가 항상 존재합니다. errorCode는 HTTP 상태 기반 기본값이 자동 주입되어 빈 문자열이 되지 않으며, errors·fieldErrors는 해당 항목이 없으면 빈 배열([])로 반환됩니다.

성공 응답

요청이 성공하면 success: true와 함께 data 필드에 결과가 포함됩니다.

// 성공 응답
{
  "success": true,
  "message": "Success",
  "data": { ... }
}

에러 응답

요청이 실패하면 success: false와 함께 6필드 고정 shape으로 반환됩니다. errorCode는 항상 존재하며, 단순 에러는 errors 메시지만, 필드 단위 검증 실패는 fieldErrors에 구조화 정보가 포함됩니다.

참고: 도메인 검증(예: 페이지 제약, finalize 전제조건)의 errors·message는 한글로 반환되지만, 요청 본문의 필수 필드가 아예 누락되는 케이스(모델 바인딩 자동 검증)는 영어 라벨(예: "The PostalCode field is required.")로 반환될 수 있습니다. 클라이언트 분기는 errorCode와 fieldErrors[].constraint로 하세요.

{
  "success": false,
  "errorCode": "ERR_NOT_FOUND",
  "message": "Not Found",
  "data": null,
  "errors": ["책을 찾을 수 없습니다: bk_xxx"],
  "fieldErrors": []
}

{
  "success": false,
  "errorCode": "ERR_VALIDATION_FAILED",
  "message": "Bad Request",
  "data": null,
  "errors": [
    "shipping.address1: The Address1 field is required.",
    "shipping.postalCode: The PostalCode field is required.",
    "shipping.recipientName: The RecipientName field is required.",
    "shipping.recipientPhone: The RecipientPhone field is required."
  ],
  "fieldErrors": [
    { "field": "shipping.address1", "message": "The Address1 field is required.", "constraint": "required" },
    { "field": "shipping.postalCode", "message": "The PostalCode field is required.", "constraint": "required" },
    { "field": "shipping.recipientName", "message": "The RecipientName field is required.", "constraint": "required" },
    { "field": "shipping.recipientPhone", "message": "The RecipientPhone field is required.", "constraint": "required" }
  ]
}

fieldErrors 항목 구조

필드 단위 검증 실패는 fieldErrors 배열의 각 항목이 아래 필드를 가집니다. field·message는 항상 존재하며, 나머지 3개는 해당 맥락에서 값이 있을 때만 포함됩니다(없으면 키 자체가 생략).

constraint enum

{
  "field": "pageCount",
  "message": "최소 24 페이지가 필요합니다",
  "currentValue": 10,
  "requiredValue": 24,
  "constraint": "min"
}

페이지네이션

목록 조회 API는 limit/offset 기반 페이지네이션을 사용합니다. 응답 구조는 data.{리소스명} 배열과 data.pagination 객체가 분리된 형태입니다. 리소스명은 엔드포인트에 따라 다릅니다 (books, orders, templates 등).

Query 파라미터

공통 응답 필드

{
  "success": true,
  "message": "성공",
  "data": [ /* ... book 항목들 */ ],
  "pagination": {
    "total": 0,
    "limit": 10,
    "offset": 0,
    "hasNext": false
  }
}

{
  "success": true,
  "message": "성공",
  "data": [ /* ... order 항목들 */ ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "hasNext": true
  }
}

{
  "success": true,
  "message": "성공",
  "data": [ /* ... template 항목들 */ ],
  "pagination": {
    "total": 120,
    "limit": 100,
    "offset": 0,
    "hasNext": true
  }
}

Rate Limiting

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

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "success": false,
  "errorCode": "ERR_TOO_MANY_REQUESTS",
  "message": "Too Many Requests",
  "data": null,
  "errors": ["요청 한도를 초과했습니다. Retry-After 헤더 값만큼 대기 후 재시도하세요."],
  "fieldErrors": []
}

멱등성 (Idempotency)

네트워크 오류로 동일한 요청이 중복 실행되는 것을 방지하기 위해 Idempotency-Key 헤더를 지원합니다.Books/Credits/Orders 주요 POST 엔드포인트(POST /books, POST /orders, POST /credits/sandbox/charge 등)에서 사용을 강력히 권장합니다.

동일한 Idempotency-Key + 같은 요청 본문으로 재시도하면 최초 응답이 그대로 재사용됩니다(중복 처리 방지). 동일한 키 + 다른 요청 본문을 보내면 422 Unprocessable Entity + errorCode: "ERR_IDEMPOTENCY_KEY_MISMATCH"가 반환됩니다. 따라서 재시도 시에는 반드시 원본과 동일한 본문을 같은 키로 보내야 합니다.

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

주요 HTTP 에러 코드

자주 만나는 HTTP 상태 코드와 기본 errorCode 대응입니다. 상태 코드별 상세 케이스·응답 예시·마이그레이션 가이드는 에러 코드 & 트러블슈팅을 참조하세요.

PDF 다운로드(GET /books/{bookUid}/pdf-cover·GET /books/{bookUid}/pdf-contents)는 책의 creationType에 따라 위 일반 에러 외에 5종 추가 errorCode(ERR_PDF_NOT_UPLOADED 404 / ERR_PDF_NOT_GENERATED 409 / ERR_PDF_PENDING 409 / ERR_PDF_GENERATION_FAILED 422 / ERR_PDF_FILE_MISSING 500)로 분기됩니다. 자세한 매트릭스는 Books — PDF 기반 / Books — 템플릿 기반 / 에러 코드 & 트러블슈팅의 PDF 다운로드 섹션을 참조하세요.

날짜 형식

모든 날짜/시간 필드는 ISO 8601 형식(UTC)을 사용합니다. 응답 필드에 따라 밀리초 단위까지 포함될 수 있습니다.

관련 문서

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