suzuri-api

name	suzuri-api
description	SUZURI REST APIを使ったアプリケーション構築のガイド。SUZURI APIでグッズを作成・検索・表示するアプリや、SUZURIと連携するサービスを開発する際に使用する。「SUZURIのAPIで」「SUZURIで商品を」「SUZURIと連携」「スズリAPI」「suzuri.jpのAPI」などSUZURIに関連するアプリケーション開発の話題が出たら、このスキルを参照すること。

SUZURI API リファレンス

SUZURI（suzuri.jp）はGMOペパボが運営するプリントオンデマンドサービス。公開REST APIでオリジナルグッズの作成・検索・表示が可能。

最新のAPI仕様: https://suzuri.jp/developer/documentation/v1 アイテム別の推奨入稿画像サイズ: https://suzuri.jp/item_templates

このスキルはベースライン情報。実装時は上記の最新情報を優先する。

API概要

項目	値
ベースURL	https://suzuri.jp/api/v1
プロトコル	HTTPS必須
リクエスト形式	GET: クエリストリング、POST/PUT/DELETE: application/json
レスポンス形式	JSON
JSONスキーマ	GET https://suzuri.jp/api/v1/schema

認証

APIキー

自分のアカウントに紐づくアプリ向け。https://suzuri.jp/developer/apps で発行。

Authorization: Bearer {api_key}

スコープ: read（読み取り）/ write（作成・更新・削除）

注意: キー発行者自身の非公開商品も取得される。公開商品のみ扱う場合は published フィールドでフィルタする。

OAuth 2.0

複数ユーザーがそれぞれ自分のアカウントで操作するアプリ向け。

1. GET https://suzuri.jp/oauth/authorize に client_id, scope, redirect_uri, response_type=code を指定
2. ユーザー認可後、redirect_uri に code が返る
3. POST https://suzuri.jp/oauth/token で grant_type=authorization_code, code, redirect_uri, client_id, client_secret を送信（Content-Type: application/x-www-form-urlencoded）

アプリ登録は https://suzuri.jp/developer/apps で行う。コールバックURLはアプリに1つしか設定できないため、環境ごとに別のアプリ登録が必要。redirect_uri はHTTPS必須。

認証方式の選び方

観点	APIキー	OAuth
グッズ作成先	キー発行者のショップ	アプリユーザーのショップ
非公開グッズへのアクセス	発行者のもののみ	ユーザーのもの
用途	自分のショップ管理、個人ツール	マルチユーザーアプリ

リソース構造

Item（アイテム: Tシャツ、マグカップなど商品種類）
  └── ItemVariant（色・サイズの組み合わせ）

Material（素材: ユーザーがアップロードしたデザイン画像）
  └── Product（商品: Material × Item の組み合わせ）

Choice（オモイデ: 商品のコレクション）
  └── Product（商品を追加）

Favorite（ズッキュン: 商品へのいいね）

素材（Material）を作成すると、指定したアイテムに対して商品（Product）が自動生成される。素材を削除すると紐づく商品もすべて削除される。

エンドポイント一覧

詳細なパラメータやレスポンス形式は references/api-reference.md を参照。

操作	メソッド	エンドポイント
アイテム一覧	GET	/items
素材一覧	GET	/materials
素材作成	POST	/materials
テキスト素材作成	POST	/materials/text
素材更新	PUT	/materials/{id}
素材削除	DELETE	/materials/{id}
商品一覧	GET	/products
商品詳細	GET	/products/{id}
商品検索	GET	/products/search
セール商品	GET	/products/on_sale
オモイデ一覧	GET	/choices
オモイデ作成	POST	/choices
オモイデ更新	PUT	/choices/{id}
オモイデ削除	DELETE	/choices/{id}
ズッキュン一覧	GET	/products/{id}/favorites
ズッキュン追加	POST	/products/{id}/favorites
ズッキュン削除	DELETE	/products/{id}/favorites
ユーザー一覧	GET	/users
ユーザー詳細	GET	/users/{id}
自分の情報	GET	/user
アクティビティ	GET	/activities
未読数	GET	/activities/unreads

実装パターン

商品一覧を表示する

GET /api/v1/products?userName={your_name}
Authorization: Bearer {token}

• 商品画像: sampleImageUrl（WebP）推奨。imageUrl はテンプレートURLでパラメータ置換が必要
• 商品ページリンク: sampleUrl を使う

画像からグッズを作成する

POST /api/v1/materials
Content-Type: application/json
Authorization: Bearer {token}

{
  "texture": "https://example.com/image.png",
  "title": "デザイン名",
  "price": 100,
  "description": "説明文",
  "products": [
    { "itemId": 1, "published": true }
  ]
}

• texture: 画像URLまたはデータURI
• price: トリブン（クリエイターの取り分）。0以上の整数
• products: itemId は GET /api/v1/items で事前に取得する
• resizeMode: contain（フィット）/ cover（埋め尽くし、一部アイテムのみ）
• 刺繍アイテムなど、API経由での商品作成に非対応のItemがある

プレビュー付きグッズ作成フロー

1. POST /api/v1/materials でグッズ作成
2. レスポンスの sampleImageUrl でプレビュー表示
3. 購入: sampleUrl へ遷移 / 取り消し: DELETE /api/v1/materials/{id} で素材ごと削除

テキストからグッズを作成する

POST /api/v1/materials/text
Content-Type: application/json
Authorization: Bearer {token}

{
  "text": "Hello World",
  "itemVariantId": 123
}

• text: 255文字以内
• itemVariantId: 対象のアイテムバリエーションID

商品を検索する

GET /api/v1/products/search?q={keyword}&limit=20&offset=0

ページネーション

リストAPIは limit と offset をサポート。

• limit: 取得件数（デフォルト20〜30、最大50）
• offset: 開始位置（デフォルト0）
• meta.hasNext が true なら次のページが存在

レート制限

レスポンスヘッダで確認: X-Ratelimit-Limit / X-Ratelimit-Remaining / X-Ratelimit-Reset

対象エンドポイント: POST /materials, PUT /materials/{id}, POST /materials/text, POST /products/{id}/favorites

エラーハンドリング

HTTPステータスコードで判断する（レスポンスボディの内容は保証されない）。

コード	意味
200	成功
201	作成成功
204	成功（ボディなし）
401	認証エラー
40x	クライアントエラー
50x	サーバーエラー

画像URLテンプレート

sampleImageUrl を使えば置換不要。カスタムサイズが必要な場合は imageUrl の以下を置換:

• {width}x{height}: 画像サイズ
• {size}: サイズ指定
• {color}: 色指定
• [/angle]: 表示角度（front, backなど）

価格の計算

商品価格 = 素材のトリブン + アイテムバリエーション価格 + プリント箇所追加価格

APIレスポンスの priceWithTax に税込最終価格が含まれる。