Dujiao 对接开放 API 文档

1. 文档说明

本文档用于第三方系统对接本站的商品、订单与交付能力。

测试连接
获取分类
获取商品与 SKU
创建采购订单
查询采购订单
取消采购订单
接收订单状态回调

本接口遵循统一响应结构，并使用 Header + HMAC-SHA256 验签。对接入口固定为 /api/v1/upstream/*。

2. 基础信息

2.1 Base URL

{{CURRENT_ORIGIN}}/api/v1/upstream

2.2 统一响应格式

成功：

{
  "ok": true
}

失败：

{
  "ok": false,
  "error_code": "error_code_here",
  "error_message": "human readable message"
}

3. 认证方式

3.1 必填请求头

Dujiao-Next-Api-Key：API Key
Dujiao-Next-Timestamp：Unix 秒级时间戳
Dujiao-Next-Signature：签名值，小写十六进制

3.2 签名算法

{METHOD}
{PATH}
{TIMESTAMP}
{BODY_MD5}

METHOD：大写 HTTP 方法
PATH：请求路径，不带域名，不带 query string
TIMESTAMP：与 Header 中时间戳一致
BODY_MD5：请求体 MD5，小写十六进制；空 body 也需要参与计算

3.3 Python 签名示例

import hashlib
import hmac
import json
import time
import requests

api_key = "your_api_key"
api_secret = "your_api_secret"
base_url = "{{CURRENT_ORIGIN}}"

def sign(secret: str, method: str, path: str, timestamp: int, body: bytes) -> str:
    body_md5 = hashlib.md5(body).hexdigest()
    sign_string = f"{method}\n{path}\n{timestamp}\n{body_md5}"
    return hmac.new(secret.encode(), sign_string.encode(), hashlib.sha256).hexdigest()

def api_request(method: str, path: str, body: dict | None = None):
    ts = int(time.time())
    body_bytes = json.dumps(body, ensure_ascii=False).encode("utf-8") if body else b""
    signature = sign(api_secret, method, path, ts, body_bytes)
    headers = {
        "Dujiao-Next-Api-Key": api_key,
        "Dujiao-Next-Timestamp": str(ts),
        "Dujiao-Next-Signature": signature,
        "Content-Type": "application/json",
    }
    resp = requests.request(method, base_url + path, headers=headers, data=body_bytes)
    return resp.json()

print(api_request("POST", "/api/v1/upstream/ping"))

4. 接口列表

POST /ping：测试连接
GET /categories：获取分类列表
GET /products：获取商品列表
GET /products/{id}：获取商品详情
POST /orders：创建采购订单
GET /orders/{id}：查询采购订单
POST /orders/{id}/cancel：取消采购订单
POST /api/v1/upstream/callback：订单状态回调

5. 状态值说明

pending_payment：待支付
paid：已支付，待处理
fulfilling：处理中
partially_delivered：部分交付
delivered：已交付
completed：已完成
canceled：已取消

6. 接口详情

6.1 测试连接

POST /api/v1/upstream/ping

无请求体。

{
  "ok": true,
  "site_name": "你的站点名称",
  "protocol_version": "1.0",
  "user_id": 42,
  "balance": "1000.00",
  "currency": "CNY",
  "member_level": null
}

6.2 获取分类列表

GET /api/v1/upstream/categories

{
  "ok": true,
  "categories": [
    {
      "id": 1,
      "parent_id": 0,
      "slug": "game-topup",
      "name": {
        "zh-CN": "游戏充值",
        "en": "Game Top-up"
      },
      "icon": "",
      "sort_order": 10
    }
  ]
}

6.3 获取商品列表

GET /api/v1/upstream/products?page=1&page_size=20

{
  "ok": true,
  "items": [
    {
      "id": 1,
      "slug": "example-product",
      "title": {
        "zh-CN": "示例商品",
        "en": "Example Product"
      },
      "description": {
        "zh-CN": "这是一个示例"
      },
      "content": {},
      "seo_meta": {},
      "images": [
        "{{CURRENT_ORIGIN}}/static/example/img1.jpg"
      ],
      "tags": [
        "hot"
      ],
      "price_amount": "7.90",
      "original_price": "9.90",
      "member_price": "7.50",
      "currency": "CNY",
      "fulfillment_type": "auto",
      "manual_form_schema": null,
      "is_active": true,
      "category_id": 1,
      "skus": [
        {
          "id": 1,
          "sku_code": "DEFAULT",
          "spec_values": {},
          "price_amount": "7.90",
          "original_price": "9.90",
          "member_price": "7.50",
          "stock_status": "in_stock",
          "stock_quantity": 100,
          "is_active": true
        }
      ],
      "created_at": "2026-03-01T12:00:00Z",
      "updated_at": "2026-03-01T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

6.4 获取商品详情

GET /api/v1/upstream/products/{id}

product_not_found：商品不存在
product_unavailable：商品不可用

6.5 创建采购订单

POST /api/v1/upstream/orders
Content-Type: application/json

{
  "sku_id": 1,
  "quantity": 1,
  "manual_form_data": {},
  "downstream_order_no": "A-20260412-0001",
  "trace_id": "trace-001",
  "callback_url": "{{CURRENT_ORIGIN}}/api/v1/upstream/callback"
}

{
  "ok": true,
  "order_id": 101,
  "order_no": "DJ20260301120000ABCD",
  "status": "paid",
  "amount": "9.90",
  "currency": "CNY"
}

6.6 查询采购订单

GET /api/v1/upstream/orders/{id}

{
  "ok": true,
  "order_id": 101,
  "order_no": "DJ20260301120000ABCD",
  "status": "completed",
  "amount": "9.90",
  "currency": "CNY",
  "items": [
    {
      "product_id": 1,
      "sku_id": 1,
      "title": {
        "zh-CN": "示例商品"
      },
      "quantity": 1,
      "unit_price": "9.90",
      "total_price": "9.90",
      "fulfillment_type": "auto"
    }
  ],
  "fulfillment": {
    "type": "auto",
    "status": "delivered",
    "payload": "ABCD-EFGH-1234-5678",
    "delivery_data": null,
    "delivered_at": "2026-03-01T12:01:00Z"
  }
}

6.7 取消采购订单

POST /api/v1/upstream/orders/{id}/cancel

{
  "ok": true,
  "order_id": 101,
  "order_no": "DJ20260301120000ABCD",
  "status": "canceled"
}

7. 回调接口

POST /api/v1/upstream/callback

{
  "event": "order.updated",
  "order_id": 101,
  "order_no": "DJ20260301120000ABCD",
  "downstream_order_no": "A-20260412-0001",
  "status": "completed",
  "fulfillment": {
    "type": "auto",
    "status": "delivered",
    "payload": "ABCD-EFGH-1234-5678",
    "delivery_data": null,
    "delivered_at": "2026-03-01T12:01:00Z"
  },
  "timestamp": 1712900000
}

成功响应：

{
  "ok": true,
  "message": "received"
}

8. 错误码说明

missing_auth_headers
invalid_timestamp
timestamp_expired
invalid_signature
invalid_api_key
user_disabled
bad_request
invalid_callback_url
sku_unavailable
product_unavailable
product_not_found
order_not_found
insufficient_balance
insufficient_stock
cancel_not_allowed
payment_failed
internal_error

9. 对接流程建议

获取 API Key / API Secret
调用 POST /ping 测试连通性
调用 GET /products 拉取商品与 SKU
建立商品 / SKU 映射
调用 POST /orders 创建采购订单
接收回调，或轮询 GET /orders/{id}
必要时调用 POST /orders/{id}/cancel

10. 接入注意事项

建议全站使用 HTTPS
callback_url 必须是公网可访问地址
downstream_order_no 建议全局唯一
请妥善保管 API Secret
回调处理必须幂等

Dujiao 对接开放 API 文档

Open API 申请

目录

1. 文档说明

2. 基础信息

2.1 Base URL

2.2 统一响应格式

3. 认证方式

3.1 必填请求头

3.2 签名算法

3.3 Python 签名示例

4. 接口列表

5. 状态值说明

6. 接口详情

6.1 测试连接

6.2 获取分类列表

6.3 获取商品列表

6.4 获取商品详情

6.5 创建采购订单

6.6 查询采购订单

6.7 取消采购订单

7. 回调接口

8. 错误码说明

9. 对接流程建议

10. 接入注意事项