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:

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
  },
  "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 to a member by email)

• 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 the member identified by the given email. The member must already exist (exact email match); otherwise it returns "Member does not exist". This endpoint does not auto-create members.

Request body (application/json):

Request example:

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":"user@example.com","requestId":"REQ-20260604-0001"}'

Response fields:

coupons element fields:

Response example:

{
  "code": 0,
  "data": {
    "code": "E602F4DC626E4948",
    "email": "user@example.com",
    "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: empty email returns "Email is required"; no member found by email 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":"user@example.com","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, goodsDetailUrl (includes rno), goodsSaleCount, goodsSda, goodsCategoryCode.

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())

12. 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.
• 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.

13. 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.

14. Document Version