# 余额自动下单 API 接口文档

版本：`v2.1`  
更新时间：`2026-10-14`  
生产地址：`https://98-xj.com`  
结算币种：以接口返回的 `currency` 为准，当前为 `CNY`

[简体中文](/docs/cardnet-upstream-api-v2.zh-CN.md) | [繁體中文](/docs/cardnet-upstream-api-v2.zh-TW.md) | [English](/docs/cardnet-upstream-api-v2.en-US.md) | [Tiếng Việt](/docs/cardnet-upstream-api-v2.vi-VN.md) | [Русский](/docs/cardnet-upstream-api-v2.ru-RU.md) | [Türkçe](/docs/cardnet-upstream-api-v2.tr-TR.md)

## 1. 接入说明

本接口供已审核通过并启用 API 凭证的客户使用。

- 客户需要先在本站充值钱包余额。
- 下单时从钱包余额立即扣款。
- 仅支持自动发货商品和 `wallet` 余额支付。
- 不返回支付链接或 USDT 收款地址。
- 下单、扣款、库存占用、钱包流水、订单创建和自动发货为同一事务；任一步失败均不会产生半成品订单或单独扣款。
- 创建订单成功后，通过订单查询接口读取卡密。
- API Key 和 API Secret 必须只保存在服务端，不得放入网页、App 前端或公开仓库。

平台向客户提供：

```text
API_BASE_URL=https://98-xj.com
API_KEY=<平台提供>
API_SECRET=<平台提供>
```

> **重要：API Secret 必须按页面显示的完整原文作为 UTF-8 字符串使用。**  
> 当前 Secret 即使看起来像 128 位十六进制文本，也不要做 hex 解码、Base64 解码或大小写转换。解码成 64 字节后再做 HMAC 会得到错误签名。API Key 与 API Secret 必须来自同一份凭证；重新生成 Secret 后旧 Secret 立即失效。

### 1.1 凭证安全

- **生成或重新生成 Secret 需要二次验证**：在个人中心「API 对接」操作时，必须输入当前登录密码；已开启两步验证的账号还要输入动态码。未设置过登录密码的账号（例如 Telegram 自动注册）需先在「安全中心」设置密码。
- **修改或找回登录密码会作废 Secret**：密码变更后，旧 API Secret 立即失效，所有请求返回 `401 authentication_failed`。请登录个人中心重新生成，并同步更新服务器配置。
- **IP 白名单（强烈建议开启）**：个人中心「API 对接 → IP 白名单」可自助设置允许调用的来源 IP。每行一个 IP 或 CIDR（如 `203.0.113.10` 或 `203.0.113.0/24`），最多 20 条，不能填写 `0.0.0.0/0`。保存同样需要二次验证，立即生效。来源 IP 不在白名单时返回 `403 authentication_failed`；留空表示不限制。请填写服务器的固定出口 IP，Key 与 Secret 即使泄露也无法在其他地方使用。
- **敏感操作限频**：同一账号 10 分钟内最多 10 次生成 Secret 或修改白名单，超出后暂停 15 分钟。

## 2. 接口列表

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `POST` | `/api/v1/upstream/ping` | 测试凭证并查询钱包余额 |
| `GET` | `/api/v1/upstream/categories` | 查询商品分类 |
| `GET` | `/api/v1/upstream/products` | 查询商品列表 |
| `GET` | `/api/v1/upstream/products/:id` | 查询单个商品 |
| `POST` | `/api/v1/upstream/orders` | 余额下单 |
| `GET` | `/api/v1/upstream/orders/:id` | 查询订单与卡密 |
| `POST` | `/api/v1/upstream/orders/:id/cancel` | 取消可取消的订单 |

所有凭证都只接受下述 HMAC-SHA256 v2 签名；缺少 nonce 的旧版三段签名一律返回 `401 authentication_failed`。

## 3. 请求签名

### 3.1 必填请求头

| Header | 说明 |
| --- | --- |
| `Dujiao-Next-Api-Key` | 平台提供的 API Key |
| `Dujiao-Next-Timestamp` | 当前 Unix 秒时间戳 |
| `Dujiao-Next-Nonce` | 本次请求唯一的随机字符串，推荐 UUID v4 |
| `Dujiao-Next-Signature` | HMAC-SHA256 签名，小写十六进制 |

有 JSON 请求体时同时发送：

```http
Content-Type: application/json
```

### 3.2 待签名字符串

```text
METHOD\nPATH\nTIMESTAMP\nNONCE\nSHA256(RAW_BODY)
```

计算规则：

1. `METHOD`：大写 HTTP 方法，例如 `GET`、`POST`。
2. `PATH`：只包含 URL 路径，不包含域名、查询参数或 `#fragment`。
3. `TIMESTAMP`：与请求头完全相同的 Unix 秒时间戳。
4. `NONCE`：与请求头完全相同的随机字符串。
5. `SHA256(RAW_BODY)`：实际发送 body 原始字节的 SHA-256 小写十六进制。
6. 五段之间使用一个换行符 `\n`，末尾不添加换行。
7. 最终签名：

```text
hex_lower(HMAC_SHA256(API_SECRET, canonical_string))
```

GET 请求和没有请求体的 POST 请求，`RAW_BODY` 使用空字节串：

```text
SHA256("") = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```

注意：

- 服务器时间允许误差为前后 `60` 秒，客户服务器必须保持时间同步。
- 每个请求必须使用新的 `nonce`，网络重试也不能复用旧 nonce。
- 签名成功后不能再修改 JSON 的空格、字段顺序、编码或换行。
- 查询参数不参与签名，但路径必须参与签名。
- 请求不能使用 gzip 等压缩编码。
- 单个请求体最大 `65,536` 字节。
- `API_SECRET` 直接执行 UTF-8 编码后作为 HMAC key；不要把看似十六进制的 Secret 解码成二进制。
- API Key 与 Secret 必须成对使用；Secret 轮换后必须原子更新客户端配置并重启/热加载调用进程。

### 3.3 固定测试向量

正式请求生产接口前，客户端必须先通过以下离线测试向量。这里的 Secret 是公开测试值，不可用于生产：

```text
API_SECRET = 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
METHOD     = POST
PATH       = /api/v1/upstream/ping
TIMESTAMP  = 1709625600
NONCE      = 550e8400-e29b-41d4-a716-446655440000
RAW_BODY   = 空字节串
BODY_HASH  = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
SIGNATURE  = 09cf5cedb04ba4b32552c7e9d8c533368eeb48dd9ba1b72fd1e2c151e9487819
```

如果本地计算结果不是上述 `SIGNATURE`，不要请求生产接口。优先检查：Secret 是否被 hex/Base64 解码、换行是否为 `\n`、末尾是否多了换行、PATH 是否混入域名或查询参数。

### 3.4 Python 签名与请求示例

依赖：

```bash
pip install requests
```

示例：

```python
import hashlib
import hmac
import json
import os
import time
import uuid
from urllib.parse import urlencode

import requests

BASE_URL = "https://98-xj.com"
API_KEY = os.environ["CARDNET_API_KEY"]
API_SECRET = os.environ["CARDNET_API_SECRET"]


def api_request(method, path, *, query=None, payload=None, timeout=15):
    method = method.upper()
    raw_body = b""
    if payload is not None:
        raw_body = json.dumps(
            payload,
            ensure_ascii=False,
            separators=(",", ":"),
        ).encode("utf-8")

    timestamp = int(time.time())
    nonce = str(uuid.uuid4())
    body_hash = hashlib.sha256(raw_body).hexdigest()
    canonical = (
        f"{method}\n{path}\n{timestamp}\n{nonce}\n{body_hash}"
    ).encode("utf-8")
    signature = hmac.new(
        API_SECRET.encode("utf-8"),
        canonical,
        hashlib.sha256,
    ).hexdigest()

    headers = {
        "Dujiao-Next-Api-Key": API_KEY,
        "Dujiao-Next-Timestamp": str(timestamp),
        "Dujiao-Next-Nonce": nonce,
        "Dujiao-Next-Signature": signature,
    }
    if payload is not None:
        headers["Content-Type"] = "application/json"

    url = BASE_URL + path
    if query:
        url += "?" + urlencode(query)

    response = requests.request(
        method,
        url,
        data=raw_body if payload is not None else None,
        headers=headers,
        timeout=timeout,
    )
    return response.status_code, response.json()


# 测试凭证和余额
status, result = api_request("POST", "/api/v1/upstream/ping")
print(status, result)

# 创建订单
status, result = api_request(
    "POST",
    "/api/v1/upstream/orders",
    payload={
        "sku_id": 123,
        "quantity": 1,
        "downstream_order_no": "merchant-20260718-0001",
        "payment_mode": "wallet",
    },
)
print(status, result)

# 查询订单和卡密
if result.get("order_id"):
    order_id = result["order_id"]
    status, detail = api_request(
        "GET",
        f"/api/v1/upstream/orders/{order_id}",
    )
    print(status, detail)
```

### 3.5 Node.js 签名示例

适用于 Node.js 18 及以上版本。`API_SECRET` 直接作为 UTF-8 文本传给 HMAC：

```javascript
import crypto from "node:crypto";

function signV2(secret, method, path, timestamp, nonce, rawBody = Buffer.alloc(0)) {
  const bodyHash = crypto.createHash("sha256").update(rawBody).digest("hex");
  const canonical = `${method.toUpperCase()}\n${path}\n${timestamp}\n${nonce}\n${bodyHash}`;
  return crypto.createHmac("sha256", Buffer.from(secret, "utf8"))
    .update(Buffer.from(canonical, "utf8"))
    .digest("hex");
}

const method = "POST";
const path = "/api/v1/upstream/ping";
const timestamp = Math.floor(Date.now() / 1000);
const nonce = crypto.randomUUID();
const rawBody = Buffer.alloc(0);
const signature = signV2(
  process.env.CARDNET_API_SECRET,
  method,
  path,
  timestamp,
  nonce,
  rawBody,
);

const response = await fetch(`https://98-xj.com${path}`, {
  method,
  headers: {
    "Dujiao-Next-Api-Key": process.env.CARDNET_API_KEY,
    "Dujiao-Next-Timestamp": String(timestamp),
    "Dujiao-Next-Nonce": nonce,
    "Dujiao-Next-Signature": signature,
  },
});
console.log(response.status, await response.json());
```

### 3.6 Go 签名示例

```go
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"strings"
)

func signV2(secret, method, path, timestamp, nonce string, rawBody []byte) string {
	bodyHash := sha256.Sum256(rawBody)
	canonical := strings.Join([]string{
		strings.ToUpper(method),
		path,
		timestamp,
		nonce,
		hex.EncodeToString(bodyHash[:]),
	}, "\n")
	mac := hmac.New(sha256.New, []byte(secret)) // Secret 原始 UTF-8 字节
	_, _ = mac.Write([]byte(canonical))
	return fmt.Sprintf("%x", mac.Sum(nil))
}
```

## 4. 测试凭证与查询余额

```http
POST /api/v1/upstream/ping
```

请求体为空。

成功响应：

```json
{
  "ok": true,
  "site_name": "站点名称",
  "protocol_version": "1.0",
  "user_id": 1001,
  "balance": "500.00",
  "currency": "CNY",
  "member_level": null
}
```

`balance` 是当前已入账可用余额。下单前应先检查余额，但最终是否扣款成功以创建订单响应为准。

## 5. 查询商品分类

```http
GET /api/v1/upstream/categories
```

成功响应：

```json
{
  "ok": true,
  "categories": [
    {
      "id": 1,
      "parent_id": 0,
      "slug": "example",
      "name": {
        "zh-CN": "示例分类"
      },
      "icon": "",
      "sort_order": 0
    }
  ]
}
```

## 6. 查询商品

### 6.1 商品列表

```http
GET /api/v1/upstream/products?page=1&page_size=50
```

查询参数：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `page` | 否 | 页码，默认 `1` |
| `page_size` | 否 | 每页数量，默认及最大 `50` |
| `include_inactive` | 否 | `true` 时包含已下架商品 |
| `updated_after` | 否 | RFC3339 时间，例如 `2026-07-18T00:00:00Z` |

成功响应结构：

```json
{
  "ok": true,
  "items": [
    {
      "id": 10,
      "slug": "example-product",
      "title": {
        "zh-CN": "示例商品"
      },
      "price_amount": "20.00",
      "fulfillment_type": "auto",
      "is_active": true,
      "category_id": 1,
      "wholesale_prices": [
        {
          "min_quantity": 10,
          "unit_price": "18.00"
        }
      ],
      "skus": [
        {
          "id": 123,
          "sku_code": "SKU-001",
          "spec_values": {},
          "price_amount": "20.00",
          "stock_status": "in_stock",
          "stock_quantity": 50,
          "is_active": true
        }
      ],
      "created_at": "2026-07-18T00:00:00Z",
      "updated_at": "2026-07-18T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50,
  "includes_inactive": false
}
```

库存状态：

| `stock_status` | 说明 |
| --- | --- |
| `in_stock` | 库存正常 |
| `low_stock` | 库存较少 |
| `out_of_stock` | 无库存 |
| `unlimited` | 无限库存，`stock_quantity` 为 `-1` |

余额 API 下单只支持 `fulfillment_type=auto` 的可用自动发货 SKU。实际价格、购买限制和库存会在下单事务内重新校验，创建订单返回的 `amount` 才是最终成交金额。

### 6.2 单个商品

```http
GET /api/v1/upstream/products/10
```

成功响应：

```json
{
  "ok": true,
  "product": {
    "id": 10,
    "title": {
      "zh-CN": "示例商品"
    },
    "price_amount": "20.00",
    "fulfillment_type": "auto",
    "is_active": true,
    "skus": [
      {
        "id": 123,
        "sku_code": "SKU-001",
        "price_amount": "20.00",
        "stock_status": "in_stock",
        "stock_quantity": 50,
        "is_active": true
      }
    ]
  }
}
```

## 7. 创建余额订单

```http
POST /api/v1/upstream/orders
Content-Type: application/json
```

请求字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `sku_id` | 是 | 商品接口返回的 SKU ID |
| `quantity` | 是 | 正整数，当前接口上限 `100`，并受商品自身限制 |
| `downstream_order_no` | 是 | 客户自己的唯一订单号，同时作为幂等键 |
| `payment_mode` | 否 | 只能省略、传 `null` 或传 `"wallet"` |
| `trace_id` | 否 | 客户链路追踪号 |
| `callback_url` | 否 | 当前不支持；只能省略、传 `null` 或空字符串 |
| `manual_form_data` | 否 | 当前不支持；只能省略、传 `null` 或空对象 `{}` |

`downstream_order_no` 和非空 `trace_id` 必须满足：

```regex
^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
```

推荐请求体：

```json
{
  "sku_id": 123,
  "quantity": 2,
  "downstream_order_no": "merchant-20260718-0001",
  "payment_mode": "wallet",
  "trace_id": "trace-20260718-0001"
}
```

成功响应：

```json
{
  "ok": true,
  "order_id": 456,
  "order_no": "EXAMPLE-ORDER-NO",
  "status": "completed",
  "amount": "40.00",
  "currency": "CNY",
  "downstream_order_no": "merchant-20260718-0001",
  "trace_id": "trace-20260718-0001"
}
```

创建接口不直接返回卡密。收到成功响应后，使用 `order_id` 查询订单详情。

### 7.1 幂等规则

幂等范围为：

```text
(当前 API 凭证, downstream_order_no)
```

- 同一个 `downstream_order_no`，且 `sku_id`、`quantity` 相同：返回原订单，不会重复扣款或重复占用库存。
- 同一个 `downstream_order_no`，但 `sku_id` 或 `quantity` 不同：返回 `idempotency_conflict`。
- `payment_mode` 省略、`null`、`wallet` 三种写法等价。
- 网络超时或 5xx 导致结果不确定时，必须使用原 `downstream_order_no` 和原业务参数重试，但每次都要生成新的 timestamp、nonce 和签名。
- 不要因为第一次响应超时就更换 `downstream_order_no`，否则可能创建第二笔真实订单。

## 8. 查询订单和卡密

```http
GET /api/v1/upstream/orders/456
```

成功响应：

```json
{
  "ok": true,
  "order_id": 456,
  "order_no": "EXAMPLE-ORDER-NO",
  "status": "completed",
  "amount": "40.00",
  "refunded_amount": "0.00",
  "currency": "CNY",
  "refund_records": [],
  "items": [
    {
      "product_id": 10,
      "sku_id": 123,
      "title": {
        "zh-CN": "示例商品"
      },
      "quantity": 2,
      "unit_price": "20.00",
      "total_price": "40.00",
      "fulfillment_type": "auto"
    }
  ],
  "fulfillment": {
    "type": "auto",
    "status": "delivered",
    "payload": "<卡密内容>",
    "delivery_data": {},
    "delivered_at": "2026-07-18T00:00:00Z"
  }
}
```

`fulfillment.payload` 和 `fulfillment.delivery_data` 可能包含卡密，必须按敏感数据处理：

- 只通过 HTTPS 传输。
- 不得写入普通访问日志、报错日志或监控标签。
- 不得返回给无权限用户。

常见订单状态：

| 状态 | 说明 |
| --- | --- |
| `paid` | 已付款 |
| `fulfilling` | 发货处理中 |
| `partially_delivered` | 部分发货 |
| `delivered` | 已发货 |
| `completed` | 已完成 |
| `partially_refunded` | 部分退款 |
| `refunded` | 已退款 |
| `canceled` | 已取消 |

正常的余额自动卡密订单通常会直接返回 `completed`。

## 9. 取消订单

```http
POST /api/v1/upstream/orders/456/cancel
```

请求体为空。

成功响应：

```json
{
  "ok": true,
  "order_id": 456,
  "order_no": "EXAMPLE-ORDER-NO",
  "status": "canceled"
}
```

已自动发货或已完成的订单通常不能取消，会返回 `cancel_not_allowed`。

## 10. 错误响应

统一错误结构：

```json
{
  "ok": false,
  "error_code": "invalid_request",
  "error_message": "request rejected"
}
```

客户端应根据 HTTP 状态码和 `error_code` 处理，不要依赖 `error_message` 文本。

| HTTP | `error_code` | 含义与处理 |
| --- | --- | --- |
| `400` | `bad_request` | 路径参数格式错误（如订单 ID、商品 ID 不是纯数字），修正后再请求 |
| `400` | `invalid_request` | JSON 格式、字段名、字段类型或取值不合法（含未知字段、`downstream_order_no` 格式不符） |
| `400` | `payment_mode_not_supported` | `payment_mode` 只能省略、传 `null` 或 `"wallet"` |
| `400` | `callback_not_supported` | `callback_url` 只能省略、传 `null` 或空字符串 |
| `400` | `product_not_supported` | SKU 不存在、已下架、不是自动发货，或数量不满足购买限制；更换 SKU 或调整数量 |
| `401` | `authentication_failed` | 鉴权失败统一返回此码：缺少请求头、API Key 无效或已停用、账号停用、签名错误、时间戳超出 ±60 秒或不是秒级整数、缺少 nonce、Secret 已因改密作废等。暂停自动请求并告警，逐项核对后手工重试一次 `/ping` |
| `403` | `authentication_failed` | 签名正确，但来源 IP 不在该凭证的 IP 白名单内；核对服务器出口 IP，或在个人中心更新白名单 |
| `403` | `wallet_order_not_enabled` | 该凭证未开通余额下单权限，联系平台 |
| `403` | `member_level_required` | 该商品仅限指定会员等级购买 |
| `403` | `credential_paused` | 该凭证的 API 调用已被暂停，联系平台 |
| `404` | `product_not_found` | 商品不存在 |
| `404` | `order_not_found` | 订单不存在或不属于当前账号 |
| `409` | `replay_detected` | nonce 已被使用；生成新的 nonce 重新签名，业务参数保持不变 |
| `409` | `idempotency_conflict` | 同一个 `downstream_order_no` 绑定了不同的商品或数量，停止自动重试 |
| `409` | `insufficient_balance` | 钱包余额不足；先充值并确认已入账 |
| `409` | `insufficient_stock` | 库存不足；更换商品、减少数量或稍后重试 |
| `409` | `cancel_not_allowed` | 当前订单状态不允许取消 |
| `413` | `invalid_request` | 请求体超过 `65,536` 字节 |
| `415` | `invalid_request` | 请求使用了 gzip 等压缩编码 |
| `429` | `rate_limited` | 超出频率限制；按 `Retry-After`（如有）退避，再用新的 timestamp、nonce 和签名重试 |
| `500` | `internal_error` | 查询类接口内部错误；退避后重试 |
| `503` | `service_unavailable` | 服务暂时不可用或并发已满；保持原幂等参数，退避后用新签名重试 |

> `401` 和 `403` 表示凭证、签名或账号配置问题，客户端必须暂停自动请求并告警。修正配置后只允许先手工重试一次 `/ping`，不要对鉴权失败进行无限重试。

## 11. 调用频率与重试

- 单个凭证总请求上限为 `60 次/分钟`，超限后封禁 `30` 秒，期间返回 `429 rate_limited`。
- 同一来源 IP 在鉴权前的请求上限为 `120 次/分钟`，超限后封禁 `5` 分钟。
- 创建、取消等写请求并发不超过 `2`，查询请求并发不超过 `8`；超出时返回 `503 service_unavailable`。
- 创建订单建议控制在 `5 次/10 秒`以内。
- 只有 `429`、`503` 和网络超时可使用指数退避，例如 `1、2、4、8` 秒。
- `401`、`403` 必须立即暂停自动调用并告警，禁止自动重试，避免错误配置形成请求风暴。
- 重试创建订单时保持同一个 `downstream_order_no`、`sku_id` 和 `quantity`，但必须生成新的 timestamp、nonce 和签名。
- `insufficient_balance`、`insufficient_stock`、`sku_unavailable`、`product_unavailable`、`idempotency_conflict` 不应盲目重试。

## 12. 上线前检查

客户正式接入前应确认：

1. API 凭证已经审核通过并启用。
2. API Key 是后台显示的 64 位 Key，API Secret 是生成时显示的完整 128 位原文。
3. 固定离线测试向量已通过，确认 Secret 未进行 hex/Base64 解码。
4. `POST /api/v1/upstream/ping` 返回 `ok=true`。
5. 钱包 `balance` 足够支付测试订单。
6. 客户服务器时间已同步。
7. API Secret 只保存在服务端环境变量或密钥管理系统。
8. 使用真实发送的原始 body 计算签名。
9. 创建订单已实现 `downstream_order_no` 幂等重试。
10. 客户端不会自动重试 `401`、`403`，且卡密不会进入普通日志。
11. 已在个人中心配置 IP 白名单，只包含服务器的固定出口 IP（推荐）。
12. 修改登录密码或重新生成 Secret 后，有流程同步更新服务器上的 Secret。

## 13. 更新记录

### 2026-10-14 · v2.1

- 新增「1.1 凭证安全」：生成或重新生成 Secret 需要二次验证；修改或找回登录密码会作废 Secret；可自助设置 IP 白名单。
- 错误码表按实际返回重写：鉴权失败统一为 `401 authentication_failed`，IP 不在白名单为 `403 authentication_failed`，余额不足为 `409 insufficient_balance`；补充 `member_level_required`、`wallet_order_not_enabled`、`credential_paused`、`product_not_found`、`internal_error`。
- 频率限制补充封禁时长与按 IP 的限制。
- 新增越南语、俄语、土耳其语版本。

### 2026-08-27 · v2.0

- 明确 HMAC-SHA256 v2 的五段 canonical 格式。
- 明确 128 位 API Secret 按 UTF-8 原文使用，禁止 hex/Base64 解码。
- 增加可离线验证的固定测试向量以及 Python、Node.js、Go 示例。
- 补齐实际鉴权错误码，并规定 `401`、`403` 禁止自动重试。
