开发者文档 / 开放接口
开放 API 接入文档
异次元按图完成货源对接；Dujiao-Next 查看签名、商品与订单接口。
异次元货源对接教程
先在本站取得商户资料，再回到你自己的网站接入货源。
先确认对接方式：本教程适用于异次元的「店铺共享」功能，使用商户ID＋商户密钥。如果你的网站使用 Dujiao-Next，请查看下方 Dujiao-Next 接入说明。
配图按实际界面字段整理为操作示意。账号、地址与密钥均已隐藏，不对应真实资料；不同版本的按钮名称可能略有差异。
注册、登录并取得商户资料
在本站操作注册并登录本站会员账号，进入会员中心首页，在个人资料区找到商户ID和商户密钥，保存好这两项资料。
- 商户ID与商户密钥必须来自同一个本站会员账号。
- 这里使用的是商户密钥，部分版本也称通信密钥；不要填成登录密码或 Dujiao-Next 的 API Secret。
打开会员中心 （未登录时会要求登录）
在你的网站新增共享店铺
在你的网站操作打开你自己网站的管理后台，进入「店铺共享」，点击「新增店铺」，按下表填写。
| 填写项 | 应该填写什么 |
|---|---|
| 协议 | 选择异次元（3.0）。部分版本显示为「异次元（v3.1.2重构后全新版）」或类似名称，选择对应的异次元新版协议。 |
| 店铺地址 | 本站首页的完整根地址，保留协议与域名。不要填写你自己的网站地址，也不要添加文档页或接口路径。 |
| 商户ID / API Key | 填写第1步取得的商户ID。 |
| 商户密钥 / API Secret | 填写第1步取得的商户密钥。 |
某些版本会共用「商户ID / API Key」「商户密钥 / API Secret」字段名称。选择异次元协议后，应填商户ID和商户密钥；不使用本页下方申请的 Dujiao-Next 凭据。
确认连接正常，再接入资源
在你的网站操作确认并保存后，回到「店铺共享」列表，检查对应店铺的状态。显示正常后，点击该行的接入资源按钮；部分版本显示为插头图标。
商品较多时，读取分类和商品需要一些时间。等待本次加载完成，不要连续点击反复发起请求。若失败，先按下方的排查表检查。
选择本地分类、价格与远程商品
在你的网站操作- 选择商品要放入的本地分类；分类应先在你的网站创建好。
- 按经营需求设置价格主从同步、商品数量同步与立即上架。第一次可先关闭「立即上架」，检查后再开放购买。
- 设置加价模式和加价数额，再展开远程分类，勾选要接入的商品。
- 首次建议只选择1～2个商品，点击「确认」。核对导入结果后再逐步增加数量。
| 加价模式 | 示例 | 得到的售价 |
|---|---|---|
| 普通金额加价 | 成本 10 元，加价数额填 1 | 11 元 |
| 百分比加价 | 成本 10 元，加价数额填 0.1（加价10%） | 11 元 |
本站对应版本的百分比按小数填写。你的网站若标注了不同单位，请以其提示与导入后的实际售价为准，避免把10%误填成10。
接入后，先完成这几项检查
- 在你的网站核对商品名称、规格、库存、售价和上下架状态。
- 确认本站供货账号的余额足够后续采购。导入建立商品映射，真实采购订单会使用供货账号余额。
- 准备好后再自行进行少量真实订单测试，核对采购与发货结果；确认正常后再批量接入。
连接失败或价格异常时，如何排查？
| 遇到的情况 | 优先检查 |
|---|---|
| 商户ID不存在 / 密钥错误 | 确认使用本站同一账号的商户ID和商户密钥，检查是否多复制空格。若重置过密钥，需要同步更新你的网站配置。 |
| 无法连接 / 提示疑似防火墙拦截 | 先核对根地址、协议和凭据。此类提示也可能由网络或超时引起，不能只凭提示判断为防火墙；保留完整报错联系管理员核查。 |
| 资源加载较慢 | 等待当前请求完成，避免重复点击；首次少量选择商品。持续超时请联系你的网站维护人员核查网络与超时设置。 |
| 没有商品 / 没有选中商品 | 展开远程分类并勾选具体商品，同时选择本地分类；确认上游商品当前开放对接。 |
| 导入后售价不符合预期 | 检查普通加价与百分比加价是否选对、百分比单位和价格主从同步设置，再核对实际售价。 |
使用 Dujiao-Next 的站长，请继续查看 Dujiao-Next 接入与 API 文档。
Dujiao-Next 快速开始
使用本站 Dujiao-Next 开放接口，同步商品与 SKU、以会员余额采购，并接收交付结果。
- 开通 API 并保存凭据登录本站会员账号，填写接入信息，获得 API Key 与 API Secret。
- 配置上游并同步商品Dujiao-Next 的 Base URL 填本站根地址；自行开发时，按下方签名规则调用接口。
- 采购并接收交付建立 SKU 映射，使用唯一的下游订单号采购，通过查询或回调获取交付内容。
上方为 Dujiao-Next 配置用的站点根地址；HTTP 接口完整前缀见「基础规则」。
开通与凭据
登录本站账号，提交对接信息后即可申请 Open API 权限。凭据与当前会员账号关联。
开启自动审批时，余额不低于 ¥5 的会员可自动开通；其他情况请等待管理员审核。
正在读取开通状态…
基础规则
请求与会员凭据所属的站点保持同源。本文示例会随当前访问域名显示。
HTTP 接口前缀
请求体使用 application/json，字符编码为 UTF-8。所有下列商品与订单接口均需签名认证。
统一响应
成功响应包含 ok: true 和该接口对应的数据字段。
{
"ok": true
}失败响应包含错误码与说明；请同时检查 HTTP 状态码。
{
"ok": false,
"error_code": "invalid_signature",
"error_message": "invalid signature"
}签名认证
| 请求头 | 含义 |
|---|---|
Dujiao-Next-Api-Key | 开通后获得的 API Key |
Dujiao-Next-Timestamp | 10 位 Unix 秒级时间戳，与服务器时间偏差不超过 60 秒 |
Dujiao-Next-Signature | 以 API Secret 计算的 HMAC-SHA256，小写十六进制 |
签名原文
以下四项用换行符 \n 连接，末尾不添加换行。
{METHOD}
{PATH}
{TIMESTAMP}
{BODY_MD5}METHOD：大写 HTTP 方法，例如 GET、POST。PATH：完整接口路径，例如/api/v1/upstream/products，不含域名与查询字符串。TIMESTAMP：与请求头完全一致的秒级时间戳。BODY_MD5：实际发送的原始请求体字节的 MD5，小写十六进制。无请求体时使用空字节串的 MD5。
签名完成后不要重新序列化 JSON。空请求体与
{} 的签名不同；带分页参数的 GET 请求仍只签名 URL 路径。Python 请求示例
替换示例凭据后在你自己的服务端运行；不要把 API Secret 放入公开网页。
import hashlib
import hmac
import json
import time
from urllib.parse import urlsplit
import requests
API_KEY = "your_api_key"
API_SECRET = "your_api_secret"
BASE_URL = "{{CURRENT_ORIGIN}}"
def api_request(method, path, payload=None):
method = method.upper()
timestamp = str(int(time.time()))
body = (json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
.encode("utf-8") if payload is not None else b"")
sign_path = urlsplit(path).path # 不包含 ?page=1 等查询参数
canonical = "\n".join((method, sign_path, timestamp,
hashlib.md5(body).hexdigest()))
signature = hmac.new(API_SECRET.encode("utf-8"),
canonical.encode("utf-8"), hashlib.sha256).hexdigest()
response = requests.request(
method, BASE_URL + path, data=body, timeout=30,
headers={
"Dujiao-Next-Api-Key": API_KEY,
"Dujiao-Next-Timestamp": timestamp,
"Dujiao-Next-Signature": signature,
"Content-Type": "application/json",
},
)
result = response.json()
if not response.ok or result.get("ok") is not True:
raise RuntimeError(result.get("error_message", "API 请求失败"))
return result
# 只测试连接，不创建订单
print(api_request("POST", "/api/v1/upstream/ping"))
# 分页查询示例：api_request("GET", "/api/v1/upstream/products?page=1&page_size=20")连接测试
POST
/api/v1/upstream/ping无请求体。用于确认凭据、签名与余额，balance 为当前会员余额。
{
"ok": true,
"site_name": "你的站点名称",
"protocol_version": "1.0",
"user_id": 42,
"balance": "1000.00",
"currency": "CNY",
"member_level": null
}分类列表
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
}
]
}商品列表与库存
GET
/api/v1/upstream/products?page=1&page_size=20&include_inactive=true| 查询参数 | 默认值 | 说明 |
|---|---|---|
page | 1 | 页码，从 1 开始 |
page_size | 20 | 每页数量，最多 100 |
include_inactive | false | 传 true 时，包含下架及曾开放 API 后关闭的商品，以同步不可售状态 |
updated_after | 可选 | 当前兼容接收此参数，仍按全量授权商品分页返回；请按商品 ID 合并 |
Dujiao-Next v1.3.1 同步商品时会追加
include_inactive=true。
本接口会在该模式下同时返回已下架、关闭 Open API 但曾同步过、以及当前缺货的商品。
is_active 只表示商品或 SKU 是否上架/启用；库存单独通过
stock_status 和 stock_quantity 表达。
{
"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.90",
"currency": "CNY",
"fulfillment_type": "auto",
"manual_form_schema": null,
"is_active": true,
"category_id": 1,
"skus": [
{
"id": 1,
"sku_code": "DEFAULT_1",
"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,
"includes_inactive": true
}默认不传 include_inactive 时，仅返回当前已上架且开放 Open API 的商品；已上架但暂时缺货的商品仍会返回。
已启用但缺货的 SKU 示例（注意 is_active 仍为 true）：
{
"id": 2,
"sku_code": "DEFAULT_2",
"spec_values": {},
"price_amount": "7.90",
"original_price": "9.90",
"member_price": "7.90",
"stock_status": "out_of_stock",
"stock_quantity": 0,
"is_active": true
}商品下架或关闭 Open API 时，is_active=false，并返回 stock_status=out_of_stock、stock_quantity=0。
价格与可售范围以当前凭据所属会员为准；库存可能随上游变化，创建订单时仍会再次校验。下单使用 skus[].id，不要把商品 ID 直接作为 SKU ID。
人工交付等不限量 SKU 可返回 stock_quantity=-1、stock_status=unlimited；不要把 -1 当作缺货。
商品详情
GET
/api/v1/upstream/products/{id}
对已下架或曾经同步过但后来关闭 Open API 的商品，接口返回
ok=true
且 product.is_active=false，便于 Dujiao-Next 1.3.1 将本地商品标记为不可售。
不存在或从未开放给 Open API 的商品仍返回 404。
product_not_found：商品不存在product_unavailable：商品不可用
成功响应形如 {"ok": true, "product": {...}}；product 的字段结构与列表中的单个商品相同。
创建采购订单
| 请求字段 | 要求 | 说明 |
|---|---|---|
sku_id | 必填 | 从商品接口获取的 SKU ID，正整数 |
quantity | 必填 | 采购数量，正整数 |
downstream_order_no | 建议必填 | 你的下游订单号，同一 API Key 下保持唯一；同一订单重试时沿用 |
callback_url | 可选 | 你的下游公网回调地址，建议 HTTPS |
trace_id | 可选 | 自定义追踪标识 |
manual_form_data | 按商品要求 | 按 manual_form_schema 提交对应人工交付字段 |
POST
/api/v1/upstream/orders{
"sku_id": 1,
"quantity": 1,
"manual_form_data": {},
"downstream_order_no": "A-20260412-0001",
"trace_id": "trace-001",
"callback_url": "https://your-downstream.example/api/v1/upstream/callback"
}{
"ok": true,
"order_id": 101,
"order_no": "DJ20260301120000ABCD",
"status": "paid",
"amount": "9.90",
"currency": "CNY"
}本接口会使用会员余额真实采购。创建成功不代表已交付，请继续查询订单或接收回调。网络超时后请先核对订单，重试保持原下游订单号；不要更换订单号重复采购。
查询采购订单
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"
}
}{id} 使用创建订单返回的 order_id。仅能查询当前凭据所属会员的订单；尚未交付时可能没有 fulfillment 字段。
取消订单限制
POST
/api/v1/upstream/orders/{id}/cancel当前余额采购订单不支持通过 API 取消。对存在且归属当前会员的订单，此兼容入口返回 HTTP 409：
{
"ok": false,
"error_code": "cancel_not_allowed",
"error_message": "current order status cannot be canceled"
}请勿把调用取消接口作为退款成功的依据。如需售后，请联系本站管理员处理。
订单状态回调
订单状态变化后，本站向你创建订单时提交的 callback_url 发送通知。这是你需要提供的下游接收接口。
POST
https://your-downstream.example/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"
}验签与确认
- 使用同一 API Key / Secret 与三项
Dujiao-Next-*请求头，按原始请求体验签。 - 回调的签名路径固定为
/api/v1/upstream/callback；即使实际接收地址采用其他路径，也使用此固定值验签。 - 接收端返回 HTTP 2xx，且 JSON 的
ok必须为布尔值true，本站才会记为送达成功。 - 同一状态事件自动最多尝试 8 次（含首次），失败重试间隔至少 60 秒。请按订单和事件状态幂等处理，必要时调用查询接口补偿。
- 回调需要同时提供非空
callback_url与downstream_order_no。地址需通过公网 URL 校验，不能指向本地或内网。
接口速查
以下路径均相对于 /api/v1/upstream。回调地址由下游提供，不属于本站的请求接口列表。
| 方法 | 接口路径 | 用途 |
|---|---|---|
| POST | /ping | 验证签名与查询余额 |
| GET | /categories | 分类列表 |
| GET | /products | 商品、SKU、库存与价格 |
| GET | /products/{id} | 单个商品详情 |
| POST | /orders | 使用余额采购 |
| GET | /orders/{id} | 订单与交付结果 |
| POST | /orders/{id}/cancel | 兼容入口，当前不支持取消 |
状态值说明
| 订单 status | 含义 |
|---|---|
pending_payment | 待支付 |
paid | 已支付，等待交付处理 |
fulfilling | 共享或人工商品处理中 |
completed | 已交付完成 |
canceled | 已取消或退款状态映射 |
以上为订单状态。交付结果独立放在 fulfillment 中；其中 fulfillment.status = delivered 表示已交付，payload 为交付原文。
错误码说明
| 错误码 | 含义 | 处理建议 |
|---|---|---|
service_disabled | API 服务未启用（503） | 等待管理员启用服务 |
too_many_auth_failures | 验证失败过多（429） | 核对凭据并稍后再试 |
not_found | 接口路径不存在（404） | 检查请求方法和完整路径 |
missing_auth_headers | 缺少签名请求头 | 检查三项 Dujiao-Next 请求头 |
invalid_timestamp | 时间戳格式错误 | 使用 10 位秒级时间戳 |
timestamp_expired | 时间偏差过大 | 同步时钟，重新生成签名 |
invalid_signature | 验签失败 | 检查方法、路径、原始请求体和 Secret |
invalid_api_key | API Key 不可用 | 核对凭据和开通状态 |
user_disabled | 会员账号已停用 | 联系管理员核对账号 |
bad_request | 请求参数有误 | 检查 JSON 和必填字段 |
invalid_callback_url | 回调地址不合法 | 使用允许的公网 HTTP(S) 地址 |
sku_unavailable | SKU 不可用 | 重新同步 SKU 映射 |
product_unavailable | 商品不可售 | 同步商品状态后再采购 |
product_not_found | 商品不存在或未开放 | 核对商品 ID 和开放范围 |
order_not_found | 订单不可访问 | 使用本会员创建的订单 ID |
insufficient_balance | 余额不足 | 补足会员余额 |
insufficient_stock | 库存不足 | 刷新库存并调整数量 |
cancel_not_allowed | 不支持取消 | 联系管理员处理售后 |
payment_failed | 采购支付失败 | 核对订单状态后再决定下一步 |
internal_error | 服务处理失败 | 保留订单号并联系管理员 |
接入注意事项
- Dujiao-Next 上游配置填站点根地址，调用 HTTP 接口时使用完整路径，二者不要混淆。
- API Secret 仅在生成或重置时完整显示一次；重置会使旧 Secret 立即失效，请同步更新你的服务端配置。
- 状态与库存会变化，请持续同步不可售状态；不要仅凭缓存库存判断采购一定成功。
- 回调处理先验签再处理，并保持幂等；长时间未收到结果时通过查询订单补偿。
- 网络超时不代表订单未创建。保持原下游订单号，先核对结果，避免重复采购。
接入流程：开通凭据 → 测试连接 → 同步商品 / SKU → 余额采购 → 查询或回调获取交付。