V1 Shop Configuration API

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

概述

• 所有接口需要 Access Token，通过 Authorization: Bearer <access_token> 传递。
• 数据按 Token 绑定的卖家租户隔离。
• 客户端不能通过请求参数访问其他租户或店铺。
• 一个店铺只能配置一个回调 URL，再次设置时覆盖原配置。
• 订单和物流通知事件见回调通知。

Base Path: /openapi/v1/shop

---

获取店铺信息

GET /openapi/v1/shop/profile

Authentication: Required (Access Token)

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

Response

字段	类型	说明
shop	Shop	当前店铺资料

Response Example

{
  "success": true,
  "data": {
    "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 或支付绑定
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	是	HTTPS 回调 URL，最长 2048 字符，不得包含 fragment 或内嵌账号密码
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 遗失时，使用相同或新的 URL 再次调用本接口取得新 Secret，并同步更新接收端配置。

Error Responses

Status	message	code	说明
400	Invalid callback URL	invalid_callback_url	URL 不是有效 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	请求频率超过限制

公共响应字段

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	唯一 HTTPS 回调 URL
enabled	boolean	是否创建新的通知投递任务
created_at	string	首次设置时间，ISO 8601 UTC
updated_at	string	最近设置时间，ISO 8601 UTC

注意事项

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