V1 Shop Configuration API

店铺配置模块用于获取 Access Token 所绑定的 Sugumart 店铺资料，以及获取和设置该 tenant 唯一的业务通知 URL。

概述

• 所有接口需要 Access Token，通过 Authorization: Bearer <access_token> 传递。
• 数据按 Token 绑定的卖家租户隔离。
• 客户端不能通过请求参数访问其他租户或店铺。
• 一个 Sugumart tenant 只能配置一个业务通知 URL，再次设置时覆盖原配置。
• 回调配置属于 tenant，不属于发起请求的开放应用。多个开放应用访问同一 tenant 时，读取和修改的是同一份配置。
• 本章的回调是 Sugumart 服务端发起的 Webhook，不是浏览器 OAuth redirect_uri。
• 订单和物流通知事件见业务通知。

Base Path: /openapi/v1/shop

---

获取店铺信息

GET /openapi/v1/shop/profile

Authentication: Required (Access Token)

获取当前 Access Token 所绑定的 Sugumart 店铺资料。

Response

字段	类型	说明
shop	Shop	当前店铺资料
token	TokenSummary	本次请求所使用的 Access Token 时间信息

Response Example

{
  "success": true,
  "data": {
    "token": {
      "issued_at": "2026-08-10T08:00:00.000Z",
      "expires_at": "2026-11-08T08:00:00.000Z"
    },
    "shop": {
      "id": "07c6a675-2997-4e63-bfa7-772c60c538b9",
      "name": "杉木生活选物",
      "status": "approved",
      "ruten_shop_id": "sugumart_tw",
      "primary_category": "0011",
      "email": "service@sugumart.example",
      "avatar": "https://static.sugumart.com/shops/sugumart-tw.png",
      "kyc_status": "approved",
      "created_at": "2026-05-11T03:20:00.000Z",
      "updated_at": "2026-08-01T06:15:00.000Z"
    }
  }
}

Error Responses

Status	message	code	说明
401	Invalid or expired token	invalid_token	Access Token 无效或已过期
403	Shop is not initialized	shop_not_initialized	店铺尚未完成 KYC 审核；Payoneer 未绑定不会触发此错误
403	Shop is suspended	shop_suspended	店铺已暂停或禁止使用 OpenAPI

---

获取回调配置

GET /openapi/v1/shop/callback

Authentication: Required (Access Token)

获取当前店铺唯一的回调配置。未设置回调时，callback 返回 null。

Response

字段	类型	说明
callback	Callback | null	当前回调配置；未设置时为 null

Response Example

{
  "success": true,
  "data": {
    "callback": {
      "url": "https://partner.example.com/webhooks/sugumart",
      "enabled": true,
      "created_at": "2026-07-20T08:00:00.000Z",
      "updated_at": "2026-08-04T08:00:00.000Z"
    }
  }
}

未设置回调时：

{
  "success": true,
  "data": {
    "callback": null
  }
}

响应不返回签名 Secret。Secret 只在设置回调成功时返回。

Error Responses

Status	message	code	说明
401	Invalid or expired token	invalid_token	Access Token 无效或已过期
404	Shop not found	shop_not_found	当前租户没有可用的 Sugumart 店铺

---

设置回调配置

POST /openapi/v1/shop/callback

Authentication: Required (Access Token)

设置当前店铺唯一的回调 URL。店铺已有配置时，本接口覆盖原配置并签发新的签名 Secret；旧 Secret 在设置成功后立即失效。

该 URL 接收全部 V1 商品审核、订单与物流通知，不支持为不同事件设置多个 URL。

Request Body

字段	类型	必填	说明
url	string	是	HTTP 或 HTTPS 回调 URL，最长 2048 字符，不得包含 fragment 或内嵌账号密码；正式环境建议 HTTPS
enabled	boolean	否	是否启用通知，默认 true

Request Example

{
  "url": "https://partner.example.com/webhooks/sugumart",
  "enabled": true
}

Response

字段	类型	说明
callback	Callback	设置后的唯一回调配置
secret	string	HMAC-SHA256 签名 Secret，仅本次响应返回

Response Example

{
  "success": true,
  "data": {
    "callback": {
      "url": "https://partner.example.com/webhooks/sugumart",
      "enabled": true,
      "created_at": "2026-08-04T08:00:00.000Z",
      "updated_at": "2026-08-04T08:00:00.000Z"
    },
    "secret": "sgm_whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

调用方必须安全保存 secret。也可以通过显式查看接口重新获取当前 Secret；再次设置回调会轮换 Secret，并使旧值立即失效。

查看回调签名 Secret

POST /openapi/v1/shop/callback/reveal-secret

Authentication: Required (Access Token)

显式查看当前店铺已经保存的签名 Secret。响应设置 Cache-Control: no-store；普通回调查询永远不会返回 Secret。

{
  "success": true,
  "data": {
    "secret": "sgm_whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

尚未配置时返回 404 callback_not_configured。Secret 不应写入浏览器持久化存储、前端源码或日志。

Error Responses

Status	message	code	说明
400	Invalid callback URL	invalid_callback_url	URL 不是有效 HTTP/HTTPS 地址，或包含不允许的内容
401	Invalid or expired token	invalid_token	Access Token 无效或已过期
404	Shop not found	shop_not_found	当前租户没有可用的 Sugumart 店铺
422	Validation failed	validation_error	请求字段校验失败
429	Too many requests	rate_limit_exceeded	请求频率超过限制

公共响应字段

公开响应字段统一使用 snake_case。因此 Token 到期时间为 expires_at， 资源更新时间为 updated_at；二者都使用 ISO 8601 UTC，但业务语义不同。

TokenSummary

字段	类型	说明
issued_at	string	Access Token 签发时间，ISO 8601 UTC
expires_at	string	Access Token 到期时间，ISO 8601 UTC

Shop

字段	类型	说明
id	string(uuid)	Sugumart 店铺 ID
name	string	店铺名称
status	string	店铺状态：draft、pending、approved、forbidden
ruten_shop_id	string | null	已绑定的露天商店编号；尚未绑定时为 null
primary_category	string | null	店铺审核通过的主营一级类目代码
email	string | null	店铺联系邮箱
avatar	string | null	店铺头像 URL
kyc_status	string	店铺 KYC 状态
created_at	string	店铺创建时间，ISO 8601 UTC
updated_at	string	店铺更新时间，ISO 8601 UTC

Callback

字段	类型	说明
url	string	唯一 HTTP 或 HTTPS 回调 URL；正式环境建议 HTTPS
enabled	boolean	是否创建新的通知投递任务
created_at	string	首次设置时间，ISO 8601 UTC
updated_at	string	最近设置时间，ISO 8601 UTC

注意事项

• 停用回调后不再创建新的投递任务；已经开始的投递不会撤回。
• 覆盖配置不会重新投递旧 URL 已经成功接收的事件。
• 新配置只影响设置成功后创建或重试的通知投递。
• 签名、事件格式、重试和幂等规则见业务通知。