홈▸개발문서▸Templates

Templates 활용 가이드

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

템플릿이란?

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

템플릿 종류

템플릿은 templateKind로 구분되며, 두 가지 종류가 있습니다.

종류값용도적용 API
표지 템플릿cover책 표지 디자인. 책당 하나만 적용됩니다.POST /books/{bookUid}/cover
내지 템플릿content내지 페이지 디자인. 여러 번 적용하여 페이지를 추가합니다.POST /books/{bookUid}/contents
표지 템플릿과 내지 템플릿은 서로 다른 API로 적용합니다. 표지에 내지 템플릿을 사용하거나, 내지에 표지 템플릿을 사용할 수 없습니다.

카테고리

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

코드key한국어English
1diary일기장Diary
2notice알림장Notice
3album앨범Album
4yearbook졸업앨범Yearbook
5wedding웨딩Wedding
6baby육아Baby
7travel여행Travel
8etc기타Etc

템플릿 조회하기

목록 조회

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

Query Parameter설명
bookSpecUid상품 스펙 UID로 필터링 (예: SQUAREBOOK_HC)
category카테고리로 필터링 (예: album, diary)
templateKind종류로 필터링 (cover 또는 content)
limit, offset페이지네이션 (기본 limit: 50)
bash
# SQUAREBOOK_HC용 내지 템플릿 조회
curl 'https://api.sweetbook.com/v1/templates?bookSpecUid=SQUAREBOOK_HC&templateKind=content' \
  -H 'Authorization: Bearer YOUR_API_KEY'
json
{
  "success": true,
  "message": "Success",
  "data": {
    "templates": [
      {
        "templateUid": "8hKvbcNJdSgj",
        "templateName": "알림장A_내지",
        "templateKind": "content",
        "category": "diary",
        "bookSpecUid": "SQUAREBOOK_HC",
        "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}로 특정 템플릿의 상세 정보를 확인할 수 있습니다. 상세 응답에는 파라미터 정의, 레이아웃, 레이아웃 규칙, 베이스 레이어 등이 포함됩니다.

bash
curl 'https://api.sweetbook.com/v1/templates/8hKvbcNJdSgj' \
  -H 'Authorization: Bearer YOUR_API_KEY'
상세 응답 필드설명
parameters파라미터 정의 (텍스트/이미지/갤러리 바인딩 정보)
layout레이아웃 정의 (요소 배치, 크기)
layoutRules레이아웃 규칙 (여백, 흐름, 컬럼 등)
baseLayer베이스 레이어 (홀수/짝수 페이지 배경 요소)
thumbnails썸네일 URL (layout, baseLayerOdd, baseLayerEven)

템플릿 선택 기준

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

1. bookSpecUid 일치

템플릿의 bookSpecUid가 생성한 책의 bookSpecUid와 일치해야 합니다. 레이아웃 크기가 다르면 적용할 수 없습니다.

2. templateKind 확인

표지에는 cover 템플릿, 내지에는 content 템플릿을 사용해야 합니다.

3. 파라미터 확인

상세 조회로 parameters를 확인하여 어떤 값(텍스트, 사진 등)을 전달해야 하는지 파악하세요.

파라미터 바인딩

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

바인딩 유형전달 값예시
text텍스트 문자열"bookTitle": "우리 가족 앨범"
file이미지 URL 또는 업로드 파일"lineBg": "https://..."
rowGallery사진 파일명 배열"photos": ["photo1.jpg", "photo2.jpg"]
갤러리 바인딩에 사용할 사진은 먼저 POST /books/{bookUid}/photos로 업로드한 후, 반환된 fileName을 사용합니다.

책에 템플릿 적용하기

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

text
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   최종화

표지 적용 예시

bash
curl -X POST 'https://api.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"
  }
}'

내지 추가 예시

bash
curl -X POST 'https://api.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"]
  }
}'
내지는 POST /books/{bookUid}/contents를 여러 번 호출하여 페이지를 계속 추가할 수 있습니다. 각 호출마다 다른 템플릿을 사용할 수도 있습니다.

관련 문서