Open Platform (Open API) Integration Guide

Online docs (recommended): https://docs.rizzitgo.com — API reference stays in sync with this guide
Audience: external partners / third-party developers
Languages: English (this document) · 中文

This guide explains how to integrate with our /open-api/* open endpoints. The open endpoints are physically isolated from the consumer-facing /app-api and the admin /admin-api. They use OAuth2 client_credentials (client mode) for authentication, and control the set of callable endpoints per application via scope.

1. Overview and Architecture

• Auth model: standard OAuth2 client-credentials mode. Partners exchange the issued clientId + clientSecret for a short-lived access_token, then call business endpoints with that token. The open platform does not involve user login, authorization-code, or password grants.
• Endpoint isolation: all open endpoints live under the /open-api/** prefix and are routed separately by the gateway. Open tokens have a fixed user type of OPEN_API and cannot access /admin-api or /app-api, eliminating privilege escalation at the source.
• Permission granularity: each endpoint is guarded by the scope it requires (e.g. the goods-detail endpoint requires goods:detail:read). An application can only call endpoints corresponding to the scopes granted to it.
• Multi-tenancy: requests must carry tenant-id, which must match the one used when the token was obtained.

Call sequence:

sequenceDiagram
    participant P as Partner App
    participant GW as API Gateway
    participant SYS as System Service
    participant BIZ as Business Service

    P->>GW: POST /open-api/system/oauth2/token<br/>Basic(clientId:clientSecret)
    GW->>SYS: forward token request
    SYS-->>P: access_token (userType=OPEN_API, expires_in)
    P->>GW: POST /open-api/goods/detail<br/>Bearer access_token + tenant-id
    GW->>BIZ: validate token + scope, then forward
    BIZ-->>P: business data (unified {code,data,msg})

2. Glossary

3. Onboarding Process

1. Contact platform operations and submit: partner name, contact (name / email / phone), source IPs for callbacks (optional, for the IP whitelist), and the required scopes.
2. Operations creates the application under Admin Console "Open Platform / Partner Applications" and issues:
   • clientId
   • clientSecret (shown only once; store it securely)
   • the granted scope list (e.g. goods:detail:read)
   • tenant-id
3. The partner exchanges clientId + clientSecret for an access_token, then calls business endpoints with the token.

Pre-launch checklist:

• clientSecret stored securely (recommended: a secrets manager; never embed in frontend/client code or logs).
• All required scopes confirmed as granted.
• Caller egress IP added to the whitelist (if operations enabled the whitelist).
• Token caching implemented (reuse within expires_in; do not fetch a token on every request).
• Auto re-fetch on 401 and exponential backoff retry on 429 implemented.

3.1 Complete Scope Reference

Below is the full list of available scope values. Naming convention: {domain}:{resource}:{action}. When requesting a token, specify the required scopes via the scope parameter (space-separated). Endpoints corresponding to scopes not granted to your application will return 403.

Note: The OAuth2 token endpoints (/open-api/system/oauth2/token and /token/revoke) do not require any scope — they only need clientId + clientSecret authentication. The scope list expands as new business capabilities are added; always refer to the latest version of this document.

4. Environments and Domains

The production gateway domain is api.rizzitgo.com (already used in the examples), and the test/sandbox gateway domain is api-qa.rizzitbuy.com. Replace placeholders such as {tenant-id}, {clientId}, {clientSecret} with the actual values issued by operations.

5. Obtaining an Access Token

• Method & path: POST /open-api/system/oauth2/token
• Authentication: HTTP Basic. Base64-encode clientId:clientSecret and put it in the Authorization header (i.e. Authorization: Basic base64(clientId:clientSecret)).
• Content-Type: application/x-www-form-urlencoded

Request parameters:

Request example:

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

Response fields:

Response example:

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

Note: the open platform only supports client_credentials. Passing any other grant_type (such as authorization_code / password / refresh_token) returns 400 with the message "the open platform only supports the client_credentials grant". The token's userType is fixed to OPEN_API and cannot access /admin-api or /app-api.

6. Calling Business Endpoints

Every business request must include:

7. API Reference

7.1 Query Goods Detail (pilot)

• Method & path: POST /open-api/goods/detail
• Required scope: goods:detail:read

Request body (application/json):

Request example:

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

Response fields:

skuList element fields:

skuSpecInfoList element fields:

Response example:

{
  "code": 0,
  "data": {
    "goodsId": "123456",
    "goodsTitle": "Sample Goods",
    "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 Query Goods QC Detail

• Method & path: POST /open-api/goods/qc-detail
• Required scope: goods:qc:read

Request body (application/json):

Request example:

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

Response fields:

Note: for internal information protection, the QC endpoints do not return inspector / photographer staff IDs or names.

Response example:

{
  "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 Query Goods QC Image List

• Method & path: POST /open-api/goods/qc-images
• Required scope: goods:qc:read
• Request body: same as 7.2 (goodsId + source)

Request example:

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

Response example: data is an array of QC image URLs.

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

7.4 Paginated QC Data Query by Time

• Method & path: POST /open-api/goods/qc-page
• Required scope: goods:qc:read

Request body (application/json):

Request example:

curl -X POST 'https://api.rizzitgo.com/open-api/goods/qc-page' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'tenant-id: {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"]
      }'

Response fields: data.list is an array of QC details (same fields as 7.2), data.total is the total count.

{
  "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 Search Goods by Image

• Method & path: POST /open-api/goods/search-by-images
• Required scope: goods:search:read

Request body (application/json):

Request example:

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

Response fields:

goodsList element fields:

Note: to protect internal information, the open API does not return member-scoped fields such as collection status or personalized share links.

Response example:

{
  "code": 0,
  "data": {
    "goodsList": [
      {
        "goodsId": "123456",
        "goodsTitle": "Sample Goods",
        "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 Parse Goods URL

• Method & path: POST /open-api/goods/search-url-parse
• Required scope: goods:search:read
• Description: Parses short or long links from Taobao/Tmall, 1688, Weidian, and common agent sites (cssbuy, cnfans, hoobuy, etc.) to extract the platform goods ID and source. Unrecognized links return "Failed to parse product URL".

Request body (application/json):

Request example:

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

Response fields:

Response example:

{
  "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 Redeem Coupon by Code (issue by email or Discord user ID)

• Method & path: POST /open-api/promotion/redeem-code/redeem
• Required scope: promotion:redeem-code:redeem
• Description: Uses a pre-configured redeem code from the platform admin (which can bind N coupon templates and randomly hit one by weight) to issue a coupon to a member. Identify the member with either email or discordUserId (at least one required). When both are sent, Discord is used and email is not a fallback. The member must already exist (exact email match, or a Discord account already bound to a member); otherwise it returns "Member does not exist". This endpoint does not auto-create members.

Request body (application/json):

Request example (by email):

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

Request example (by Discord user ID):

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

Response fields:

coupons element fields:

Response example:

{
  "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": ""
}

Business errors: omitting both email and discordUserId returns "Please provide email or Discord user ID"; no member found by email or Discord (including unbound Discord or deleted member) returns "Member does not exist"; non-existent/expired/voided redeem codes and per-user or per-day (incl. per-IP) redemption limits reuse the existing redeem-code error codes. Redemption limits, validity and quotas are configured in the admin; please call within the agreed quota.

7.8 Member coupon query / extend / restore

Locate a member by email, member number (unionId), or user ID; query their coupons; extend unused coupons or restore expired ones. All three endpoints use the same user identifier rule: provide exactly one of the three fields, with priority userId > unionId > email.

Coupon status codes (string in both request and response, not numeric):

7.8.1 Paginated member coupon query

• Method & path: POST /open-api/promotion/member-coupon/page
• Required scope: promotion:member-coupon:read

Request body (application/json):

Response data: list (coupon items), total (count). Each item includes id, templateId, title, code, status (string code), discount fields, validStartTime, validEndTime, useTime, takeTime.

Example:

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

7.8.2 Extend unused coupons

• Method & path: POST /open-api/promotion/member-coupon/extend
• Required scope: promotion:member-coupon:extend
• Note: Only coupons with status=UNUSED can be extended.

Response data: successCount, coupons (id, status, validEndTime).

7.8.3 Restore expired coupons

• Method & path: POST /open-api/promotion/member-coupon/restore
• Required scope: promotion:member-coupon:restore
• Note: Only coupons with status=EXPIRE can be restored to UNUSED with a new validity period (default 15 days, configurable in admin).

Response data: successCount, coupons (id, status=UNUSED, validEndTime).

Business errors: 1_013_024_000 missing user identifier; 1_013_024_001 member not found; 1_013_024_002 coupon not owned by user; 1_013_024_003 invalid status code; 1_013_024_004 restore when not EXPIRE; extend when not UNUSED returns 1_013_003_005.

7.9 Promoter spreadsheet product pagination

Page a promoter's spreadsheet (shared product list) by referral code rno. Optional filters: custom category, keyword, product source, price range, and sort order.

• Method & path: POST /open-api/promotion/spreadsheet/page
• Required scope: promotion:spreadsheet:read

Request body (application/json):

Response data:

Main fields in each list item: goodsId, goodsTitle, localGoodsTitle, priceInCents, priceInUsd (USD amount from CNY cents using DB exchange rate), goodsSource, goodsPicUrl, goodsImageUrlList (full image list when async-synced; otherwise may contain only the main image), goodsDetailUrl (includes rno), goodsSaleCount, goodsSda, goodsCategoryCode, qcInfoList (latest up to 5 QC groups; empty array when none; element fields match open goods QC: goodsId, skuId, source, goodsName, localGoodsName, specName, localSpecName, imagePath, goodsDetailUrl, qcPathList, length, width, height, weight, volume, completionTime; no inspector/photographer fields).

Example:

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

Business errors: 1_013_025_000 missing rno; 1_013_007_000 promoter not found (invalid rno).

8. Revoking a Token (optional)

• Method & path: POST /open-api/system/oauth2/token/revoke
• Authentication: same as obtaining a token (HTTP Basic)
• Parameter: 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: {tenant-id}' \
  -d 'token={access_token}'

9. Unified Response Structure and Error Codes

All endpoints return the unified structure { code, data, msg }: code = 0 means success, anything else means failure, and msg carries the message.

Common errors:

10. Security and Limits

• IP whitelist: if operations configured ipWhitelist for the application (comma-separated, multiple IPs), only source IPs in the whitelist may call; empty means no restriction.
• Rate limiting: a per-application QPS can be configured (rateLimitQps, 0 means unlimited). Exceeding it returns 429.
• Secret storage: clientSecret is shown only once; never embed it in frontend/client code, logs, or version control. If leaked, immediately contact operations to "Reset Secret" under "Partner Applications"; the old secret is invalidated instantly.
• Token caching and concurrent refresh: cache the access_token on the client and reuse it within expires_in to avoid frequent token fetches. Refresh ahead of expiry with a buffer (e.g. when less than 60s remain), and lock the refresh to prevent concurrent duplicate fetches.
• Retry and backoff: on 401, re-fetch the token and retry once; on 429 or network jitter, retry with exponential backoff (e.g. 1s, 2s, 4s) with an upper bound.
• Multi-tenancy: always carry a tenant-id consistent with the token to avoid cross-tenant access being rejected.

11. Code Samples (obtain token -> query goods detail)

cURL

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

# 2) query goods detail
curl -X POST 'https://api.rizzitgo.com/open-api/goods/detail' \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'tenant-id: {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 = "{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) obtain token
        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());
        // In a real project, parse data.access_token with a JSON library
        String accessToken = "<parse data.access_token from tokenResp>";

        // 2) query goods detail
        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 = "{tenant-id}"
CLIENT_ID = "{clientId}"
CLIENT_SECRET = "{clientSecret}"

# 1) obtain token
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) query goods detail
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())

11.1 System exchange rate list — POST /open-api/pay/exchange-rate/list

• Required scope: pay:exchange-rate:read
• operationId: PayExchangeAPI
• Request: no body (an empty JSON {} is accepted)

Returns the configured system exchange rate for every enabled currency. The base currency is CNY: 1 CNY = exchangeRate of that currency. This endpoint does not return the real-time rate and does not apply country/customer premium policies.

Conversion: amount_foreign = amount_CNY × exchangeRate (e.g. CNY 100 with 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: {tenant-id}' \
  -H 'Content-Type: application/json' \
  -d '{}'

Response data item fields: name, abbreviationCode (ISO code such as USD / EUR / CNY), symbol, exchangeRate (system rate vs CNY).

{
  "code": 0,
  "data": [
    {
      "name": "Chinese Yuan",
      "abbreviationCode": "CNY",
      "symbol": "¥",
      "exchangeRate": 1
    },
    {
      "name": "US Dollar",
      "abbreviationCode": "USD",
      "symbol": "$",
      "exchangeRate": 0.140000
    }
  ]
}

12. Purchase order and wallet pay

Scopes: system:partner-member:read, order:purchase:quote, order:purchase:create, order:purchase:query, order:purchase:supplement-pay, pay:wallet:query, pay:wallet:pay

Place a purchase order on behalf of a bound member and debit their wallet. Amount fields are CNY cents. Server-side live prices are used; client-supplied prices are ignored.

Prerequisite: operations binds the partner externalUserId to a platform member under Admin Console "Open Platform / Member Bind". Binding enables repayment auth by default so buyer-agent supplements can auto-debit.

Recommended sequence:

1. POST /open-api/system/oauth2/token
2. POST /open-api/system/partner-member/query (optional bind check)
3. POST /open-api/order/purchase/quote
4. POST /open-api/order/purchase/create (idempotent on outOrderNo)
5. POST /open-api/pay/wallet/pay (use paymentId from step 4)

Supplement is not part of the happy path. Auto-debit runs when auth is on and balance is enough. Only then: supplement/list → supplement/trade-no → wallet/pay.

platformChannel: 1 Taobao, 2 1688, 3 Weidian, 5 Xianyu.

12.1 Query member bind — POST /open-api/system/partner-member/query

• Required scope: system:partner-member:read
• operationId: QueryMemberBindAPI

Unbound or disabled bindings return a business error.

Request: { "externalUserId": "shopify_10086" }

Response data: externalUserId, memberUnionId (member code for human check), bound.

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

12.1.1 List member binds — POST /open-api/system/partner-member/list

• Required scope: system:partner-member:read (same as single-bind query)
• operationId: QueryMemberBindListAPI

No request body. Identifies the partner from the access token and returns all binds (including disabled) plus each member's wallet balance. Empty array when none exist. Numeric member id is not exposed. Wallet lookup failures return 0 balance without failing the list.

Response data[]: externalUserId, memberUnionId, status (0=enabled, 1=disabled), balance (available, fen), freezePrice (frozen, fen), currencyCode (CNY).

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

12.2 Quote — POST /open-api/order/purchase/quote

• Required scope: order:purchase:quote
• operationId: PurchaseQuoteAPI

Does not create an order. Use returned payAmount as expectedPayAmount on create.

Request: externalUserId (required), items[] with platformChannel, goodsId, skuId, qty (1–9999), optional remarks.

Response 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: {tenant-id}' \
  -H 'Content-Type: application/json' \
  -d '{"externalUserId":"shopify_10086","items":[{"platformChannel":1,"goodsId":"654321","skuId":"5001","qty":2}]}'

12.3 Create purchase order — POST /open-api/order/purchase/create

• Required scope: order:purchase:create
• operationId: PurchaseCreateAPI

outOrderNo is idempotent per partner. A successful prior create is replayed with duplicated=true.

Request: required outOrderNo, externalUserId, items; optional addressId (default member address if omitted), orderComment, expectedPayAmount (reject if live price deviation exceeds the threshold).

Response 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: {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}]}'

12.4 Query purchase order — POST /open-api/order/purchase/query

• Required scope: order:purchase:query
• operationId: PurchaseQueryAPI

Pass either outOrderNo or orderNo. Only orders created by this partner are returned.

Response data: paymentId, payAmount, refStatus (0 processing / 1 created / 2 failed), orders[] (split by shop).

12.5 Query wallet balance — POST /open-api/pay/wallet/balance

• Required scope: pay:wallet:query
• operationId: WalletBalanceAPI

Request: { "externalUserId": "shopify_10086" }

Response data: balance (available, cents), freezePrice, currencyCode (CNY).

12.6 Wallet pay — POST /open-api/pay/wallet/pay

• Required scope: pay:wallet:pay
• operationId: WalletPayAPI

The business order is checked before debiting. Already-paid paymentId is rejected; query instead.

Request: required externalUserId (same as create), paymentId; optional payAmount (must match the pay order).

Response data: status (0 unpaid / 10 success / 20 refunded / 30 closed), paySuccess, payAmount, successTime, balance (remaining after debit).

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

12.7 List supplements — POST /open-api/order/purchase/supplement/list

• Required scope: order:purchase:query
• operationId: PurchaseSupplementListAPI

Needed only when auto-debit failed.

Request: { "externalUserId": "shopify_10086" }

Response data: supplementTotalAmount, orders[]. bizType: 1 purchase, 2 bag. expenseType: 102 goods, 104 freight, 203 bag freight. Use orderExpensesNo in the next call.

12.8 Create supplement pay order — POST /open-api/order/purchase/supplement/trade-no

• Required scope: order:purchase:supplement-pay
• operationId: PurchaseSupplementTradeNoAPI

Do not mix purchase and bag expense nos in one request. Then call wallet/pay with paymentId.

Request: { "externalUserId": "shopify_10086", "orderExpensesNoList": ["OE2026081100001"] }

Response data: paymentId, payAmount, payType (3 freight / 6 goods / 7 bag / 8 goods+freight).

13. Order and bag-order APIs

Scopes: order:bag-order:read, order:order-item:read

List endpoints require a member: pass at least one of memberId or unionId. Amount fields (price / actualPrice / freightFee / goodsTotalAmount) are in CNY cents.

13.1 Query bag order by number — POST /open-api/order/bag-order/query

• Required scope: order:bag-order:read

Request: { "bagOrderNo": "BG20250624001" }

Response data: exists, bagOrderNo, status, statusDesc, createTime, unionId.

Bag status: 0 unpaid, 1 pending review, 2 pending outbound, 3 outbound in progress, 4 pending extra payment, 5 pending shipment, 6 shipped, 7 received, 8 returned, 9 cancelled, 10 closed.

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

13.2 Page bag orders — POST /open-api/order/bag-order/page

• Required scope: order:bag-order:read

Required: pageNo, pageSize, and at least one of memberId / unionId. Optional filters: status, bagOrderNo, createTime ([start, end], yyyy-MM-dd HH:mm:ss).

List item fields: bagOrderNo, outboundOrderNo, status, statusDesc, goodsQty, goodsTotalAmount (cents), 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: {tenant-id}' \
  -H 'Content-Type: application/json' \
  -d '{"unionId":"M123456","pageNo":1,"pageSize":10}'

13.3 Page order items — POST /open-api/order/order-item/page

• Required scope: order:order-item:read

Required: pageNo, pageSize, and at least one of memberId / unionId. Optional: status, orderNo, orderItemNo, createTime.

List item fields: orderNo, orderItemNo, status, unionId, goodsName, localGoodsName, specName, localSpecName, imagePath, qty, price, actualPrice, freightFee, shopName, localShopName, createTime.

Common item status values: 101 unpaid, 105 cancelled, 201 pending accept, 204 purchasing, 206 merchant shipped, 305 warehoused, 308 shipped.

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

14. Logistics tracking

• Method & path: POST /open-api/logistics/track/query
• Required scope: logistics:track:query

Unified entry for domestic (type=1) and international (type=2) tracking. For domestic queries, carrierName improves recognition. For international queries, language (zh / en / es) controls translation.

Common response fields: trackingNo, type, status, trackContent, trackDate, trackItems (currentPosition, content, trackDate, status).

Track status: PENDING, IN_TRANSIT, DELIVERING, DELIVERED, EXCEPTION.

Domestic extras: carrierName, carrierCode, checkStatus, arrivalTime.
International extras: 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: {tenant-id}' \
  -H 'Content-Type: application/json' \
  -d '{"trackingNo":"YT9876543210","type":1,"carrierName":"YTO"}'

14.1 Freight estimate — POST /open-api/logistics/line/freight-estimate

• Required scope: logistics:freight-estimate:read
• operationId: FreightEstimateAPI

Estimates freight for available lines by destination country and weight. Only available lines are returned. totalFee is the system freight in CNY cents (C-end promotions are not applied). This version accepts country and weight only (no dimensions, province, or mail-restriction type). When language is omitted, lineName is English; when it is set, lineName is Google-translated.

Request:

Response data item fields:

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

Response example:

{
  "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
    }
  ]
}

15. Discord authorize URL

• Method & path: POST /open-api/member/auth/discord-authorize-url
• Required scope: member:auth:discord-login

Partners (e.g. a Discord bot) can obtain the platform Discord OAuth login URL. redirectUri must be an https:// URL and must exactly match a Redirect registered in the Discord Developer Portal.

Request: { "redirectUri": "https://rizzitgo.com" }
Response data: authorizeUrl.

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

15.1 Query Discord login status

• Method & path: POST /open-api/member/auth/discord-login-status
• Required scope: member:auth:discord-login

Look up whether a Discord user ID (snowflake, stored as social openid) is bound to a member. Unauthenticated users still get HTTP 200 with loggedIn=false, so bots can poll. A bind whose member has been deleted is treated as not logged in.

Request: { "discordUserId": "123456789012345678" }

Response data:

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

16. Member consumption query

• Method & path: POST /open-api/member/consumption/query
• Required scope: member:consumption:read
• operationId: MemberConsumptionAPI

Summarizes paid parcels and wallet recharges for a member. Amounts are in CNY cents. Omit createTime for lifetime totals. When provided, both start and end are required, and start must not be after end.

The time range is applied to parcel submit time (create_time) and recharge pay time (pay_time) respectively.

Member identifier (at least one): memberId, unionId, or discordOpenId (Discord snowflake, stored as social openid; same value as discordUserId on the login-status endpoint). When multiple identifiers are sent they must resolve to the same member, otherwise the API returns "User does not exist".

Request body (application/json):

Response data fields:

Lifetime totals by unionId:

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

By Discord Open ID with a time range:

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

Response example:

{
  "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": ""
}

Business errors: omitting every member identifier, or sending createTime without both start and end (including start after end), fails request validation. Identifier lookup failure, unbound Discord, deleted member, or conflicting identifiers return 1_004_001_000 "User does not exist". Members with no parcels/recharges still succeed with counts of 0.

17. FAQ

• Frequent 401s? Usually the token expired or was not cached. Reuse the token within expires_in and refresh before expiry; ensure the Authorization header is in the Bearer {access_token} format.
• Consumption query returns "User does not exist"? Provide at least one of memberId / unionId / discordOpenId. Lookup failure, unbound Discord, or identifiers that resolve to different members all return this error.
• Getting 403? The application has not been granted the scope required by that endpoint. Contact operations to grant it.
• Getting 429? You hit the per-clientId QPS limit. Lower the rate and retry with backoff; request a higher quota if needed.
• Cross-tenant access rejected? Ensure the tenant-id header matches the one used to obtain the token.
• clientSecret leaked? Immediately contact operations to "Reset Secret"; the old secret is invalidated instantly. Update the secret in your configuration.
• Unbound external user? Operations must bind externalUserId to a member code under "Open Platform / Member Bind". Disabled binds cannot quote, create, or pay.
• Create rejected for price deviation? The server uses live prices. Call quote first and pass payAmount as expectedPayAmount promptly.
• When to call supplement APIs? Auto-debit runs when repayment auth is on and balance is enough. Only if that fails: supplement/list → supplement/trade-no → wallet/pay.

18. Online API Documentation

The gateway's Knife4j-aggregated Swagger includes an /open-api/** group, where you can view request/response definitions of each endpoint online to ease integration.

19. Document Version