Site Integration Open API

Last Updated: 2026-04-01

This document covers the Dujiao-Next site-to-site integration API endpoints under /api/v1/upstream/*.

1. Basics

1.1 Base URL

https://<upstream-site-domain>/api/v1/upstream

Example: https://api.example.com/api/v1/upstream

1.2 Unified Response Envelope

Success:

json

{
  "ok": true,
  ...
}

Failure:

json

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

1.3 Runtime Constraints (Important)

Procurement after payment is asynchronous and must not block end-user checkout.
Mapped upstream items must wait for upstream callbacks; local manual/auto fulfillment is not allowed.
Local cancellation is upstream-first: if upstream cancel fails or is non-cancelable, local cancel/refund must be denied.
When upstream procurement fails, downstream should mark the order as an exception for admin handling, instead of auto local cancel/refund.

2. Authentication & Signature

2.1 Required Headers

Header	Description
`Dujiao-Next-Api-Key`	API Key (generated by the upstream site user under "API Permissions")
`Dujiao-Next-Timestamp`	Unix timestamp (seconds)
`Dujiao-Next-Signature`	HMAC-SHA256 signature (lowercase hex)

2.2 Signature Algorithm

Sign string format:

{METHOD}\n{PATH}\n{TIMESTAMP}\n{BODY_MD5}

Component details:

Placeholder	Description
`{METHOD}`	HTTP method in uppercase, e.g. `GET`, `POST`
`{PATH}`	Request path (no domain, no query string), e.g. `/api/v1/upstream/products`
`{TIMESTAMP}`	Must match the `Dujiao-Next-Timestamp` header
`{BODY_MD5}`	MD5 hash of the request body (lowercase hex). For empty body, use MD5 of empty string: `d41d8cd98f00b204e9800998ecf8427e`

Final signature:

signature = hex_lower(hmac_sha256(signString, api_secret))

2.3 Signature Pseudocode

python

import hashlib, hmac, time

api_key = "your_api_key"
api_secret = "your_api_secret"
method = "POST"
path = "/api/v1/upstream/orders"
body = b'{"sku_id":1,"quantity":1}'
timestamp = str(int(time.time()))

body_md5 = hashlib.md5(body).hexdigest()
sign_string = f"{method}\n{path}\n{timestamp}\n{body_md5}"
signature = hmac.new(
    api_secret.encode(), sign_string.encode(), hashlib.sha256
).hexdigest()

headers = {
    "Dujiao-Next-Api-Key": api_key,
    "Dujiao-Next-Timestamp": timestamp,
    "Dujiao-Next-Signature": signature,
    "Content-Type": "application/json",
}

2.4 Validation Rules

Timestamp skew tolerance: ±60 seconds.
API Key must be in "approved and active" status.
The user account associated with the API Key must be active.

3. Endpoint List

Method	Path	Description
`POST`	`/ping`	Connectivity check
`GET`	`/categories`	Fetch category list
`GET`	`/products`	Fetch product list
`GET`	`/products/:id`	Fetch product details
`POST`	`/orders`	Create procurement order (auto wallet payment)
`GET`	`/orders/:id`	Query procurement order
`POST`	`/orders/:id/cancel`	Cancel procurement order

Callback endpoint (Site B → Site A):

Method	Path	Description
`POST`	`/upstream/callback`	Site B pushes order status changes and delivery content to Site A

4. Core Endpoints

4.1 POST `/ping`

Connectivity check. Also returns wallet balance, currency, and member level for the API user.

Request: No body required.

Response fields:

Field	Type	Description
`ok`	boolean	Connectivity status
`site_name`	string	Site name
`protocol_version`	string	Protocol version, currently `"1.0"`
`user_id`	number	API user ID
`balance`	string	Available wallet balance
`currency`	string	Site currency (e.g. `CNY`, `USD`)
`member_level`	object\|null	User's member level info (`null` if no member level)

member_level sub-object:

Field	Type	Description
`id`	number	Member level ID
`name`	object	Multilingual level name, e.g. `{"zh-CN":"黄金会员","en":"Gold"}`
`slug`	string	Level identifier
`icon`	string	Level icon URL

Response example:

json

{
  "ok": true,
  "site_name": "My Shop",
  "protocol_version": "1.0",
  "user_id": 42,
  "balance": "1000.00",
  "currency": "CNY",
  "member_level": {
    "id": 1,
    "name": { "zh-CN": "黄金会员", "en": "Gold" },
    "slug": "gold",
    "icon": "https://example.com/gold.png"
  }
}

4.2 GET `/categories`

Fetch the upstream category list.

Request: No body or query parameters required.

Response fields:

Field	Type	Description
`ok`	boolean	Whether successful
`categories`	array	Category array (see Category structure below)

Category Structure

Field	Type	Description
`id`	number	Category ID
`parent_id`	number	Parent category ID (0 for top-level categories)
`slug`	string	Unique category identifier
`name`	object	Localized name, e.g. `{"zh-CN":"Game Top-up","en":"Game Top-up"}`
`icon`	string	Category icon URL
`sort_order`	number	Sort weight (descending)

Response example:

json

{
  "ok": true,
  "categories": [
    {
      "id": 1,
      "parent_id": 0,
      "slug": "game-topup",
      "name": { "zh-CN": "Game Top-up", "en": "Game Top-up" },
      "icon": "",
      "sort_order": 10
    },
    {
      "id": 2,
      "parent_id": 1,
      "slug": "steam",
      "name": { "zh-CN": "Steam", "en": "Steam" },
      "icon": "",
      "sort_order": 5
    }
  ]
}

Category Hierarchy

Categories support up to two levels: top-level categories (parent_id = 0) and sub-categories (parent_id points to a top-level category). Products can only be associated with leaf categories.

4.3 GET `/products`

Fetch the upstream product list (only active products are returned).

Query parameters:

Param	Type	Required	Default	Description
`page`	number	No	1	Page number
`page_size`	number	No	20	Items per page (1–100)

Response fields:

Field	Type	Description
`ok`	boolean	Success flag
`items`	array	Product array (see Product structure below)
`total`	number	Total count
`page`	number	Current page
`page_size`	number	Items per page

Product Structure

Field	Type	Description
`id`	number	Product ID (orders reference SKU ID, not this)
`slug`	string	URL slug
`title`	object	Multilingual title, e.g. `{"zh-CN":"标题","en":"Title"}`
`description`	object	Multilingual description
`content`	object	Multilingual detail content
`seo_meta`	object	SEO metadata
`images`	string[]	Image URL list
`tags`	string[]	Tag list
`price_amount`	string	Actual selling price (member price if applicable)
`original_price`	string	Original price (only returned when member discount exists, `omitempty`)
`member_price`	string	Member price (only returned when member discount exists, `omitempty`)
`fulfillment_type`	string	Fulfillment type: `auto` / `manual`
`manual_form_schema`	object	Manual fulfillment form schema (required buyer input for `manual` type products)
`is_active`	boolean	Whether the product is active
`category_id`	number	Category ID
`skus`	array	SKU list (see SKU structure below)
`created_at`	string	Created time (ISO 8601)
`updated_at`	string	Updated time (ISO 8601)

SKU Structure

Field	Type	Description
`id`	number	SKU ID (use this ID when placing orders)
`sku_code`	string	SKU code
`spec_values`	object	Spec values, e.g. `{"Color":"Red","Size":"128GB"}`
`price_amount`	string	Actual selling price (member price if applicable)
`original_price`	string	Original price (only returned when member discount exists, `omitempty`)
`member_price`	string	Member price (only returned when member discount exists, `omitempty`)
`stock_status`	string	Stock status: `unlimited` / `in_stock` / `low_stock` / `out_of_stock`
`stock_quantity`	number	Stock quantity (-1 = unlimited)
`is_active`	boolean	Whether the SKU is active

Stock Status Reference

unlimited: Unlimited stock (stock_quantity = -1)
in_stock: Sufficient (> 20)
low_stock: Low stock (1–20)
out_of_stock: Sold out (0)

Response example:

json

{
  "ok": true,
  "items": [
    {
      "id": 1,
      "slug": "example-product",
      "title": { "zh-CN": "示例商品", "en": "Example Product" },
      "description": { "zh-CN": "这是一个示例" },
      "content": {},
      "seo_meta": {},
      "images": ["https://example.com/img1.jpg"],
      "tags": ["hot"],
      "price_amount": "7.90",
      "original_price": "9.90",
      "member_price": "7.90",
      "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.90",
          "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
}

4.4 GET `/products/:id`

Fetch product details by ID.

Path parameter:

Param	Type	Description
`id`	number	Product ID

Response fields:

Field	Type	Description
`ok`	boolean	Success flag
`product`	object	Product structure (same as section 4.3)

Error codes:

error_code	HTTP Status	Description
`product_not_found`	404	Product not found
`product_unavailable`	404	Product is inactive

4.5 POST `/orders`

Create a procurement order. The system automatically deducts from the API user's wallet balance — no separate payment step required.

Request body:

Field	Type	Required	Description
`sku_id`	number	Yes	SKU ID (from `skus[].id` in the product list)
`quantity`	number	Yes	Quantity, must be ≥ 1
`manual_form_data`	object	No	Manual fulfillment form data (required when product is `manual` type)
`downstream_order_no`	string	No	Downstream order number (recommended globally unique, for idempotency and callback matching)
`trace_id`	string	No	Caller trace ID
`callback_url`	string	No	Callback URL (must be a publicly accessible HTTP/HTTPS address)

Idempotency

The same API Key + downstream_order_no combination cannot create duplicate orders. Repeat submissions return the existing order info.

Success response (ok: true):

Field	Type	Description
`ok`	boolean	`true`
`order_id`	number	Upstream order ID
`order_no`	string	Upstream order number
`status`	string	Order status (typically `paid`)
`amount`	string	Order amount
`currency`	string	Currency

Success response example:

json

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

Business failure (HTTP 200, ok: false):

json

{
  "ok": false,
  "order_id": 101,
  "order_no": "DJ20260301120000ABCD",
  "status": "canceled",
  "error_code": "payment_failed",
  "error_message": "wallet payment failed: insufficient balance"
}

When wallet balance is insufficient or payment fails, the order is auto-canceled and ok: false is returned.

Error codes:

error_code	HTTP Status	Description
`bad_request`	400	Invalid request parameters
`invalid_callback_url`	400	Callback URL is illegal (private network/localhost, etc.)
`sku_unavailable`	400	SKU not found or inactive
`product_unavailable`	400	Product not available
`insufficient_balance`	402	Insufficient wallet balance
`insufficient_stock`	409	Insufficient stock
`payment_failed`	200	Wallet payment failed (`ok: false`)

4.6 GET `/orders/:id`

Query procurement order details.

Path parameter:

Param	Type	Description
`id`	number	Order ID (from `order_id` returned when creating the order)

Response fields:

Field	Type	Description
`ok`	boolean	Success flag
`order_id`	number	Order ID
`order_no`	string	Order number
`status`	string	Order status
`amount`	string	Order amount
`currency`	string	Currency
`items`	array	Order items list (see below)
`fulfillment`	object	Fulfillment info (only present when delivered, see below)

items[] fields:

Field	Type	Description
`product_id`	number	Product ID
`sku_id`	number	SKU ID
`title`	object	Multilingual title
`quantity`	number	Quantity
`unit_price`	string	Unit price
`total_price`	string	Subtotal
`fulfillment_type`	string	Fulfillment type

fulfillment fields (only when status is delivered):

Field	Type	Description
`type`	string	Fulfillment type (`auto` / `manual`)
`status`	string	Fulfillment status (`delivered`)
`payload`	string	Delivery content (card keys, text, etc.)
`delivery_data`	object	Structured delivery data
`delivered_at`	string	Delivery time (ISO 8601)

Response example:

json

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

4.7 POST `/orders/:id/cancel`

Cancel a procurement order.

Path parameter:

Param	Type	Description
`id`	number	Order ID

Request: No body required.

Success response:

Field	Type	Description
`ok`	boolean	`true`
`order_id`	number	Order ID
`order_no`	string	Order number
`status`	string	Status after cancellation (`canceled`)

Error codes:

error_code	HTTP Status	Description
`order_not_found`	404	Order not found
`cancel_not_allowed`	409	Order cannot be canceled in current status

5. Callback Endpoint

5.1 POST `/api/v1/upstream/callback`

Site B proactively pushes order status changes and delivery content to Site A.

Callback triggers:

Order status changes (paid → completed, canceled, etc.)
Delivery content generated (auto card delivery, manual fulfillment complete)

Callback authentication:

Site B signs with the api_key / api_secret configured in Site A's connection settings. Site A verifies using the same algorithm.

Request headers:

Header	Description
`Dujiao-Next-Api-Key`	API Key configured in Site A's "Site Connection"
`Dujiao-Next-Timestamp`	Unix timestamp (seconds)
`Dujiao-Next-Signature`	HMAC-SHA256 signature

Request body:

Field	Type	Required	Description
`event`	string	No	Event type
`order_id`	number	Yes	Site B order ID
`order_no`	string	No	Site B order number
`downstream_order_no`	string	Yes	Site A local order number (for matching procurement orders)
`status`	string	Yes	Order status
`fulfillment`	object	No	Fulfillment info (see below)
`timestamp`	number	No	Event timestamp

fulfillment sub-object:

Field	Type	Description
`type`	string	Fulfillment type (`auto` / `manual`)
`status`	string	Fulfillment status (`delivered`)
`payload`	string	Delivery content (card keys, text, etc.)
`delivery_data`	object	Structured delivery data
`delivered_at`	string	Delivery time (ISO 8601)

Callback status mapping:

Upstream status	Site A handles as
`delivered` / `completed`	`delivered` (triggers local fulfillment)
`canceled`	`canceled` (triggers local cancellation)
Others	Passed through as-is

Callback success response:

json

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

Callback failure response:

json

{ "ok": false, "message": "reason" }

6. Order Status Reference

Status	Description
`pending_payment`	Pending payment
`paid`	Paid (awaiting fulfillment)
`fulfilling`	Fulfilling (delivery in progress)
`partially_delivered`	Partially delivered
`delivered`	Delivered
`completed`	Completed
`canceled`	Canceled

7. Error Code Reference

7.1 Authentication Errors (HTTP 401 / 403)

error_code	Description
`missing_auth_headers`	Missing authentication headers
`invalid_timestamp`	Invalid timestamp format
`timestamp_expired`	Timestamp expired (beyond ±60 seconds)
`invalid_signature`	Signature verification failed
`invalid_api_key`	API Key is invalid or disabled
`user_disabled`	User account associated with API Key is banned

7.2 Business Errors

error_code	HTTP Status	Description
`bad_request`	400	Invalid request parameters
`invalid_callback_url`	400	Callback URL is illegal
`sku_unavailable`	400	SKU not found or inactive
`product_unavailable`	400	Product not found or inactive
`product_not_found`	404	Product not found
`order_not_found`	404	Order not found
`insufficient_balance`	402	Insufficient wallet balance
`insufficient_stock`	409	Insufficient stock
`cancel_not_allowed`	409	Order cannot be canceled
`payment_failed`	200	Wallet payment failed (`ok: false`)
`internal_error`	500	Internal server error

8. Integration Workflow & Best Practices

8.1 Standard Integration Flow

1. Site B user enables API access and generates API Key / Secret
2. Site A admin creates a "Site Connection" with Site B's URL and credentials
3. Site A calls POST /ping to test connectivity
4. Site A calls GET /products to fetch product list
5. Site A creates product mappings in admin panel (local product → upstream product/SKU)
6. End user places order on Site A → Site A asynchronously calls POST /orders to procure from Site B
7. Site B processes order and fulfills → pushes callback to Site A
8. Site A updates local order status based on callback

8.2 Idempotency & Retry

downstream_order_no serves as idempotency key: same API Key + same downstream_order_no creates only one order.
Implement exponential backoff retry for all write operations (e.g. 1s → 2s → 4s).
Query endpoints can be polled but should be rate-limited.

8.3 Callback Reliability

Site B pushes callbacks to the callback_url provided during order creation when delivery/status changes occur.
Site A should also implement polling fallback: periodically call GET /orders/:id to check order status.
Callbacks may fail due to network issues; Site A should handle idempotently.

8.4 Security Requirements

callback_url must not point to private networks (localhost, 127.0.0.1, private IP ranges, etc.).
Signatures use HMAC-SHA256; the Secret is only shown once at creation time — store it securely.
All communications should use HTTPS.

9. Signature Implementation Examples

Go

package main

import (
    "crypto/hmac"
    "crypto/md5"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "time"
)

func sign(secret, method, path string, timestamp int64, body []byte) string {
    h := md5.New()
    h.Write(body)
    bodyMD5 := hex.EncodeToString(h.Sum(nil))
    signString := fmt.Sprintf("%s\n%s\n%d\n%s", method, path, timestamp, bodyMD5)
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(signString))
    return hex.EncodeToString(mac.Sum(nil))
}

func main() {
    secret := "your_api_secret"
    method := "POST"
    path := "/api/v1/upstream/orders"
    body := []byte(`{"sku_id":1,"quantity":1}`)
    ts := time.Now().Unix()

    sig := sign(secret, method, path, ts, body)
    fmt.Println("Signature:", sig)
    fmt.Println("Timestamp:", ts)
}

Python

python

import hashlib, hmac, time, json, requests

api_key = "your_api_key"
api_secret = "your_api_secret"
base_url = "https://api.example.com"

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):
    ts = int(time.time())
    body_bytes = json.dumps(body).encode() if body else b""
    sig = sign(api_secret, method, path, ts, body_bytes)
    headers = {
        "Dujiao-Next-Api-Key": api_key,
        "Dujiao-Next-Timestamp": str(ts),
        "Dujiao-Next-Signature": sig,
        "Content-Type": "application/json",
    }
    resp = requests.request(method, base_url + path, headers=headers, data=body_bytes)
    return resp.json()

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

# Fetch products
print(api_request("GET", "/api/v1/upstream/products"))

# Create order
print(api_request("POST", "/api/v1/upstream/orders", {
    "sku_id": 1,
    "quantity": 1,
    "downstream_order_no": "A-20260301-001",
    "callback_url": "https://a-site.example.com/api/v1/upstream/callback",
}))

PHP

php

<?php
function dujiaoSign(string $secret, string $method, string $path, int $timestamp, string $body): string {
    $bodyMD5 = md5($body);
    $signString = "{$method}\n{$path}\n{$timestamp}\n{$bodyMD5}";
    return hash_hmac('sha256', $signString, $secret);
}

$apiKey = 'your_api_key';
$apiSecret = 'your_api_secret';
$baseUrl = 'https://api.example.com';

$method = 'POST';
$path = '/api/v1/upstream/orders';
$body = json_encode(['sku_id' => 1, 'quantity' => 1, 'downstream_order_no' => 'A-001']);
$timestamp = time();
$signature = dujiaoSign($apiSecret, $method, $path, $timestamp, $body);

$ch = curl_init($baseUrl . $path);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        "Dujiao-Next-Api-Key: {$apiKey}",
        "Dujiao-Next-Timestamp: {$timestamp}",
        "Dujiao-Next-Signature: {$signature}",
    ],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Site Integration Open API ​

1. Basics ​

1.1 Base URL ​

1.2 Unified Response Envelope ​

1.3 Runtime Constraints (Important) ​

2. Authentication & Signature ​

2.1 Required Headers ​

2.2 Signature Algorithm ​

2.3 Signature Pseudocode ​

2.4 Validation Rules ​

3. Endpoint List ​

4. Core Endpoints ​

4.1 POST /ping ​

4.2 GET /categories ​

Category Structure ​

4.3 GET /products ​

Product Structure ​

SKU Structure ​

4.4 GET /products/:id ​

4.5 POST /orders ​

4.6 GET /orders/:id ​

4.7 POST /orders/:id/cancel ​

5. Callback Endpoint ​

5.1 POST /api/v1/upstream/callback ​

6. Order Status Reference ​

7. Error Code Reference ​

7.1 Authentication Errors (HTTP 401 / 403) ​

7.2 Business Errors ​

8. Integration Workflow & Best Practices ​

8.1 Standard Integration Flow ​

8.2 Idempotency & Retry ​

8.3 Callback Reliability ​

8.4 Security Requirements ​

9. Signature Implementation Examples ​

Go ​

Python ​

PHP ​

Site Integration Open API

1. Basics

1.1 Base URL

1.2 Unified Response Envelope

1.3 Runtime Constraints (Important)

2. Authentication & Signature

2.1 Required Headers

2.2 Signature Algorithm

2.3 Signature Pseudocode

2.4 Validation Rules

3. Endpoint List

4. Core Endpoints

4.1 POST `/ping`

4.2 GET `/categories`

Category Structure

4.3 GET `/products`

Product Structure

SKU Structure

4.4 GET `/products/:id`

4.5 POST `/orders`

4.6 GET `/orders/:id`

4.7 POST `/orders/:id/cancel`

5. Callback Endpoint

5.1 POST `/api/v1/upstream/callback`

6. Order Status Reference

7. Error Code Reference

7.1 Authentication Errors (HTTP 401 / 403)

7.2 Business Errors

8. Integration Workflow & Best Practices

8.1 Standard Integration Flow

8.2 Idempotency & Retry

8.3 Callback Reliability

8.4 Security Requirements

9. Signature Implementation Examples

Go

Python

PHP