好价源 API 对接文档

接入概览

对接方把 好价源 当作货源站：先同步商品，用户在本地付款后再向货源站代采下单，最后通过订单查询或回调拿到发货内容。

1. 对接方在 好价源 用户中心获取 API Key，货源站可开启 IP 白名单。
2. 调用 user_info 校验账号、余额和会员等级，余额不足时先充值。
3. 调用 goods_category、goods_list、goods_detail 同步允许对接的商品与规格。
4. 本地买家付款后，调用 order_buy 向货源站代采下单，out_trade_no 必须唯一。
5. 自动发货商品会在下单响应里返回 content；人工发货或实物商品继续调用 order_query 或等待 notify_url 回调。

鉴权规则

所有接口都需要 api_key。如果货源站用户开启了 IP 白名单，请求 IP 必须在白名单内。

鉴权模式

模式	说明
普通模式	GET 或 POST 传入 api_key 即可。官方同系统对接插件默认按此方式调用。
签名模式	额外传入 timestamp 和 sign 时，服务端会校验 5 分钟时间窗口和签名。

签名算法

$params = [
    'action' => 'goods_list',
    'api_key' => 'YOUR_API_KEY',
    'timestamp' => time(),
];
ksort($params);
$signStr = '';
foreach ($params as $key => $value) {
    if ($value !== '' && $value !== null) {
        $signStr .= $key . '=' . trim($value) . '&';
    }
}
$signStr .= 'key=YOUR_API_KEY';
$params['sign'] = md5($signStr);

请求格式：接口读取 GET/POST 表单参数；下单接口建议使用 application/x-www-form-urlencoded 或普通表单提交，不按 JSON Body 解析。

获取账户信息

用于测试 API Key 是否有效，并读取当前对接账号余额与会员等级。官方同系统对接插件在"测试货源站"时会先调用此接口。

请求参数

参数	类型	必填	位置	说明
action	string	是	GET	固定值 user_info
api_key	string	是	GET/POST	对接账号 API Key
timestamp	int	否	GET/POST	携带 sign 时必填，Unix 秒级时间戳
sign	string	否	GET/POST	签名值；不传 sign 时走普通 api_key 鉴权

返回字段

字段	类型	说明
uid	int	对接账号用户 ID
money	float	账户余额，单位元
level_name	string	当前会员等级名称

请求示例

GET /user/api.php?action=user_info&api_key=YOUR_API_KEY

返回示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "uid": 10001,
    "money": 238.5,
    "level_name": "普通会员"
  }
}

获取商品分类

返回货源站总店商品分类。对接方可用分类 ID 建立本地分类映射。

请求参数

参数	类型	必填	位置	说明
action	string	是	GET	固定值 goods_category
api_key	string	是	GET/POST	对接账号 API Key

返回字段

字段	类型	说明
id	int	分类 ID，用于 goods_list 的 cid 参数
title	string	分类名称
taxis	int	分类排序值
description	string	分类描述

请求示例

GET /user/api.php?action=goods_category&api_key=YOUR_API_KEY

返回示例

{
  "code": 0,
  "msg": "ok",
  "data": [
    {"id": 1, "title": "虚拟商品", "taxis": 10, "description": "自动发货商品"}
  ]
}

获取商品列表

分页返回允许对接的商品。接口只返回总店、已上架、allow_dock=1 的商品，并排除本身已经属于对接来源的商品。

请求参数

参数	类型	必填	位置	说明
action	string	是	GET	固定值 goods_list
api_key	string	是	GET/POST	对接账号 API Key
cid	int	否	GET	分类 ID，不传则返回全部允许对接商品
page	int	否	GET	页码，默认 1
limit	int	否	GET	每页数量，默认 20，最大 100；按页拉取到空数组即可停止

返回字段

字段	类型	说明
id	int	商品 ID，后续 goods_detail/order_buy 使用
sort_id	int	所属分类 ID
type	string	商品类型标识
title	string	商品标题
cover	string	商品封面路径，可能是相对路径
stock	int	库存数量
is_sku	string	y=多规格，n=无规格
guest_price	float	当前 API 账号采购价，单位元

请求示例

GET /user/api.php?action=goods_list&api_key=YOUR_API_KEY&page=1&limit=20

获取商品详情

返回单个商品完整信息、SKU、规格值、库存、采购价和下单输入字段。官方同系统对接插件导入商品和计划任务同步库存时都会调用此接口。

请求参数

参数	类型	必填	位置	说明
action	string	是	GET	固定值 goods_detail
api_key	string	是	GET/POST	对接账号 API Key
id	int	是	GET	商品 ID

返回字段

字段	类型	说明
skus[].sku	string	规格标识；无规格为 0，多规格为规格值 ID 组合
skus[].guest_price	float	当前 API 账号采购价，单位元
spec	array	多规格属性和值，用于把本地选择映射回货源站 sku
attach_user	json/string	商品级下单输入项
order_required	array	全局下单输入项；实物商品为空数组

请求示例

GET /user/api.php?action=goods_detail&id=12&api_key=YOUR_API_KEY

返回示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": 12,
    "title": "示例商品",
    "is_sku": "y",
    "stock": 50,
    "skus": [
      {"sku": "101-205", "stock": 8, "guest_price": 9.9}
    ],
    "spec": [
      {"title": "套餐", "sku_values": [{"id": 101, "name": "月卡"}]}
    ],
    "order_required": []
  }
}

代采下单

对接方本地订单支付成功后调用。注意：action 必须放在 URL 查询参数中，业务参数用 POST 提交；官方同系统对接插件也是这样调用的。

请求参数

参数	类型	必填	位置	说明
action	string	是	GET	固定值 order_buy，放在 URL 中
api_key	string	是	POST	对接账号 API Key
goods_id	int	是	POST	货源站商品 ID
quantity	int	是	POST	购买数量，最小 1
sku	string	否	POST	规格标识；无规格传 0 或不传
out_trade_no	string	是	POST	对接方商户单号，必须唯一；接口按此字段做幂等
notify_url	string	否	GET/POST	异步回调地址
input_value	string	否	POST	必填项取值，必须传 JSON 字符串，字段名以 goods_detail 返回的 attach_user/order_required 为准，例如 input_value={"联系信息":"13800138000"}；实物商品需包含收货人、手机号、地区、详细地址等字段

返回字段

字段	类型	说明
order_id	string	货源站订单号，后续 order_query 使用
content	string	交付内容；自动发货可能立即返回，人工发货可能为空
status	int	订单状态：1=待发货，2=已完成

请求示例

POST /user/api.php?action=order_buy
api_key=YOUR_API_KEY&goods_id=12&quantity=1&sku=0&out_trade_no=LOCAL202607070001&input_value={"联系信息":"13800138000"}

返回示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "order_id": "20260707120000123456",
    "content": "账号：demo\n密码：123456",
    "status": 2
  }
}

订单查询

查询代采订单状态和交付内容。人工发货、实物发货或网络超时后，建议用此接口按订单号查询。

请求参数

参数	类型	必填	位置	说明
action	string	是	GET	固定值 order_query
api_key	string	是	GET/POST	对接账号 API Key
order_id	string	二选一	GET	order_buy 返回的货源站订单号
out_trade_no	string	二选一	GET	对接方下单时传入的商户单号

返回字段

字段	类型	说明
order_id	string	货源站订单号
out_trade_no	string	对接方商户单号
amount	float	订单金额，单位元
status	int	1=待发货，2=已完成，3=已退款/关闭
content	string	交付内容，仅 status>=2 时可视为有效

请求示例

GET /user/api.php?action=order_query&api_key=YOUR_API_KEY&order_id=20260707120000123456

返回示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "order_id": "20260707120000123456",
    "out_trade_no": "LOCAL202607070001",
    "amount": 9.9,
    "status": 2,
    "pay_time": 1783425600,
    "content": "账号：demo\n密码：123456"
  }
}

回调通知

调用 order_buy 时传入 notify_url 后，发货完成或售后退款时，货源站会向该地址发送 POST 表单通知。

回调字段

字段	说明
order_id	货源站订单号
out_trade_no	对接方商户单号
status	2=已完成，3=已退款/关闭
content	交付内容，退款时可能为空
timestamp	回调时间戳
sign	按同一签名算法生成，用于确认回调可信

接收示例

$params = $_POST;
$sign = $params['sign'] ?? '';
unset($params['sign']);
ksort($params);
$signStr = '';
foreach ($params as $key => $value) {
    if ($value !== '' && $value !== null) {
        $signStr .= $key . '=' . trim($value) . '&';
    }
}
$signStr .= 'key=YOUR_API_KEY';
if (md5($signStr) !== $sign) {
    http_response_code(400);
    exit('sign_error');
}
// 根据 out_trade_no 更新本地订单状态
echo 'ok';

状态与错误

接口统一返回 {"code":0,"msg":"ok","data":...}。业务失败时 code 非 0，开发者应优先读取 msg 判断原因。

错误信息	常见原因	建议处理
缺少API对接密钥 (api_key)	未传 api_key 或参数名错误	检查 GET/POST 参数
API密钥无效	api_key 不存在或已重新生成	重新复制用户中心 API Key
请求IP未在白名单中	货源站开启了 IP 白名单	把对接服务器出口 IP 加入白名单
签名校验失败	sign 拼接参数不一致或使用了错误密钥	按 ASCII 升序排序并排除 sign 参数
商品不存在、已下架或不支持对接	商品未上架、未开启允许对接或 ID 错误	重新同步 goods_list/goods_detail
商品规格不存在	sku 与货源站规格值组合不匹配	用 goods_detail 返回的 skus[].sku 下单
商品库存不足	当前库存少于 quantity	减少数量或等待货源补库存
货源账户余额不足	对接账号余额不足以支付采购订单	先充值或拦截本地下单