pepabo 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
複数ユーザーがそれぞれ自分のアカウントで操作するアプリ向け。
GET https://suzuri.jp/oauth/authorizeにclient_id,scope,redirect_uri,response_type=codeを指定- ユーザー認可後、
redirect_uriにcodeが返る 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またはデータURIprice: トリブン（クリエイターの取り分）。0以上の整数products:itemIdはGET /api/v1/itemsで事前に取得するresizeMode:contain（フィット）/cover（埋め尽くし、一部アイテムのみ）- 刺繍アイテムなど、API経由での商品作成に非対応のItemがある
プレビュー付きグッズ作成フロー
POST /api/v1/materialsでグッズ作成- レスポンスの
sampleImageUrlでプレビュー表示 - 購入:
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 に税込最終価格が含まれる。