鱼果跨境 · API 对接文档
通过 REST API 对接本平台商品，支持商品查询、余额查询、自动/人工下单与查单。
自动发货 人工发货 余额扣款 下架即停供 幂等下单1. 接入说明
- 联系平台管理员申请 API Key（后台为用户充值余额并创建密钥）。
- 所有请求使用 HTTPS，Base URL：
https://www.yuguofb.com/api/v1/reseller - 请求头携带密钥：
X-Api-Key: 你的密钥（或使用Authorization: Bearer 你的密钥）。 - 商品下架后，列表不再返回且下单会失败，无需下游改动。
安全提示：请妥善保管 API Key。
2. 统一响应格式
{
"code": 0,
"message": "success",
"data": {}
}
| code | 含义 |
|---|---|
| 0 | 成功 |
| 401 | API Key 无效或已禁用 |
| 403 | 商品已下架 / IP 不在白名单 |
| 404 | 商品不存在或订单不存在 |
| 409 | 余额不足 / 库存不足 |
| 422 | 参数错误 |
| 429 | 请求过于频繁 |
3. 接口列表
3.1 商品列表
GET https://www.yuguofb.com/api/v1/reseller/products
返回已上架商品（含自动发货与人工发货）。字段：id, name, price, stock, min_qty, max_qty, type, category。其中 type 为 auto（自动发货）或 manual（人工发货）。
3.2 商品详情
GET https://www.yuguofb.com/api/v1/reseller/products/{id}
3.3 余额查询
GET https://www.yuguofb.com/api/v1/reseller/balance
3.4 创建订单
POST https://www.yuguofb.com/api/v1/reseller/orders
Content-Type: application/json
X-Api-Key: your_api_key
{
"product_id": 1024,
"quantity": 1,
"client_order_id": "your-unique-id-001"
}
client_order_id 建议传入下游唯一订单号，重复提交将返回同一结果（幂等）。
自动发货（type=auto）：下单成功后 status 为 completed，并立即返回 delivery（卡密数组）。
人工发货（type=manual）：下单成功后 status 为 processing（不是 completed），此时通常还没有 delivery。平台后台人工发货完成后，订单变为 completed 并带上 delivery。下游需轮询「查询订单」接口获取最终结果。
人工订单对接提示
下单成功仅表示本平台已扣款并创建待处理订单；交付内容需等人工发货完成后再通过查单获取。建议按
order_sn 轮询 GET /orders/{order_sn}（例如每 10～30 秒），直到 status=completed。
人工订单创建成功示例：
{
"code": 0,
"message": "success",
"data": {
"order_sn": "XXXX",
"client_order_id": "your-unique-id-001",
"product_id": 589,
"quantity": 1,
"unit_price": "10.00",
"total_price": "10.00",
"type": "manual",
"status": "processing",
"created_at": "2026-07-22 01:40:00"
}
}
3.5 查询订单
GET https://www.yuguofb.com/api/v1/reseller/orders/{order_sn}
返回字段包含 order_sn, client_order_id, product_id, quantity, unit_price, total_price, type, status, created_at；当 status=completed 且已发货时，额外返回 delivery（字符串数组）。
| status | 含义 |
|---|---|
| pending | 待支付（一般 API 下单不会出现） |
| processing | 处理中（人工发货待后台完成） |
| completed | 已完成（可读取 delivery） |
| failed | 失败 / 异常 |
| refunded | 已退款 |
| expired | 已过期 |
4. 调用示例（cURL）
curl -X GET "https://www.yuguofb.com/api/v1/reseller/products" \
-H "X-Api-Key: your_api_key"
curl -X POST "https://www.yuguofb.com/api/v1/reseller/orders" \
-H "Content-Type: application/json" \
-H "X-Api-Key: your_api_key" \
-d '{"product_id":1024,"quantity":1,"client_order_id":"demo-001"}'
5. 定价规则
价格按密钥关联用户在后台的配置自动计算：商品售价、用户折扣(减%)、批发优惠均与前台下单一致，客户端传价无效。请确保关联账户余额充足。
6. 人工发货对接流程（推荐）
- 调用商品列表/详情，确认
type=manual。 POST /orders下单，拿到order_sn；此时status一般为processing。- 下游系统保存本平台
order_sn，并向用户展示「处理中」。 - 轮询
GET /orders/{order_sn}；当status变为completed后读取delivery交付给终端用户。
注意
请勿将人工订单的首次下单响应当作已发货；只有
completed 且存在 delivery 时才应向下游用户交付内容。