Templates API

템플릿을 조회하고 책에 적용하는 방법을 안내합니다.

템플릿이란?

템플릿은 포토북 페이지의 레이아웃을 정의하는 디자인 틀입니다. 텍스트, 사진, 그래픽 요소의 배치와 스타일이 미리 설정되어 있어, 파라미터만 전달하면 완성된 페이지를 만들 수 있습니다. 각 템플릿의 디자인 특징과 사용 예시는 템플릿 상세 정보 ↗에서 확인할 수 있습니다.

템플릿 종류

템플릿은 templateKind로 구분되며, 네 가지 종류가 있습니다. 현재 제공되는 모든 템플릿 카탈로그는 템플릿 카탈로그 ↗에서 미리 볼 수 있습니다.

카테고리

템플릿은 용도별 카테고리로 분류됩니다. GET /template-categories로 전체 목록을 조회할 수 있습니다.

템플릿 조회하기

목록 조회

GET /templates로 사용 가능한 템플릿을 조회합니다. 공용(public) 템플릿과 본인이 생성한 템플릿이 함께 조회됩니다.

# SQUAREBOOK_HC용 내지 템플릿 조회
curl 'https://api-sandbox.sweetbook.com/v1/templates?bookSpecUid=SQUAREBOOK_HC&templateKind=content' \
  -H 'Authorization: Bearer {YOUR_API_KEY}'

{
  "success": true,
  "message": "Success",
  "data": [
    {
      "templateUid": "8hKvbcNJdSgj",
      "accountUid": "public",
      "templateName": "알림장A_내지",
      "description": "알림장 내지 — 미니멀 1단",
      "templateKind": "content",
      "category": "diary",
      "theme": "minimal",
      "bookSpecUid": "SQUAREBOOK_HC",
      "bookSpecName": "고화질 스퀘어북 (하드커버)",
      "isPublic": true,
      "status": "active",
      "thumbnails": { "layout": "https://..." },
      "createdAt": "2026-01-15T09:00:00Z",
      "updatedAt": "2026-01-20T14:30:00Z"
    }
  ],
  "pagination": { "total": 45, "limit": 50, "offset": 0, "hasNext": false }
}

상세 조회

GET /templates/{templateUid}로 특정 템플릿의 상세 정보를 확인할 수 있습니다. 상세 응답에는 파라미터 정의, 레이아웃, 레이아웃 규칙, 베이스 레이어 등이 포함됩니다.

썸네일 URL은 정적 호스팅 자산이며 다음 정책을 따릅니다.

• 인증 불요: Authorization 헤더 없이 접근 가능합니다. <img src>에 직접 사용할 수 있습니다.
• 영구 URL: 만료·서명 토큰이 없습니다. 캐시·CDN 친화적입니다.
• 확장자 가변: .jpg / .png / .webp 등 등록 시 원본 확장자가 그대로 유지됩니다. 응답의 URL을 그대로 사용하고 확장자를 임의로 가정·변경하지 마세요.
• 도메인: 호출 도메인(api-sandbox.sweetbook.com / api.sweetbook.com)이 자동 적용됩니다.

curl 'https://api-sandbox.sweetbook.com/v1/templates/8hKvbcNJdSgj' \
  -H 'Authorization: Bearer {YOUR_API_KEY}'

"thumbnails": {
  "layout": "https://api-sandbox.sweetbook.com/templates_thumb/{templateUid}/layout.jpg",
  "baseLayerOdd": "https://api-sandbox.sweetbook.com/templates_thumb/{templateUid}/base_layer_odd.jpg",
  "baseLayerEven": "https://api-sandbox.sweetbook.com/templates_thumb/{templateUid}/base_layer_even.jpg"
}

"thumbnails": {
  "layout": "https://api-sandbox.sweetbook.com/templates_thumb/{templateUid}/layout.jpg"
}

템플릿 선택 기준

템플릿을 선택할 때 다음 사항을 확인하세요.

파라미터 구조

템플릿 상세 응답의 parameters는 definitions 래퍼로 감싸진 구조입니다. 각 파라미터 키는 parameters.definitions.{key} 경로에 위치합니다.

{
  "parameters": {
    "definitions": {
      "bookTitle": {
        "binding": "text",
        "label": "책 제목"
      },
      "frontPhoto": {
        "binding": "file",
        "label": "표지 사진"
      },
      "photos": {
        "binding": "rowGallery",
        "label": "내지 사진 목록"
      }
    }
  }
}

파라미터 바인딩

템플릿의 parameters.definitions에 정의된 바인딩 유형에 따라 값을 전달합니다.

파라미터 스키마 조회

GET /templates/{templateUid}/schema는 템플릿 파라미터 명세를 JSON Schema (draft-07) 형식으로 반환합니다. 상세 조회(GET /templates/{templateUid})의 parameters 필드는 내부 저장 구조를 그대로 노출하지만, 본 엔드포인트는 표준 JSON Schema 형식으로 변환하여 페이로드 검증·자동화 도구·코드 생성기와 바로 연동할 수 있도록 합니다.

권한 정책은 상세 조회와 동일합니다 — 공용 템플릿(isPublic: true)은 누구나, 본인 소유 개인 템플릿은 본인만 조회 가능합니다. 존재하지 않거나 접근 권한이 없는 templateUid로 호출하면 404 ERR_NOT_FOUND가 반환됩니다.

curl 'https://api-sandbox.sweetbook.com/v1/templates/4MY2fokVjkeY/schema' \
  -H 'Authorization: Bearer {YOUR_API_KEY}'

응답 구조

응답의 data 객체는 JSON Schema draft-07 사양을 따르며 다음 필드를 포함합니다.

{
  "success": true,
  "message": "성공",
  "data": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "4MY2fokVjkeY",
    "title": "표지",
    "type": "object",
    "properties": {
      "frontPhoto": {
        "type": "string",
        "description": "앞표지 배경 대형 사진",
        "format": "uri",
        "x-binding": "file"
      },
      "backPhoto": {
        "type": "string",
        "description": "뒤표지 소형 사진",
        "format": "uri",
        "x-binding": "file"
      },
      "dateRange": {
        "type": "string",
        "description": "날짜 범위",
        "x-binding": "text"
      },
      "spineTitle": {
        "type": "string",
        "description": "책등 및 앞표지 세로 제목",
        "x-binding": "text"
      }
    },
    "required": ["frontPhoto", "dateRange", "spineTitle"],
    "x-templateKind": "cover"
  }
}

properties 항목 구조

각 파라미터는 표준 JSON Schema property로 표현되며, 원본 binding 값은 x-binding 확장 필드로 보존됩니다. 바인딩 유형별로 다음과 같이 매핑됩니다.

description은 원본 정의에 명시된 경우에만 노출됩니다 (없으면 omit). 원본에 enum 후보값이 있으면 그대로 passthrough되며, 없으면 omit됩니다.

"photos": {
  "type": "array",
  "description": "사진들 (0~N장)",
  "items": {
    "type": "string",
    "format": "uri"
  },
  "x-binding": "rowGallery"
}

required 판정 규칙

응답의 루트 required 배열은 다음 규칙에 따라 결정됩니다.

• 원본 정의에 required가 명시되지 않은 키는 자동으로 필수(true)로 간주되어 응답 required 배열에 포함됩니다.
• 원본 정의에 required: false가 명시된 키만 선택 파라미터로 처리되어 required 배열에서 제외됩니다.
• 본 규칙은 응답 시점에만 정규화되며 원본 데이터에는 영향을 주지 않습니다. 기존 GET /templates/{templateUid} 상세 조회의 parameters 필드는 raw passthrough이므로 이 정규화가 적용되지 않습니다.

상세 조회와의 비교

상세 조회(GET /templates/{templateUid})와 신규 스키마 조회의 차이는 다음과 같습니다.

기존 호출자는 변경할 필요가 없습니다. 상세 조회 응답 구조는 그대로 유지됩니다. JSON Schema 형식이 필요한 클라이언트만 새 엔드포인트를 추가로 호출하면 됩니다.

권장 사용 흐름

스키마 응답을 활용하여 책에 템플릿을 적용하는 표준 흐름은 다음과 같습니다.

1. GET /templates?bookSpecUid=...로 사용 가능한 템플릿 목록을 조회합니다.
2. GET /templates/{templateUid}/schema로 파라미터 스키마를 받습니다.
3. required 배열로 필수 키를 확인하고, properties.{key}.x-binding으로 전달 형식을 결정합니다.
   • "text" → parameters[key]에 문자열
   • "file" → parameters[key]에 이미지 URL 또는 업로드된 사진의 fileName
   • 갤러리 계열(gallery / collageGallery / rowGallery) → parameters[key]에 URL/파일명 배열
4. POST /books/{bookUid}/cover 또는 POST /books/{bookUid}/contents로 템플릿을 적용합니다.

$schema: "http://json-schema.org/draft-07/schema#"이 명시되어 있으므로 기성 JSON Schema 검증기(예: ajv, python-jsonschema)에 응답을 그대로 입력하여 페이로드 검증을 자동화할 수 있습니다.x-binding 같은 확장 필드는 표준 검증기가 무시하므로 별도 설정이 필요하지 않습니다.

책에 템플릿 적용하기

책 생성부터 최종화까지의 전체 흐름에서 템플릿이 사용되는 과정입니다.

1. POST /books — 책 생성 (bookSpecUid 지정)
2. POST /books/{bookUid}/photos — 사진 업로드 (필요 시)
3. POST /books/{bookUid}/cover — 표지 적용 (cover 템플릿 + 파라미터)
4. POST /books/{bookUid}/contents — 내지 추가 (content 템플릿 + 파라미터) ← 반복
5. POST /books/{bookUid}/finalization — 최종화

표지 적용 예시

표지 템플릿을 적용할 때는 templateUid, 파라미터(제목, 저자 등), 이미지 파일을 함께 전달합니다.

curl -X POST 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/cover' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "templateUid": "COVER_TEMPLATE_UID",
  "parameters": {
    "bookTitle": "우리 가족 앨범",
    "year": "2026"
  }
}'

내지 추가 예시

curl -X POST 'https://api-sandbox.sweetbook.com/v1/books/{bookUid}/contents' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "templateUid": "8hKvbcNJdSgj",
  "parameters": {
    "date": "2026-03-01",
    "dayOfWeek": "월요일",
    "teacherComment": "오늘 하루도 잘 보냈습니다.",
    "photos": ["photo1.jpg", "photo2.jpg"]
  }
}'

HTTP 상태 코드

Templates API의 모든 엔드포인트(GET /templates, GET /templates/{templateUid}, GET /templates/{templateUid}/schema, GET /template-categories)는 다음 상태 코드를 공통으로 반환합니다.

실패 응답 6필드 shape(success·errorCode·message·data·errors·fieldErrors) 및 errorCode 분기 가이드는 에러 코드 & 트러블슈팅을 참고하세요.

관련 문서

• Books — 템플릿 기반 — 책 생성, 표지/내지 추가, 최종화
• 템플릿 기반 시나리오 — 책 생성부터 주문까지 단계별 흐름
• 혼합 방식 시나리오 — 표지=템플릿, 내지=PDF 흐름
• BookSpecs API — 판형 정보 (페이지 수 규칙 포함) 조회
• 템플릿 구조와 바인딩 — 변수, 파라미터, 이미지 매칭 동작 원리
• 레이아웃 동작 원리 — breakBefore, 페이지 흐름
• 갤러리 템플릿 — 다수 이미지 배치 (collageGallery, rowGallery)
• 베이스 레이어 — 표지·내지 공통 배경 레이어