suzuri-api

SUZURI API 参考文档

SUZURI（suzuri.jp）是由 GMO Pepabo 运营的按需印制服务。通过公开的 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，因此需要为每个环境分别注册应用。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 创建商品

创建带预览的商品流程

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 中包含含税最终价格。