Appearance
V1 Open API
V1 Open 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 认证。卖家应用通过系统浏览器完成注册或登录，回调只接收一次性授权码；应用后端使用 Client Secret 与 PKCE verifier 兑换 Access Token 和 Refresh Token。Access Token 默认有效期为 90 天；Refresh Token Family 从首次授权起绝对有效 120 天，采用单次轮换和重放检测，轮换不延长绝对期限。新 Token 需在卖家完成 KYC 审核和支付绑定后才能调用业务 API。
详见 认证与安全。
可运行的 Node.js 测试环境接入代码见 Authorization Code + PKCE 示例。
请求格式
- V1 API 仅使用
GET和POST：查询操作使用GET，创建、更新、状态变更和其他写操作统一使用POST。 - 请求体使用
application/json。 - 所有时间字段使用 ISO 8601 UTC 格式。
- 金额字段使用 decimal string，单位为币种主单位；TWD 固定 2 位小数。
- 列表接口使用
limit+offset；limit默认 20、最大 100。 - 默认频率限制为 60 次/分钟；超限返回
429 rate_limit_exceeded。 - 商品 SKU 编号
sku由平台生成并只读；更新已有 SKU 时使用商品详情返回的 SKU UUIDid。 - 曾经上架过的 SKU 不得删除，不再销售时通过
status=false停用。
响应格式
成功响应
所有 V1 API 成功响应使用统一信封。success 固定为 true，业务资源放在 data 中：
json
{
"success": true,
"data": {
"product": {
"id": "a1b2c3d4-1111-4222-8333-abcdef123456",
"status": "draft"
}
},
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}列表响应：
json
{
"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 相同。它只用于请求追踪或调用方幂等控制，不替代资源级业务幂等规则。
json
{
"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 |
| 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 |
| 店铺配置 | /openapi/v1/shop | 02-shop-config.md |
| 回调通知 | 店铺配置的唯一 HTTPS URL | 02-callback-notifications.md |
| 商品管理 | /openapi/v1/products | 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] 和最新正式版本章节。