鱼果跨境 · API 对接文档

通过 REST API 对接本平台商品，支持商品查询、余额查询、自动下单与查单。

自动发货余额扣款下架即停供幂等下单

1. 接入说明

联系平台管理员申请 API Key（后台为用户充值余额并创建密钥）。
所有请求使用 HTTPS，Base URL：https://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://yuguofb.com/api/v1/reseller/products

仅返回已上架且支持自动发货的商品。字段：id, name, price, stock, min_qty, max_qty, type, category

3.2 商品详情

GET https://yuguofb.com/api/v1/reseller/products/{id}

3.3 余额查询

GET https://yuguofb.com/api/v1/reseller/balance

3.4 创建订单

POST https://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 建议传入下游唯一订单号，重复提交将返回同一结果（幂等）。成功后 data.delivery 返回卡密数组。

3.5 查询订单

GET https://yuguofb.com/api/v1/reseller/orders/{order_sn}

4. 调用示例（cURL）

curl -X GET "https://yuguofb.com/api/v1/reseller/products" \
  -H "X-Api-Key: your_api_key"

curl -X POST "https://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. 定价规则

价格按密钥关联用户在后台的配置自动计算：商品售价、用户折扣(减%)、批发优惠均与前台下单一致，客户端传价无效。请确保关联账户余额充足。