홈▸개발문서▸워크플로우▸Step 2: Templates

Step 2: 템플릿 선택 및 이해

선택한 상품(BookSpec)에 맞는 템플릿을 조회하고, 파라미터 바인딩 방식을 이해하는 단계입니다. 템플릿의 종류, 파라미터 구조, 갤러리/컬럼 템플릿 사용법을 안내합니다.

템플릿 목록 조회

GET /templates로 사용 가능한 템플릿을 조회합니다. 반드시 bookSpecUid를 지정하여 해당 상품에 호환되는 템플릿만 필터링하세요.

bash
# SQUAREBOOK_HC용 표지 템플릿 조회
curl 'https://api.sweetbook.com/v1/templates?bookSpecUid=SQUAREBOOK_HC&templateKind=cover' \
  -H 'Authorization: Bearer YOUR_API_KEY'
bash
# SQUAREBOOK_HC용 내지 템플릿 조회
curl 'https://api.sweetbook.com/v1/templates?bookSpecUid=SQUAREBOOK_HC&templateKind=content' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Query Parameter필수설명
bookSpecUid권장상품 스펙 UID로 필터링 (예: SQUAREBOOK_HC)
templateKind권장cover (표지) 또는 content (내지)
category선택카테고리 필터 (예: diary, album, wedding)
limit, offset선택페이지네이션 (기본 limit: 50)

템플릿 종류: cover vs content

템플릿은 templateKind로 구분됩니다.

종류값용도적용 API
표지 템플릿cover책 표지 디자인. 책당 하나만 적용됩니다.POST /books/{bookUid}/cover
내지 템플릿content내지 페이지 디자인. 여러 번 적용 가능합니다.POST /books/{bookUid}/contents
표지에 내지 템플릿을 사용하거나, 내지에 표지 템플릿을 사용할 수 없습니다. 반드시 종류를 일치시키세요.

템플릿 상세 조회

GET /templates/{templateUid}로 특정 템플릿의 상세 정보를 확인합니다. 파라미터 정의, 레이아웃, 베이스 레이어 등이 포함됩니다.

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

파라미터 바인딩

템플릿의 parameters에 정의된 바인딩 유형에 따라 값을 전달합니다. 파라미터 이름은 $$이름$$ 형식으로 템플릿 내에서 참조됩니다.

텍스트 바인딩

템플릿 내 $$title$$, $$date$$ 등의 텍스트 플레이스홀더에 문자열 값을 전달합니다.

json
{
  "templateUid": "COVER_TEMPLATE_UID",
  "parameters": {
    "bookTitle": "우리 가족 앨범",
    "year": "2026"
  }
}

사진(file) 바인딩

$$photo1$$ 등의 이미지 플레이스홀더에 업로드된 사진의 fileName이나 URL을 전달합니다.

json
{
  "templateUid": "CONTENT_TEMPLATE_UID",
  "parameters": {
    "photo1": "uploaded_photo_abc123.jpg"
  }
}

갤러리(rowGallery) 바인딩

$$galleryPhotos$$ 등의 갤러리 플레이스홀더에 사진 파일명 배열을 전달합니다. 갤러리 템플릿은 전달된 사진 수에 따라 레이아웃이 동적으로 배치됩니다.

json
{
  "templateUid": "GALLERY_TEMPLATE_UID",
  "parameters": {
    "galleryPhotos": ["photo1.jpg", "photo2.jpg", "photo3.jpg", "photo4.jpg"]
  }
}
갤러리 바인딩에 사용할 사진은 먼저 POST /books/{bookUid}/photos로 업로드한 후, 반환된 fileName을 사용합니다.

템플릿 선택 기준

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

  • bookSpecUid 일치: 템플릿의 bookSpecUid가 생성한 책의 bookSpecUid와 일치해야 합니다.
  • templateKind 확인: 표지에는 cover, 내지에는 content 템플릿을 사용하세요.
  • 파라미터 확인: 상세 조회로 parameters를 확인하여 어떤 값을 전달해야 하는지 파악하세요.
  • 카테고리 활용: 서비스 용도에 맞는 카테고리로 필터링하면 적합한 템플릿을 빠르게 찾을 수 있습니다.

갤러리 템플릿 사용법

갤러리 템플릿은 전달된 사진 수에 따라 레이아웃이 자동으로 배치됩니다. 사진이 많으면 여러 페이지에 걸쳐 자동 분배되므로, 한 번의 API 호출로 다수의 사진을 효율적으로 배치할 수 있습니다.

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": "GALLERY_TEMPLATE_UID",
  "parameters": {
    "galleryPhotos": [
      "photo1.jpg", "photo2.jpg", "photo3.jpg",
      "photo4.jpg", "photo5.jpg", "photo6.jpg"
    ]
  }
}'
갤러리 템플릿의 동작 원리와 레이아웃 배치 규칙은 Gallery Templates 문서를 참고하세요.

컬럼 템플릿 사용법

컬럼 템플릿은 텍스트와 사진을 세로 방향으로 쌓아 배치합니다. 일기장, 알림장처럼 텍스트 분량이 가변적인 콘텐츠에 적합합니다. 텍스트 길이에 따라 레이아웃이 자동으로 조정됩니다.

컬럼 레이아웃의 상세 동작은 Column Layout 문서를 참고하세요.

다음 단계