POST
API 购买下单
https://dcshop.xzsc.cc/user/api.php?action=order_buy
接口说明
在主站代为下单购买商品。此接口会完成以下操作:
- 幂等防重 — 根据
out_trade_no 查重,同一商户单号不会重复扣费
- 库存校验 — 检查商品库存是否充足
- 价格计算 — 按你的 API 对接账号的会员等级计算专属折扣价
- 余额扣除 — 从你的主站余额中扣除订单金额
- 自动发货 — 创建订单后立即触发发货流程
- 返回结果 — 返回订单号、发货内容(卡密)、订单状态
请求参数
| 参数 | 类型 | 必填 | 传参方式 | 说明 |
action | string | 是 | GET | 固定值 order_buy(必须放在 URL 参数中) |
api_key | string | 是 | POST | API 对接密钥 |
goods_id | int | 是 | POST | 要购买的商品 ID |
quantity | int | 是 | POST | 购买数量,最小为 1 |
sku | string | 否 | POST | SKU 标识。无规格商品传 "0" 或不传;多规格商品传 goods_detail 返回的 skus[].sku 值 |
out_trade_no | string | 是 | POST | 你方的商户订单号,用于幂等防重和后续查询 |
notify_url | string | 否 | POST | 异步回调通知地址。如果传入,订单完成发货或发生退款时,系统将主动向该地址发送 POST 通知 |
input_value | string | 否 | POST | 自定义输入框表单数据。如果商品详情中有用户输入字段,可以通过 JSON 字符串传入,如 {"游戏账号":"xxx","游戏密码":"yyy"},或者直接将输入框名称作为 POST 参数名传入 |
请求示例
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"
$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_id | string | 主站本地订单号,用于后续 order_query 查询 |
content | string | 发货内容(卡密/服务信息)。自动发货商品会立即返回,人工发货商品可能返回占位文字 |
status | int | 订单状态:1 = 待发货,2 = 已完成 |
⚠️ 关键:必须用 status 字段判断是否已发货!
对于人工发货类商品(如虚拟服务),content 可能包含系统模板自动填充的占位文字(如"您的订单正在处理中"),但此时实际并未完成人工发货。
正确做法:以 status ≥ 2 作为"已发货/已完成"的唯一判断条件。
错误做法:仅以 content 非空就认为已完成。
幂等机制说明
如果你传入的 out_trade_no 已经下过单,系统不会重复扣费,而是直接返回之前的订单信息和发货内容。这意味着在网络超时时你可以安全地重试请求。
常见错误
| 错误信息 | 原因 | 建议处理 |
| 缺少商品ID | goods_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 表示发货完成。
请求参数
| 参数 | 类型 | 必填 | 传参方式 | 说明 |
action | string | 是 | GET | 固定值 order_query |
api_key | string | 是 | GET | API 对接密钥 |
order_id | string | 二选一 | GET | 主站本地订单号(order_buy 返回的 order_id) |
out_trade_no | string | 二选一 | GET | 你方商户订单号(下单时传入的 out_trade_no) |
order_id 和 out_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_id | string | 主站本地订单号 |
out_trade_no | string | 你方商户订单号 |
amount | float | 订单实付金额,单位:元 |
status | int | 订单状态:1 = 待发货,2 = 已完成,3 = 已退款 |
pay_time | int | 支付时间,Unix 时间戳 |
content | string | 发货内容(卡密/服务信息),仅 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、会员等级等信息。可用于对接端在配置页展示余额状态,或在下单前预检余额是否充足。
请求参数
| 参数 | 类型 | 必填 | 传参方式 | 说明 |
action | string | 是 | GET | 固定值 user_info |
api_key | string | 是 | GET | API 对接密钥 |
请求示例
GET /user/api.php?action=user_info&api_key=YOUR_API_KEY
返回示例
{
"code": 0,
"msg": "ok",
"data": {
"uid": 8,
"money": 1520.50,
"level_name": "黄金代理"
}
}
返回字段说明
| 字段 | 类型 | 说明 |
uid | int | 用户 UID |
money | float | 账户余额,单位:元 |
level_name | string | 当前会员等级名称,如"普通会员"、"黄金代理"等 |
通用鉴权错误码
以下错误在所有接口中都可能出现:
| 错误信息 | HTTP 状态码 | 原因 | 解决方案 |
| 缺少API对接密钥 (api_key) | 400 | 未传入 api_key 参数 | 确保在 GET 或 POST 中传入 api_key |
| API密钥无效 | 400 | 密钥不存在或已被重置 | 联系主站管理员确认密钥 |
| 对接账户已被禁用 | 400 | 对接账号被管理员禁用 | 联系主站管理员解禁 |
| 请求IP [x.x.x.x] 未在白名单中 | 400 | 你的服务器 IP 不在主站白名单内 | 联系主站管理员添加你的服务器 IP |