开放平台（Open API）接入指南

在线文档（推荐）：https://docs.rizzitgo.com — API 参考与本文同步更新
适用对象：外部合作方 / 第三方开发者
语言版本：中文（本文） · English

本指南说明如何接入本系统的 /open-api/* 开放接口。开放接口与 C 端 /app-api、管理端 /admin-api 物理隔离，统一采用 OAuth2 client_credentials（客户端模式） 鉴权，并按 scope（授权范围）控制每个应用可调用的接口集合。

1. 概述与架构

• 鉴权模型：标准 OAuth2 客户端模式。合作方使用平台下发的 clientId + clientSecret 换取短期 access_token，再用令牌调用业务接口。开放平台不涉及用户登录、授权码、密码等模式。
• 接口隔离：所有开放接口挂载在 /open-api/** 前缀下，由网关独立路由。开放令牌的用户类型固定为 OPEN_API，无法访问 /admin-api、/app-api，从源头规避越权。
• 权限粒度：每个接口由其所需的 scope 控制（如商品详情接口需 goods:detail:read）。应用只能调用其被授予的 scope 对应的接口。
• 多租户：请求需携带 tenant-id，且必须与换取令牌时一致。

调用时序：

sequenceDiagram
    participant P as 合作方应用
    participant GW as API 网关
    participant SYS as 系统服务
    participant BIZ as 业务服务

    P->>GW: POST /open-api/system/oauth2/token<br/>Basic(clientId:clientSecret)
    GW->>SYS: 转发取令牌请求
    SYS-->>P: access_token（userType=OPEN_API, expires_in）
    P->>GW: POST /open-api/goods/detail<br/>Bearer access_token + tenant-id
    GW->>BIZ: 校验令牌 + scope 后转发
    BIZ-->>P: 业务数据（统一 {code,data,msg}）

2. 名词术语表

3. 接入流程

1. 联系平台运营，提交：合作方名称、联系人（姓名/邮箱/电话）、回调来源 IP（可选，用于 IP 白名单）、需要的接口范围（scope）。
2. 运营在管理后台「开放平台 / 合作方应用」创建应用，下发：
   • clientId（客户端编号）
   • clientSecret（客户端密钥，仅展示一次，请妥善保存）
   • 授权 scope 列表（如 goods:detail:read）
   • tenant-id（租户编号）
3. 合作方使用 clientId + clientSecret 换取 access_token，再携带令牌调用业务接口。

上线前自检清单：

• 已安全保存 clientSecret（建议放入密钥管理系统，禁止写入前端/客户端代码或日志）。
• 已确认所需 scope 均已开通。
• 调用方出口 IP 已加入白名单（若运营启用了白名单）。
• 已实现令牌缓存（按 expires_in 复用，避免每次请求都换取令牌）。
• 已实现 401 自动重新取令牌、429 退避重试。

3.1 Scope 权限列表（完整）

以下是平台当前支持的所有 scope，命名规范为 {domain}:{resource}:{action}。申请令牌时通过 scope 参数指定所需权限（空格分隔多个），未被授予的 scope 对应接口将返回 403。

说明：OAuth2 令牌接口（/open-api/system/oauth2/token 和 /token/revoke）本身不需要 scope，仅需 clientId + clientSecret 认证。scope 列表随业务扩展而增加，请以本文档最新版本为准。

4. 环境与域名

生产网关域名为 api.rizzitgo.com（文档示例已采用），测试/沙箱网关域名为 api-qa.rzdzht.me。{租户编号}、{clientId}、{clientSecret} 等占位符请替换为运营下发的实际值。

5. 获取访问令牌

• 方法与路径：POST /open-api/system/oauth2/token
• 认证：HTTP Basic，将 clientId:clientSecret 拼接后做 Base64 编码，放入 Authorization 头（即 Authorization: Basic base64(clientId:clientSecret)）。
• Content-Type：application/x-www-form-urlencoded

请求参数：

请求示例：

curl -X POST 'https://api.rizzitgo.com/open-api/system/oauth2/token' \
  -H 'Authorization: Basic {base64(clientId:clientSecret)}' \
  -H 'tenant-id: {租户编号}' \
  -d 'grant_type=client_credentials' \
  -d 'scope=goods:detail:read'

响应字段：

响应示例：

{
  "code": 0,
  "data": {
    "access_token": "xxxxxxxx",
    "refresh_token": "",
    "token_type": "Bearer",
    "expires_in": 1800,
    "scope": "goods:detail:read"
  },
  "msg": ""
}

说明：开放平台仅支持 client_credentials；传入其它 grant_type（如 authorization_code/password/refresh_token）会返回 400，提示「开放平台仅支持 client_credentials 授权模式」。令牌的 userType 固定为 OPEN_API，无法访问 /admin-api、/app-api 接口。

6. 调用业务接口

所有业务请求需带：

7. 接口参考

7.1 查询商品详情（试点）

• 方法与路径：POST /open-api/goods/detail
• 所需 scope：goods:detail:read

请求参数（application/json）：

请求示例：

curl -X POST 'https://api.rizzitgo.com/open-api/goods/detail' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"goodsId":"123456","source":1}'

响应字段：

skuList 元素字段：

skuSpecInfoList 元素字段：

响应示例：

{
  "code": 0,
  "data": {
    "goodsId": "123456",
    "goodsTitle": "示例商品",
    "goodsDetailUrl": "https://example.com/item/123456",
    "goodsPicUrl": "https://example.com/img/123456.jpg",
    "price": "99.00",
    "priceInCents": 9900,
    "orginalPrice": "129.00",
    "stockNum": "1000",
    "salesCount": "532",
    "goodsImageUrlList": [
      "https://example.com/img/1.jpg",
      "https://example.com/img/2.jpg"
    ],
    "postFee": "0.00",
    "goodsSource": 1,
    "skuList": [
      {
        "skuId": "5001",
        "specId": null,
        "price": "99.00",
        "priceInCents": 9900,
        "salePrice": "99.00",
        "salePriceInCents": 9900,
        "quantity": 100,
        "imageUrl": "https://example.com/img/sku-5001.jpg",
        "propertiesId": "1627207:28341",
        "propertiesName": "颜色:红色;尺码:M"
      }
    ],
    "skuSpecInfoList": [
      {
        "skuSpecName": "颜色",
        "skuSpecList": [
          { "pid": "1627207", "vid": "28341", "pname": "颜色", "vname": "红色", "icon": null }
        ]
      }
    ]
  },
  "msg": ""
}

7.2 查询商品质检详情

• 方法与路径：POST /open-api/goods/qc-detail
• 所需 scope：goods:qc:read

请求参数（application/json）：

请求示例：

curl -X POST 'https://api.rizzitgo.com/open-api/goods/qc-detail' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"goodsId":"123456","source":1}'

响应字段：

说明：出于内部信息保护，质检接口不返回质检员/拍照员的 ID 与姓名等员工信息。

响应示例：

{
  "code": 0,
  "data": {
    "goodsId": "123456",
    "qcPathList": [
      "https://example.com/qc/1.jpg",
      "https://example.com/qc/2.jpg"
    ],
    "length": "30",
    "width": "20",
    "height": "10",
    "weight": "500",
    "volume": "6000",
    "completionTime": "2026-06-02 18:30:00"
  },
  "msg": ""
}

7.3 查询商品质检图片列表

• 方法与路径：POST /open-api/goods/qc-images
• 所需 scope：goods:qc:read
• 请求参数：同 7.2（goodsId + source）

请求示例：

curl -X POST 'https://api.rizzitgo.com/open-api/goods/qc-images' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"goodsId":"123456","source":1}'

响应示例： data 为质检图片地址数组。

{
  "code": 0,
  "data": [
    "https://example.com/qc/1.jpg",
    "https://example.com/qc/2.jpg"
  ],
  "msg": ""
}

7.4 按时间分页查询质检数据

• 方法与路径：POST /open-api/goods/qc-page
• 所需 scope：goods:qc:read

请求参数（application/json）：

请求示例：

curl -X POST 'https://api.rizzitgo.com/open-api/goods/qc-page' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{
        "pageNo": 1,
        "pageSize": 10,
        "completionTime": ["2026-06-01 00:00:00", "2026-06-02 23:59:59"]
      }'

响应字段： data.list 为质检详情数组（字段同 7.2），data.total 为总条数。

{
  "code": 0,
  "data": {
    "list": [
      {
        "goodsId": "123456",
        "qcPathList": ["https://example.com/qc/1.jpg"],
        "length": "30",
        "width": "20",
        "height": "10",
        "weight": "500",
        "volume": "6000",
        "completionTime": "2026-06-02 18:30:00"
      }
    ],
    "total": 1
  },
  "msg": ""
}

7.5 图片识别搜索商品列表

• 方法与路径：POST /open-api/goods/search-by-images
• 所需 scope：goods:search:read

请求参数（application/json）：

请求示例：

curl -X POST 'https://api.rizzitgo.com/open-api/goods/search-by-images' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"imagesUrl":"https://example.com/img/query.jpg","page":1,"source":1}'

响应字段：

goodsList 元素字段：

说明：出于内部信息保护，开放接口不返回会员维度的收藏状态、个性化分享链接等内部字段。

响应示例：

{
  "code": 0,
  "data": {
    "goodsList": [
      {
        "goodsId": "123456",
        "goodsTitle": "示例商品",
        "goodsDetailUrl": "https://example.com/item/123456",
        "goodsPicUrl": "https://example.com/img/123456.jpg",
        "goodsSource": 1,
        "price": "99.00",
        "priceInCents": 9900,
        "originPriceInCents": 9900,
        "salesCount": "532",
        "hasDiscount": true,
        "discountPriceInCents": 8900
      }
    ],
    "page": 1,
    "size": 20,
    "totalPage": 5,
    "totalCount": 100
  },
  "msg": ""
}

7.6 商品链接解析

• 方法与路径：POST /open-api/goods/search-url-parse
• 所需 scope：goods:search:read
• 说明：解析淘宝/天猫、1688、微店及常见代购站（cssbuy、cnfans、hoobuy 等）的短链或长链，提取平台商品 ID 与来源。无法识别的链接返回「商品链接解析失败」。

请求参数（application/json）：

请求示例：

curl -X POST 'https://api.rizzitgo.com/open-api/goods/search-url-parse' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"searchUrl":"https://detail.tmall.com/item.htm?id=768650559131","rno":"ABC123"}'

响应字段：

响应示例：

{
  "code": 0,
  "data": {
    "goodsId": "768650559131",
    "goodsSource": 1,
    "goodsSourceName": "taobao",
    "goodsDetailUrl": "https://detail.tmall.com/item.htm?id=768650559131",
    "targetGoodsDetailUrl": "https://www.rizzitgo.com/detailPage?goodsId=768650559131&source=1&rno=ABC123",
    "success": true,
    "searchUrl": "https://detail.tmall.com/item.htm?id=768650559131"
  },
  "msg": ""
}

7.7 优惠券随机兑换（按邮箱或 Discord 用户 ID 发券）

• 方法与路径：POST /open-api/promotion/redeem-code/redeem
• 所需 scope：promotion:redeem-code:redeem
• 说明：使用平台后台预先配置好的兑换码（可绑定 N 张优惠券模板，并按权重随机命中一张），为指定会员发放优惠券。会员标识为 email 与 discordUserId 二选一（至少传一个）；两者都传时只用 Discord，不回落到邮箱。会员必须已存在（邮箱精确匹配，或 Discord 已绑定会员），否则返回「会员不存在」，本接口不会自动创建会员。

请求参数（application/json）：

按邮箱请求示例：

curl -X POST 'https://api.rizzitgo.com/open-api/promotion/redeem-code/redeem' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"code":"E602F4DC626E4948","email":"[email protected]","requestId":"REQ-20260604-0001"}'

按 Discord 用户 ID 请求示例：

curl -X POST 'https://api.rizzitgo.com/open-api/promotion/redeem-code/redeem' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"code":"E602F4DC626E4948","discordUserId":"123456789012345678","requestId":"REQ-20260824-0001"}'

响应字段：

coupons 元素字段：

响应示例：

{
  "code": 0,
  "data": {
    "code": "E602F4DC626E4948",
    "email": "[email protected]",
    "discordUserId": null,
    "prize": "30% OFF",
    "success": true,
    "message": "兑换成功，共获得 1 张优惠券",
    "coupons": [
      {
        "templateId": 1001,
        "title": "满100减10",
        "couponType": 2,
        "discountType": 1,
        "discountPrice": 1000,
        "discountPercent": null,
        "usePriceCondition": 10000,
        "validStartTime": "2026-06-01 00:00:00",
        "validEndTime": "2026-06-30 23:59:59"
      }
    ]
  },
  "msg": ""
}

业务错误：email 与 discordUserId 都未传返回「邮箱与 Discord 用户 ID 至少传一个」；按邮箱或 Discord 查不到会员（含 Discord 未绑定、会员已删除）返回「会员不存在」；兑换码不存在/已过期/已作废、超过每人或每日（含 IP）限兑次数等，沿用兑换码模块既有错误码与提示。兑换码的限领/限兑/有效期等限制在后台配置，请按运营约定的额度调用。

7.8 用户优惠券查询 / 续期 / 恢复

通过邮箱、会员编号（unionId）或用户 ID 定位会员，查询其优惠券列表；对未使用券续期、对已失效券恢复。三个接口的用户标识规则一致：三选一，优先级 userId > unionId > email。

优惠券状态编码（请求与响应均为字符串，非数字）：

7.8.1 分页查询用户优惠券

• 方法与路径：POST /open-api/promotion/member-coupon/page
• 所需 scope：promotion:member-coupon:read

请求参数（application/json）：

响应 data 结构：

list 元素主要字段：id、templateId、title、code、status（字符串编码）、couponType、discountType、discountPrice、discountPercent、usePriceCondition、validStartTime、validEndTime、useTime、takeTime。

请求示例：

curl -X POST 'https://api.rizzitgo.com/open-api/promotion/member-coupon/page' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","status":"EXPIRE","pageNo":1,"pageSize":10}'

7.8.2 续期未使用优惠券

• 方法与路径：POST /open-api/promotion/member-coupon/extend
• 所需 scope：promotion:member-coupon:extend
• 说明：仅 status=UNUSED 的券可续期；在原有 validEndTime 基础上延长（若已过期则从当前时间起算）。

响应 data： successCount（成功数量）、coupons（含 id、status、validEndTime）。

7.8.3 恢复已失效优惠券

• 方法与路径：POST /open-api/promotion/member-coupon/restore
• 所需 scope：promotion:member-coupon:restore
• 说明：仅 status=EXPIRE 的券可恢复；恢复后状态变为 UNUSED，并按后台配置重设有效期（默认 15 天）。

响应 data： successCount、coupons（id、status 为 UNUSED、validEndTime）。

业务错误：1_013_024_000 未提供用户标识；1_013_024_001 会员不存在；1_013_024_002 券不属于该用户；1_013_024_003 状态编码无效；1_013_024_004 恢复时券非 EXPIRE；续期非 UNUSED 时返回 1_013_003_005。

7.9 推广者电子表格商品分页查询

通过推广码 rno 指定推广者，分页查询其电子表格（分享商品列表）。可选按自定义分类、关键字、商品来源、价格区间及排序方式筛选。

• 方法与路径：POST /open-api/promotion/spreadsheet/page
• 所需 scope：promotion:spreadsheet:read

请求参数（application/json）：

响应 data 结构：

list 元素主要字段：

请求示例：

curl -X POST 'https://api.rizzitgo.com/open-api/promotion/spreadsheet/page' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"rno":"ABC123","categoryCode":"cat_001","pageNo":1,"pageSize":10}'

业务错误：1_013_025_000 未传 rno；1_013_007_000 推广者不存在（rno 无效）。

8. 撤销令牌（可选）

• 方法与路径：POST /open-api/system/oauth2/token/revoke
• 认证：同获取令牌（HTTP Basic）
• 参数：token={access_token}（application/x-www-form-urlencoded）

curl -X POST 'https://api.rizzitgo.com/open-api/system/oauth2/token/revoke' \
  -H 'Authorization: Basic {base64(clientId:clientSecret)}' \
  -H 'tenant-id: {租户编号}' \
  -d 'token={access_token}'

9. 统一响应结构与错误码

所有接口统一返回结构 { code, data, msg }：code = 0 表示成功，其余为失败，msg 为提示信息。

高频错误：

10. 安全与限制

• IP 白名单：如运营为应用配置了 ipWhitelist（逗号分隔，多个 IP），仅白名单内来源 IP 可调用；为空表示不限制。
• 限流：可按应用配置每秒 QPS（rateLimitQps，0 表示不限）。超限返回 429。
• 密钥保管：clientSecret 仅展示一次；切勿写入前端/客户端代码、日志或版本库。如泄漏请立即联系运营在「合作方应用」中「重置密钥」，旧密钥即时失效。
• 令牌缓存与并发刷新：请在客户端缓存 access_token，在 expires_in 内复用，避免高频换取令牌；建议在过期前留出缓冲（如剩余 < 60s 时提前刷新），并对刷新过程加锁，防止并发重复换取。
• 重试与退避：遇 401 自动重新取令牌并重试一次；遇 429/网络抖动采用指数退避（如 1s、2s、4s）重试，设上限。
• 多租户：请求务必携带与令牌一致的 tenant-id，避免跨租户访问被拒绝。

11. 代码示例（取令牌 → 调商品详情）

cURL

# 1) 取令牌
TOKEN=$(curl -s -X POST 'https://api.rizzitgo.com/open-api/system/oauth2/token' \
  -H 'Authorization: Basic {base64(clientId:clientSecret)}' \
  -H 'tenant-id: {租户编号}' \
  -d 'grant_type=client_credentials' \
  -d 'scope=goods:detail:read' | jq -r '.data.access_token')

# 2) 调商品详情
curl -X POST 'https://api.rizzitgo.com/open-api/goods/detail' \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"goodsId":"123456","source":1}'

Java（JDK 11+ HttpClient）

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class OpenApiDemo {

    static final String GATEWAY = "https://api.rizzitgo.com";
    static final String TENANT_ID = "{租户编号}";
    static final String CLIENT_ID = "{clientId}";
    static final String CLIENT_SECRET = "{clientSecret}";

    public static void main(String[] args) throws Exception {
        HttpClient http = HttpClient.newHttpClient();

        // 1) 取令牌
        String basic = Base64.getEncoder()
                .encodeToString((CLIENT_ID + ":" + CLIENT_SECRET).getBytes());
        HttpRequest tokenReq = HttpRequest.newBuilder()
                .uri(URI.create(GATEWAY + "/open-api/system/oauth2/token"))
                .header("Authorization", "Basic " + basic)
                .header("tenant-id", TENANT_ID)
                .header("Content-Type", "application/x-www-form-urlencoded")
                .POST(HttpRequest.BodyPublishers.ofString(
                        "grant_type=client_credentials&scope=goods:detail:read"))
                .build();
        HttpResponse<String> tokenResp = http.send(tokenReq, HttpResponse.BodyHandlers.ofString());
        System.out.println(tokenResp.body());
        // 实际项目中请用 JSON 库解析 data.access_token
        String accessToken = "<从 tokenResp 解析 data.access_token>";

        // 2) 调商品详情
        HttpRequest bizReq = HttpRequest.newBuilder()
                .uri(URI.create(GATEWAY + "/open-api/goods/detail"))
                .header("Authorization", "Bearer " + accessToken)
                .header("tenant-id", TENANT_ID)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(
                        "{\"goodsId\":\"123456\",\"source\":1}"))
                .build();
        HttpResponse<String> bizResp = http.send(bizReq, HttpResponse.BodyHandlers.ofString());
        System.out.println(bizResp.body());
    }
}

Python（requests）

import base64
import requests

GATEWAY = "https://api.rizzitgo.com"
TENANT_ID = "{租户编号}"
CLIENT_ID = "{clientId}"
CLIENT_SECRET = "{clientSecret}"

# 1) 取令牌
basic = base64.b64encode(f"{CLIENT_ID}:{CLIENT_SECRET}".encode()).decode()
token_resp = requests.post(
    f"{GATEWAY}/open-api/system/oauth2/token",
    headers={"Authorization": f"Basic {basic}", "tenant-id": TENANT_ID},
    data={"grant_type": "client_credentials", "scope": "goods:detail:read"},
)
access_token = token_resp.json()["data"]["access_token"]

# 2) 调商品详情
biz_resp = requests.post(
    f"{GATEWAY}/open-api/goods/detail",
    headers={
        "Authorization": f"Bearer {access_token}",
        "tenant-id": TENANT_ID,
        "Content-Type": "application/json",
    },
    json={"goodsId": "123456", "source": 1},
)
print(biz_resp.json())

12. 跨境支付接口

scope：pay:order:create、pay:order:query、pay:exchange-rate:read

12.1 三种单号说明

12.2 查单优先级

query 接口三个单号至少传一个，若传多个按以下优先级查询：

1. orderNo（平台单号，索引最优）
2. outOrderNo（调用方单号，需配合 OAuth client 隔离）
3. paymentOrderId（渠道单号）

推荐合作方使用 outOrderNo 查单，无需记忆平台或渠道单号。

12.3 创建支付单 — POST /open-api/pay/order/create

请求示例：

{
  "outOrderNo": "DG-20260616-001",
  "payAmount": 199.00,
  "subject": "代购订单 #12345",
  "shippingInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "country": "US",
    "addressLine": "123 Main St",
    "city": "New York",
    "zipcode": "10001",
    "phone": "4049526852",
    "email": "[email protected]",
    "callingCodeCountry": "US",
    "callingCode": "1"
  }
}

shippingInfo 字段（传入时全部必填）：

响应示例：

{
  "code": 0,
  "data": {
    "orderNo": "OP1930268730012345",
    "outOrderNo": "DG-20260616-001",
    "paymentOrderId": "KML12345678",
    "paymentUrl": "https://www.kamelnet.com/pay/xxx",
    "payAmount": 199.00,
    "payCurrency": "USD"
  }
}

幂等：同一 outOrderNo 重复请求，若原单未关闭则直接返回已有订单信息，不会重复创建。

12.4 查询支付单 — POST /open-api/pay/order/query

请求示例（三选一）：

{ "outOrderNo": "DG-20260616-001" }

响应示例：

{
  "code": 0,
  "data": {
    "paid": true,
    "status": 10,
    "paidTime": "2026-06-16T20:30:00",
    "orderNo": "OP1930268730012345",
    "outOrderNo": "DG-20260616-001",
    "paymentOrderId": "KML12345678",
    "payAmount": 199.00,
    "payCurrency": "USD"
  }
}

待支付订单查询时，系统会自动实时向渠道确认支付状态。

12.5 分页查询支付单列表 — POST /open-api/pay/order/page

与 /query 的区别：列表接口不会实时向渠道同步状态，仅查本地库，适合批量拉取和报表场景。

请求示例：

{
  "pageNo": 1,
  "pageSize": 10,
  "status": 10,
  "outOrderNo": "DG-2026",
  "createTime": ["2026-06-01 00:00:00", "2026-06-30 23:59:59"]
}

响应示例：

{
  "code": 0,
  "data": {
    "list": [
      {
        "paid": true,
        "status": 10,
        "paidTime": "2026-06-16T20:30:00",
        "orderNo": "OP1930268730012345",
        "outOrderNo": "DG-20260616-001",
        "paymentOrderId": "KML12345678",
        "payAmount": 199.00,
        "payCurrency": "USD",
        "createTime": "2026-06-16T18:00:00"
      }
    ],
    "total": 1
  }
}

数据按 OAuth client 隔离，仅返回当前调用方名下的订单。默认按创建时间倒序排列。

12.6 系统汇率列表 — POST /open-api/pay/exchange-rate/list

• 所需 scope：pay:exchange-rate:read
• operationId：PayExchangeAPI
• 请求：无需 Body（可发送空 JSON {}）

返回全部启用币种的后台配置系统汇率。基准货币为 CNY：1 CNY = exchangeRate 该币种。本接口不返回实时汇率，也不按国家/客户溢价策略改写汇率。

换算：金额_外币 = 金额_CNY × exchangeRate（例如 CNY 100、USD exchangeRate = 0.14 → USD 14）。

请求示例：

curl -X POST 'https://api.rizzitgo.com/open-api/pay/exchange-rate/list' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{}'

响应 data 字段：

响应示例：

{
  "code": 0,
  "data": [
    {
      "name": "人民币",
      "abbreviationCode": "CNY",
      "symbol": "¥",
      "exchangeRate": 1
    },
    {
      "name": "美元",
      "abbreviationCode": "USD",
      "symbol": "$",
      "exchangeRate": 0.140000
    }
  ]
}

13. 代购下单与余额支付

scope：system:partner-member:read、order:purchase:quote、order:purchase:create、order:purchase:query、order:purchase:supplement-pay、pay:wallet:query、pay:wallet:pay

第三方平台（如 Shopify）代会员下单并扣其余额。金额字段单位均为人民币分。商品价以服务端实时抓取为准，调用方传入的价格会被忽略。

前置条件：运营在管理后台「开放平台 / 会员绑定」把合作方 externalUserId 绑到平台会员。绑定默认会开启补款授权，买手补款时系统可自动扣余额。

推荐调用顺序：

1. POST /open-api/system/oauth2/token
2. POST /open-api/system/partner-member/query（可选，确认已绑定）
3. POST /open-api/order/purchase/quote
4. POST /open-api/order/purchase/create（outOrderNo 幂等）
5. POST /open-api/pay/wallet/pay（使用上一步返回的 paymentId）

补款不是下单必经步骤。授权开启且余额充足时由系统自动扣；失败后再走 supplement/list → supplement/trade-no → wallet/pay。

商品来源 platformChannel：1 淘宝，2 1688，3 微店，5 闲鱼。

13.1 查询会员绑定 — POST /open-api/system/partner-member/query

• 所需 scope：system:partner-member:read
• operationId：QueryMemberBindAPI

未绑定或已停用会返回业务异常，便于下单前校验。

请求： { "externalUserId": "shopify_10086" }

响应 data： externalUserId、memberUnionId（会员编码，便于人工核对）、bound（true 表示可用）。

curl -X POST 'https://api.rizzitgo.com/open-api/system/partner-member/query' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"externalUserId":"shopify_10086"}'

13.1.1 查询绑定列表 — POST /open-api/system/partner-member/list

• 所需 scope：system:partner-member:read（与单条查询共用）
• operationId：QueryMemberBindListAPI

无请求参数。根据访问令牌识别当前合作方，返回该合作方下全部绑定关系（含停用）及对应会员钱包余额。无绑定时 data 为空数组。平台会员编号不对外暴露。钱包查询失败时余额按 0 返回，不影响绑定列表。

响应 data[]： externalUserId、memberUnionId、status（0=正常，1=停用）、balance（可用余额，分）、freezePrice（冻结，分）、currencyCode（固定 CNY）。

curl -X POST 'https://api.rizzitgo.com/open-api/system/partner-member/list' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json'

13.2 询价 — POST /open-api/order/purchase/quote

• 所需 scope：order:purchase:quote
• operationId：PurchaseQuoteAPI

不产生订单。返回应付金额供展示；下单时请把 payAmount 回传为 expectedPayAmount，避免用过期报价成交。

请求：

响应 data 主要字段： goodsTotalAmount、freightTotalAmount、payAmount、currencyCode（固定 CNY）、shops[]（按店铺拆分的明细）。

curl -X POST 'https://api.rizzitgo.com/open-api/order/purchase/quote' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"externalUserId":"shopify_10086","items":[{"platformChannel":1,"goodsId":"654321","skuId":"5001","qty":2}]}'

13.3 创建代购单 — POST /open-api/order/purchase/create

• 所需 scope：order:purchase:create
• operationId：PurchaseCreateAPI

同一合作方下 outOrderNo 幂等：已创建成功则回放原单（duplicated=true），不会重复下单。

请求：

响应 data： outOrderNo、orderNo、paymentId、payAmount、expireTime、duplicated。

curl -X POST 'https://api.rizzitgo.com/open-api/order/purchase/create' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"outOrderNo":"SHOPIFY-20260811-0001","externalUserId":"shopify_10086","expectedPayAmount":24600,"items":[{"platformChannel":1,"goodsId":"654321","skuId":"5001","qty":2}]}'

13.4 查询代购单 — POST /open-api/order/purchase/query

• 所需 scope：order:purchase:query
• operationId：PurchaseQueryAPI

outOrderNo 与 orderNo 二选一。只返回本合作方创建的订单。

响应 data： paymentId、payAmount、refStatus（0 处理中 / 1 已创建 / 2 创建失败）、orders[] 子订单（按店铺拆分）。

13.5 查询会员余额 — POST /open-api/pay/wallet/balance

• 所需 scope：pay:wallet:query
• operationId：WalletBalanceAPI

请求： { "externalUserId": "shopify_10086" }

响应 data： balance（可用余额，分）、freezePrice（冻结，分）、currencyCode（CNY）。

13.6 余额支付 — POST /open-api/pay/wallet/pay

• 所需 scope：pay:wallet:pay
• operationId：WalletPayAPI

扣款前会校验业务单仍可支付，避免订单已取消仍扣余额。已支付的 paymentId 会报错，请改查单确认结果。

请求：

响应 data： status（0 未支付 / 10 成功 / 20 已退款 / 30 关闭）、paySuccess、payAmount、successTime、balance（扣款后剩余余额）。

curl -X POST 'https://api.rizzitgo.com/open-api/pay/wallet/pay' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"externalUserId":"shopify_10086","paymentId":"P2026081100001","payAmount":24600}'

13.7 查询待补款 — POST /open-api/order/purchase/supplement/list

• 所需 scope：order:purchase:query
• operationId：PurchaseSupplementListAPI

仅在自动扣款失败时需要。返回代购单与包裹单的待补款费用行。

请求： { "externalUserId": "shopify_10086" }

响应 data： supplementTotalAmount、orders[]。单据类型 bizType：1 代购单，2 包裹单。费用类型 expenseType：102 商品补款，104 运费补款，203 包裹运费补款。记下 orderExpensesNo 用于下一步。

13.8 创建补款支付单 — POST /open-api/order/purchase/supplement/trade-no

• 所需 scope：order:purchase:supplement-pay
• operationId：PurchaseSupplementTradeNoAPI

代购单补款与包裹补款须分别发起，不要混在同一次请求。返回的 paymentId 再调用 wallet/pay。

请求： { "externalUserId": "shopify_10086", "orderExpensesNoList": ["OE2026081100001"] }

响应 data： paymentId、payAmount、payType（3 补运费 / 6 商品补款 / 7 包裹补款 / 8 商品+运费补款）。

14. 订单与包裹接口

scope：order:bag-order:read、order:order-item:read

分页列表接口须指定会员：memberId 与 unionId 至少传一个。金额字段（price / actualPrice / freightFee / goodsTotalAmount）单位为人民币分。

14.1 按包裹单号查询 — POST /open-api/order/bag-order/query

• 所需 scope：order:bag-order:read

请求：

{ "bagOrderNo": "BG20250624001" }

响应 data 主要字段：

包裹状态 status：

请求示例：

curl -X POST 'https://api.rizzitgo.com/open-api/order/bag-order/query' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"bagOrderNo":"BG20250624001"}'

14.2 分页查询包裹列表 — POST /open-api/order/bag-order/page

• 所需 scope：order:bag-order:read

响应 list 元素主要字段： bagOrderNo、outboundOrderNo、status、statusDesc、goodsQty、goodsTotalAmount（分）、estimateWeight、estimateVolume、unionId、createTime。

curl -X POST 'https://api.rizzitgo.com/open-api/order/bag-order/page' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"unionId":"M123456","pageNo":1,"pageSize":10}'

14.3 分页查询商品订单明细 — POST /open-api/order/order-item/page

• 所需 scope：order:order-item:read

响应 list 元素主要字段： orderNo、orderItemNo、status、unionId、goodsName、localGoodsName、specName、localSpecName、imagePath、qty、price、actualPrice、freightFee、shopName、localShopName、createTime。

常用明细状态 status（完整枚举以 Redoc 与后台状态为准）：

curl -X POST 'https://api.rizzitgo.com/open-api/order/order-item/page' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"unionId":"M123456","pageNo":1,"pageSize":10}'

15. 物流轨迹查询

• 方法与路径：POST /open-api/logistics/track/query
• 所需 scope：logistics:track:query

国内（type=1）与国际（type=2）统一入口。国内建议传 carrierName 提高识别率；国际可用 language（如 zh / en / es）指定轨迹翻译语言。

响应 data 通用字段： trackingNo、type、status、trackContent、trackDate、trackItems（currentPosition、content、trackDate、status）。

轨迹状态 status：PENDING 待发出、IN_TRANSIT 运输中、DELIVERING 派送中、DELIVERED 已签收、EXCEPTION 异常。

国内扩展：carrierName、carrierCode、checkStatus、arrivalTime。
国际扩展：logisticsOrderNo、expressNo、lastMileTrackingNo、supplierCode、supplierName、logisticsLineName、trackUrl、shipCountry、country。

curl -X POST 'https://api.rizzitgo.com/open-api/logistics/track/query' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"trackingNo":"YT9876543210","type":1,"carrierName":"圆通快递"}'

15.1 运费估算 — POST /open-api/logistics/line/freight-estimate

• 所需 scope：logistics:freight-estimate:read
• operationId：FreightEstimateAPI

按目的国与重量估算可用航线运费。只返回 可用 航线；totalFee 为系统运费（人民币分，不含 C 端促销）。本期请求仅支持国家和重量（不计尺寸、省份、邮限类型）。language 不传时航线名称为英文；传入时用谷歌翻译 lineName。

请求：

响应 data 列表字段：

curl -X POST 'https://api.rizzitgo.com/open-api/logistics/line/freight-estimate' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"US","weight":1000}'

响应示例：

{
  "code": 0,
  "data": [
    {
      "id": 7785,
      "lineUUid": "a1b2c3d4",
      "lineName": "US-EMS",
      "icon": "https://cdn.rizzitgoo.com/line/ems.png",
      "referenceTime": "7-12 days",
      "totalFee": 8800,
      "billingType": 1
    }
  ]
}

16. Discord 授权登录链接

• 方法与路径：POST /open-api/member/auth/discord-authorize-url
• 所需 scope：member:auth:discord-login

用于合作方（如 Discord 机器人）向用户下发平台 Discord OAuth 登录链接。redirectUri 必须是 https:// 地址，且与 Discord Developer Portal 已登记的 Redirect 完全一致。

请求：

{ "redirectUri": "https://rizzitgo.com" }

响应 data： authorizeUrl（Discord 授权 URL，可直接发送给用户）。

curl -X POST 'https://api.rizzitgo.com/open-api/member/auth/discord-authorize-url' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"redirectUri":"https://rizzitgo.com"}'

16.1 查询 Discord 登录状态

• 方法与路径：POST /open-api/member/auth/discord-login-status
• 所需 scope：member:auth:discord-login

按 Discord 用户 ID（snowflake，对应社交用户 openid）查询该账号是否已绑定会员。未登录时仍返回 HTTP 200，loggedIn=false，便于机器人轮询。绑定存在但会员已删除时同样视为未登录。

请求：

{ "discordUserId": "123456789012345678" }

响应 data：

curl -X POST 'https://api.rizzitgo.com/open-api/member/auth/discord-login-status' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"discordUserId":"123456789012345678"}'

16.2 Discord 每日签到

• 方法与路径：POST /open-api/promotion/discord-checkin
• 所需 scope：promotion:discord-checkin:claim
• 说明：按 Discord 用户 ID 为已绑定会员代兑平台配置的余额兑换码，将签到奖励入账到会员钱包。合作方不传兑换码，码与活动开关由平台运营配置。会员必须已存在且 Discord 已绑定，否则返回「会员不存在」，本接口不会自动创建会员。建议先调 discord-login-status，仅对 loggedIn=true 的用户签到。

请求参数（application/json）：

curl -X POST 'https://api.rizzitgo.com/open-api/promotion/discord-checkin' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"discordUserId":"123456789012345678","requestId":"REQ-20260904-0001"}'

响应字段：

首次签到成功示例：

{
  "code": 0,
  "data": {
    "alreadyCheckedIn": false,
    "grantAmount": 100,
    "success": true,
    "message": "签到成功"
  },
  "msg": ""
}

今日已签到示例（仍为业务成功，勿当失败重试）：

{
  "code": 0,
  "data": {
    "alreadyCheckedIn": true,
    "grantAmount": null,
    "success": true,
    "message": "今日已签到"
  },
  "msg": ""
}

「日」按 上海自然日（Asia/Shanghai）计算。今日已达每人每日上限时不返回错误码，而是 code=0 且 alreadyCheckedIn=true。到账金额由平台配置的余额兑换码决定（常见为 100 分 = 1 CNY），请以 grantAmount 为准。

业务错误：discordUserId 为空返回参数校验失败；Discord 未绑定或会员已删除返回 1_013_022_001「会员不存在」；同一 requestId 10 分钟内重复返回 1_013_022_002「请求重复，请勿重试」；活动关闭返回 1_013_026_000「Discord 签到活动未开启」；兑换码未配置返回 1_013_026_001「Discord 签到兑换码未配置」；其它入账失败返回 1_013_026_002「Discord 签到入账失败」。

17. 用户消费信息查询

• 方法与路径：POST /open-api/member/consumption/query
• 所需 scope：member:consumption:read
• operationId：MemberConsumptionAPI

按会员标识汇总已支付包裹与钱包充值。金额单位均为人民币分。不传 createTime 时统计终身累计；传入时须同时给出开始、结束，且开始不得晚于结束。

时间区间分别作用于：包裹提交时间（create_time）、充值支付成功时间（pay_time）。

会员标识（至少传一个）：memberId、unionId、discordOpenId（Discord snowflake，对应社交 openid，与登录状态接口的 discordUserId 为同一值）。传多个时必须指向同一会员，否则返回「用户不存在」。

请求参数（application/json）：

响应 data 字段：

按 unionId 查询终身累计：

curl -X POST 'https://api.rizzitgo.com/open-api/member/consumption/query' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{"unionId":"M123456"}'

按 Discord Open ID + 时间区间：

curl -X POST 'https://api.rizzitgo.com/open-api/member/consumption/query' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {租户编号}' \
  -H 'Content-Type: application/json' \
  -d '{
        "discordOpenId":"123456789012345678",
        "createTime":["2026-01-01 00:00:00","2026-09-03 23:59:59"]
      }'

响应示例：

{
  "code": 0,
  "data": {
    "memberId": 1024,
    "unionId": "M123456",
    "discordOpenId": "123456789012345678",
    "bagOrderCount": 12,
    "bagConsumeAmount": 88000,
    "totalRechargeAmount": 150000,
    "rechargeCount": 5,
    "startTime": "2026-01-01 00:00:00",
    "endTime": "2026-09-03 23:59:59"
  },
  "msg": ""
}

业务错误：未传任何会员标识，或 createTime 不是成对的开始/结束（含开始晚于结束），返回参数校验失败；标识解析失败、Discord 未绑定、会员已删除、多个标识指向不同会员，返回 1_004_001_000「用户不存在」。无消费/充值记录时计数字段为 0，仍返回成功。

18. 常见问题（FAQ）

• 频繁收到 401？ 多半是令牌过期或未缓存。请在 expires_in 内复用令牌，并在过期前刷新；确认 Authorization 头为 Bearer {access_token} 格式。
• 查询消费返回「用户不存在」？ memberId / unionId / discordOpenId 至少传一个；任一标识解析失败、Discord 未绑定会员，或多个标识指向不同会员，都会返回该错误。
• Discord 签到返回「会员不存在」？ 该 Discord 用户尚未绑定平台会员，或会员已删除。请先引导用户走 Discord 授权登录，再用 discord-login-status 确认 loggedIn=true 后再签到。
• Discord 签到提示今日已签到？ 这是成功响应（code=0，alreadyCheckedIn=true），不要当失败重试。自然日按上海时区计算。
• 收到 403？ 说明当前应用未被授予该接口所需的 scope，请联系运营开通。
• 收到 429？ 触发了按 clientId 维度的 QPS 限流，请降低频率并退避重试，必要时申请提升配额。
• 跨租户访问被拒？ 请确认请求头 tenant-id 与换取令牌时一致。
• clientSecret 泄漏怎么办？ 立即联系运营「重置密钥」，旧密钥即时失效，并更新你侧的密钥配置。
• 下单报外部用户未绑定？ 运营须先在「开放平台 / 会员绑定」录入 externalUserId 与会员编码；停用后也不能下单或支付。
• 创建订单因价格偏差被拒？ 服务端以实时价为准。请先调 quote，把返回的 payAmount 作为 expectedPayAmount 尽快下单；报价过期或阈值过小都会拒单。
• 补款什么时候要调开放接口？ 会员已开补款授权且余额充足时系统会自动扣。仅余额不足或授权关闭时，才需要 supplement/list → supplement/trade-no → wallet/pay。

19. 在线接口文档

网关 Knife4j 聚合的 Swagger 中包含 /open-api/** 分组，可在线查看每个接口的入参/出参定义，便于联调。

20. 文档版本