返回首页

POST API 购买下单
https://dcshop.xzsc.cc/user/api.php?action=order_buy
接口说明

在主站代为下单购买商品。此接口会完成以下操作:

  1. 幂等防重 — 根据 out_trade_no 查重,同一商户单号不会重复扣费
  2. 库存校验 — 检查商品库存是否充足
  3. 价格计算 — 按你的 API 对接账号的会员等级计算专属折扣价
  4. 余额扣除 — 从你的主站余额中扣除订单金额
  5. 自动发货 — 创建订单后立即触发发货流程
  6. 返回结果 — 返回订单号、发货内容(卡密)、订单状态
请求参数
参数类型必填传参方式说明
actionstringGET固定值 order_buy(必须放在 URL 参数中)
api_keystringPOSTAPI 对接密钥
goods_idintPOST要购买的商品 ID
quantityintPOST购买数量,最小为 1
skustringPOSTSKU 标识。无规格商品传 "0" 或不传;多规格商品传 goods_detail 返回的 skus[].sku
out_trade_nostringPOST你方的商户订单号,用于幂等防重和后续查询
notify_urlstringPOST异步回调通知地址。如果传入,订单完成发货或发生退款时,系统将主动向该地址发送 POST 通知
input_valuestringPOST自定义输入框表单数据。如果商品详情中有用户输入字段,可以通过 JSON 字符串传入,如 {"游戏账号":"xxx","游戏密码":"yyy"},或者直接将输入框名称作为 POST 参数名传入
请求示例
cURL
curl -X POST "https://主站域名/user/api.php?action=order_buy" \
  -d "api_key=YOUR_API_KEY" \
  -d "goods_id=12" \
  -d "quantity=1" \
  -d "sku=0" \
  -d "out_trade_no=DOCK202605311200001"
PHP
$ch = curl_init('https://主站域名/user/api.php?action=order_buy');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'api_key'      => 'YOUR_API_KEY',
        'goods_id'     => 12,
        'quantity'     => 1,
        'sku'          => '0',
        'out_trade_no' => 'DOCK202605311200001',
    ]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_SSL_VERIFYPEER => false,
]);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
返回示例(自动发货商品 - 立即得到卡密)
{
    "code": 0,
    "msg": "ok",
    "data": {
        "order_id": "20260531120000123456",
        "content": "账号:example@email.com\n密码:abc123456",
        "status": 2
    }
}
返回示例(人工发货商品 - 需要等待卖家发货)
{
    "code": 0,
    "msg": "ok",
    "data": {
        "order_id": "20260531120000789012",
        "content": "您的订单正在处理中,请等待人工发货...",
        "status": 1
    }
}
返回字段说明
字段类型说明
order_idstring主站本地订单号,用于后续 order_query 查询
contentstring发货内容(卡密/服务信息)。自动发货商品会立即返回,人工发货商品可能返回占位文字
statusint订单状态:1 = 待发货,2 = 已完成
⚠️ 关键:必须用 status 字段判断是否已发货!

对于人工发货类商品(如虚拟服务),content 可能包含系统模板自动填充的占位文字(如"您的订单正在处理中"),但此时实际并未完成人工发货。

正确做法:status ≥ 2 作为"已发货/已完成"的唯一判断条件。
错误做法:仅以 content 非空就认为已完成。
幂等机制说明

如果你传入的 out_trade_no 已经下过单,系统不会重复扣费,而是直接返回之前的订单信息和发货内容。这意味着在网络超时时你可以安全地重试请求。

常见错误
错误信息原因建议处理
缺少商品IDgoods_id 未传或 ≤ 0检查请求参数
缺少商户订单号 (out_trade_no)out_trade_no 为空生成唯一商户单号
商品不存在或已下架商品 ID 无效或已下架重新同步商品列表
商品规格不存在传入的 sku 值不匹配重新获取商品详情确认 SKU
商品库存不足,当前剩余:N库存不足减少购买数量或等待补货
扣款失败,货源账户余额不足你的主站账户余额不够支付订单去主站充值余额
GET 查询订单状态与发货内容
https://dcshop.xzsc.cc/user/api.php?action=order_query
接口说明

查询已下单的订单状态和发货内容。支持通过主站订单号或你方商户单号两种方式查询。

此接口是对接人工发货类商品的核心轮询接口。当 order_buy 返回 status=1 时,你应该定时调用此接口查询发货状态,直到 status ≥ 2 表示发货完成。

请求参数
参数类型必填传参方式说明
actionstringGET固定值 order_query
api_keystringGETAPI 对接密钥
order_idstring二选一GET主站本地订单号(order_buy 返回的 order_id
out_trade_nostring二选一GET你方商户订单号(下单时传入的 out_trade_no
order_idout_trade_no 任传其一即可。如果两者都传,优先用 order_id 查询。
请求示例
// 方式一:用主站订单号查询
GET /user/api.php?action=order_query&order_id=20260531120000123456&api_key=YOUR_API_KEY

// 方式二:用你方商户单号查询
GET /user/api.php?action=order_query&out_trade_no=DOCK202605311200001&api_key=YOUR_API_KEY
返回示例(已发货)
{
    "code": 0,
    "msg": "ok",
    "data": {
        "order_id": "20260531120000123456",
        "out_trade_no": "DOCK202605311200001",
        "amount": 29.90,
        "status": 2,
        "pay_time": 1717132800,
        "content": "账号:example@email.com\n密码:abc123456"
    }
}
返回示例(待发货)
{
    "code": 0,
    "msg": "ok",
    "data": {
        "order_id": "20260531120000789012",
        "out_trade_no": "DOCK202605311200002",
        "amount": 99.00,
        "status": 1,
        "pay_time": 1717132800,
        "content": ""
    }
}
返回字段说明
字段类型说明
order_idstring主站本地订单号
out_trade_nostring你方商户订单号
amountfloat订单实付金额,单位:元
statusint订单状态:1 = 待发货,2 = 已完成,3 = 已退款
pay_timeint支付时间,Unix 时间戳
contentstring发货内容(卡密/服务信息),仅 status ≥ 2 时有效
订单状态值对照
status含义说明
0待支付一般不会出现在 API 下单结果中
1待发货已支付但未完成发货(人工发货类商品)
2已完成已完成发货,content 中有卡密/发货内容
3已退款订单已退款
常见错误
错误信息原因
缺少本地单号 (order_id) 或商户单号 (out_trade_no)两个查询参数都没有传
订单不存在订单号无效或不属于当前 API 账号
订单明细不存在订单数据异常,请联系管理员
GET 查询账户信息
https://dcshop.xzsc.cc/user/api.php?action=user_info
接口说明

查询当前 API 对接账号的余额、UID、会员等级等信息。可用于对接端在配置页展示余额状态,或在下单前预检余额是否充足。

请求参数
参数类型必填传参方式说明
actionstringGET固定值 user_info
api_keystringGETAPI 对接密钥
请求示例
GET /user/api.php?action=user_info&api_key=YOUR_API_KEY
返回示例
{
    "code": 0,
    "msg": "ok",
    "data": {
        "uid": 8,
        "money": 1520.50,
        "level_name": "黄金代理"
    }
}
返回字段说明
字段类型说明
uidint用户 UID
moneyfloat账户余额,单位:元
level_namestring当前会员等级名称,如"普通会员"、"黄金代理"等

通用鉴权错误码

以下错误在所有接口中都可能出现:

错误信息HTTP 状态码原因解决方案
缺少API对接密钥 (api_key)400未传入 api_key 参数确保在 GET 或 POST 中传入 api_key
API密钥无效400密钥不存在或已被重置联系主站管理员确认密钥
对接账户已被禁用400对接账号被管理员禁用联系主站管理员解禁
请求IP [x.x.x.x] 未在白名单中400你的服务器 IP 不在主站白名单内联系主站管理员添加你的服务器 IP