V1 Open API

V1 Open API 是面向外部开发者的集成接口，允许第三方应用以标准化的方式接入平台核心业务能力。

接口开发状态统一维护在 API 大纲；第三方只应接入标记为“已完成”的接口。

Base URL

环境	API URL	Auth URL
生产	https://openapi.sugumart.com	https://auth.sugumart.com
测试	https://openapi.test.sugumart.com	https://auth.test.sugumart.com

业务接口 Base Path 为 /openapi/v1。

认证方式

V1 API 使用 Bearer Token 认证。公开应用通过系统浏览器完成 Authorization Code + PKCE 授权，可分别绑定多个店铺；私有应用固定绑定创建它的唯一店铺，使用 client_credentials 换取 Token。两类应用取得相同格式的 Access Token 和 Refresh Token，并调用同一套业务 API。Access Token 默认有效期为 90 天；Refresh Token Family 从首次授权起绝对有效 120 天，采用单次轮换和重放检测，轮换不延长绝对期限。新 Token 需在卖家完成 KYC 审核后才能调用业务 API；Payoneer 绑定状态不阻断 OpenAPI。

详见 认证与安全。

可运行的 Node.js 测试环境接入代码见公开应用 Authorization Code + PKCE 示例和私有应用 Client Credentials 示例。

请求格式

• V1 API 仅使用 GET 和 POST：查询操作使用 GET，创建、更新、状态变更和其他写操作统一使用 POST。
• 请求体使用 application/json。
• 公开 API 的 Path、Query、请求 JSON、响应 JSON 与回调 JSON 字段统一使用 snake_case，例如 issued_at、expires_at、created_at、updated_at； 不对外暴露 TypeScript 内部使用的 camelCase 字段名。
• 所有时间字段使用 ISO 8601 UTC 格式。
• 金额字段使用 decimal string，单位为币种主单位；TWD 固定 2 位小数。
• 列表接口使用 limit + offset；limit 默认 20、最大 100。
• 默认频率限制为 60 次/分钟；超限返回 429 rate_limit_exceeded。
• 商品 SKU 编号 sku 由平台生成并只读；更新已有 SKU 时使用商品详情返回的 SKU UUID id。
• 曾经上架过的 SKU 不得删除，不再销售时通过 status=false 停用。

响应格式

成功响应

所有 V1 API 成功响应使用统一信封。success 固定为 true，业务资源放在 data 中：

{
  "success": true,
  "data": {
    "product": {
      "id": "a1b2c3d4-1111-4222-8333-abcdef123456",
      "status": "draft"
    }
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

列表响应：

{
  "success": true,
  "data": {
    "products": [],
    "count": 100,
    "limit": 20,
    "offset": 0
  }
}

错误响应

错误响应使用同一信封。success 固定为 false，code 和 message 仅在失败时出现；需要返回安全的结构化辅助信息时使用 data。

request_id 是可选字段：仅当请求携带 X-SGM-Request-Id Header 时，响应 Body 才返回该字段，并与响应 Header X-Request-Id 相同。它只用于请求追踪或调用方幂等控制，不替代资源级业务幂等规则。

{
  "success": false,
  "code": "ERROR_CODE",
  "message": "Human-readable error description",
  "data": null,
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

字段	类型	说明
success	boolean	请求是否成功；成功为 true，失败为 false
data	object | null	成功时包含业务数据；失败时可选，可包含安全的结构化辅助信息
code	string	失败时必填的稳定机器可读错误码
message	string	失败时必填的人类可读错误说明；程序不得依赖文案分支
request_id	string	可选；请求携带 X-SGM-Request-Id 时返回，与响应 Header X-Request-Id 相同

HTTP Status Codes

Status	Meaning
200	Success
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
413	Content Too Large
422	Validation Error
429	Too Many Requests
500	Internal Server Error

分页

Parameter	Type	Default	Max	Description
limit	integer	20	100	Items per page
offset	integer	0	-	Number of items to skip

API 模块

模块	Base Path	文档
认证与安全	浏览器注册/登录与本地回调	01-auth.md
公开应用认证示例	Node.js、Authorization Code + PKCE、本地 HTTP 回调	example-code
私有应用认证示例	Node.js、Client Credentials、固定绑定店铺验证	private-app-example
店铺配置	/openapi/v1/shop	02-shop-config.md
业务通知	店铺配置的唯一通知 URL，支持单条与批量事件	02-callback-notifications.md
商品管理	/openapi/v1/products、/openapi/v1/product-create-tasks	03-products.md
类目与商品分类	/openapi/v1/categories、/openapi/v1/product-categories	03-categories.md
订单、物流与仓库	/openapi/v1/orders、/openapi/v1/warehouses	04-orders-logistics.md
状态附录	—	05-status-appendix.md
错误码	—	06-errors.md
版本变更记录	—	CHANGELOG.md

版本与兼容性

V1 的新增、调整、废弃和修复记录统一维护在 V1 OpenAPI Changelog。调用方升级前应检查 [Unreleased] 和最新正式版本章节。

共享测试环境账号

因为订单需要实际订单, 测试环境提供的账号提供少量具备信息的订单, 供开发者测试使用,如果登陆不上，联系 sugumart。

测试环境自己注册的账号只能创建和管理sugumart方的商品。

露天店铺：https://www.ruten.com.tw/store/pcstore_select_pet04

地址：https://seller.test.sugumart.com
账号：seller@sugumart.com 密码：share123456