인증 (API Key)

API Key를 사용하여 Book Print API에 인증하는 방법을 설명합니다.

개요

Book Print API는 API Key 기반 Bearer Token 인증을 사용합니다. 모든 API 요청에 Authorization 헤더를 포함해야 합니다.

API Key 특징

SB 접두사: 모든 API Key는 SB로 시작하며 .을 포함합니다
환경 구분: Sandbox 키와 Live 키가 분리되어 있습니다
IP 제한: 선택적으로 허용 IP를 설정하여 보안을 강화할 수 있습니다
만료 없음: API Key는 폐기하지 않는 한 계속 유효합니다

Authenticated request

Authorization: Bearer {YOUR_API_KEY}

API Key 발급

API Key는 파트너 포털에서 발급받을 수 있습니다.

파트너 포털에 로그인합니다
파트너 포털 > 설정 > API Key 메뉴로 이동합니다
새 API Key 발급 버튼을 클릭합니다
환경(Sandbox/Live)을 선택합니다
발급된 API Key를 안전하게 저장합니다

API Key는 발급 시에만 전체 값을 확인할 수 있습니다. 발급 후에는 접두사(prefix)만 표시되므로, 발급 즉시 안전한 곳에 저장하세요.

환경별 API Key

환경	용도	과금
`sandbox`	개발 및 테스트 환경	Sandbox 충전금 사용
`live`	프로덕션 환경 (사업 협의 후 사용 가능)	실제 충전금 차감

Sandbox 환경

환경에 따라 API Base URL이 다르며, 서버는 요청 도메인을 기반으로 자동으로 환경을 판별합니다.

도메인 기반 환경 분기

Sandbox: https://api-sandbox.sweetbook.com
Live: https://api.sweetbook.com

Sandbox API Key는 반드시 Sandbox 도메인으로 호출해야 합니다. Live 도메인으로 호출하면 환경 불일치 에러(403 ERR_ENV_MISMATCH)가 반환됩니다.

Request

curl -X GET 'https://api-sandbox.sweetbook.com/v1/books' \
  -H "Authorization: Bearer {YOUR_API_KEY}"

JavaScript (fetch)

아래 코드블록의 탭으로 Sandbox / Live 도메인을 전환할 수 있습니다.

JavaScript (fetch)

const API_KEY = '{YOUR_API_KEY}';
const BASE_URL = 'https://api-sandbox.sweetbook.com/v1';

const response = await fetch(`${BASE_URL}/books`, {
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  }
});

const data = await response.json();
// { "success": true, "data": [...], "message": "Success" }

JavaScript (axios)

import axios from 'axios';

const api = axios.create({
  baseURL: 'https://api-sandbox.sweetbook.com/v1',
  headers: {
    'Authorization': 'Bearer {YOUR_API_KEY}'
  }
});

const { data } = await api.get('/books');
console.log(data);

Python (requests)

Python

import requests

API_KEY = '{YOUR_API_KEY}'
BASE_URL = 'https://api-sandbox.sweetbook.com/v1'

headers = {
    'Authorization': f'Bearer {API_KEY}'
}

response = requests.get(f'{BASE_URL}/books', headers=headers)
data = response.json()
print(data)

인증 에러

상태 코드	의미	원인
401 Unauthorized	인증 실패 (`ERR_UNAUTHORIZED`)	`Authorization` 헤더 누락, Bearer 토큰 무효/만료
403 Forbidden	접근 거부	API Key가 폐기되었거나 허용 IP에 의해 차단됨. Sandbox Key로 Live 호출(또는 반대) — 환경 불일치 시 `ERR_ENV_MISMATCH`. Personal 계정이 Live 도메인을 호출한 경우에도 403 반환
429 Too Many Requests	요청 제한 초과	요청 빈도 제한 초과 — `Retry-After` 헤더 값만큼 대기 후 재시도

401 응답은 표준 6필드 JSON 본문으로 반환됩니다. 다른 errorCode와 응답 포맷 상세는 에러 코드 & 트러블슈팅를 참고하세요.

401 Unauthorized (ERR_UNAUTHORIZED)

{
  "success": false,
  "errorCode": "ERR_UNAUTHORIZED",
  "message": "Unauthorized",
  "data": null,
  "errors": ["인증이 필요합니다"],
  "fieldErrors": []
}

Error handling

const response = await fetch('https://api-sandbox.sweetbook.com/v1/books', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});

if (!response.ok) {
  switch (response.status) {
    case 401: {
      const error = await response.json();
      console.error('인증 실패 — Authorization 헤더 또는 API Key를 확인하세요.', error.errors?.[0] ?? error.message);
      break;
    }
    case 403: {
      const error = await response.json();
      // ERR_ENV_MISMATCH: Sandbox/Live 도메인과 Key 환경 불일치
      console.error('접근 거부:', error.errorCode ?? '', error.errors?.[0] ?? error.message);
      break;
    }
    case 429: {
      const retryAfter = response.headers.get('Retry-After');
      console.error(`요청 제한 초과 — ${retryAfter}초 후 재시도`);
      break;
    }
    default: {
      const error = await response.json();
      console.error('API 에러:', error.errors?.[0] ?? error.message);
    }
  }
}

API Key 보안

API Key는 SB{10자}.[{32자}] 형식이며, . 뒤의 Secret 부분은 발급 시 1회만 전달됩니다.

Secret은 발급 시 1회만 표시: 서버는 원본 Secret을 보관하지 않으므로 분실 시 재확인 불가 — 발급 즉시 안전한 곳에 저장하세요.
허용 IP 설정 (allowIps): 파트너 포털 UI에서 쉼표로 구분된 IP 목록(최대 10개)을 등록하면 해당 IP에서만 Key 사용을 허용합니다.
환경 변수 사용: API Key를 코드/저장소에 직접 포함하지 말고 환경 변수로 주입하세요.
클라이언트 측 노출 금지: 반드시 서버 사이드에서만 호출하고, 브라우저/모바일 앱에는 절대 포함하지 마세요.

Rate Limiting에 대한 자세한 내용은 Rate Limiting 가이드를 참고하세요.

.env

# .env
SWEETBOOK_API_KEY={YOUR_API_KEY}

Node.js

// Node.js에서 환경 변수 사용
const API_KEY = process.env.SWEETBOOK_API_KEY;

const response = await fetch('https://api-sandbox.sweetbook.com/v1/books', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  }
});

FAQ

QSandbox 키와 Live 키의 차이는 무엇인가요?

ASandbox 키로 생성한 책과 주문은 실제 인쇄/배송이 진행되지 않고 결제완료(PAID) 상태에서 멈춥니다. 주문 금액은 Sandbox 전용 충전금에서 차감되며 실제 돈이 빠져나가지 않습니다.

QAPI Key가 노출되면 어떻게 하나요?

A즉시 파트너 포털에서 해당 API Key를 폐기하고 새로운 키를 발급받으세요.

QPostman에서 테스트하려면 어떻게 하나요?

AAuthorization 탭에서 Type을 Bearer Token으로 선택하고 API Key를 입력하세요.