云聚权益API接口文档 v1

1 平台介绍

平台简介

本开放平台对系统客户提供各类API服务,例如下单购买、订单处理、商品数据等。本文档说明了开放平台的技术规范、传输协议等信息,供接入平台的商家使用,作为程序设计开发的指导。

协议架构

  • 传输采用HTTP协议。
  • 买家使用POST方法将请求发送到接口地址,经服务端处理后,将请求结果返回。
  • 传输数据采用UTF-8编码。

注意事项

  • 接口中签名时用到的 APPIDAPIKEY 参数请联系平台管理员获取
  • PC端API密钥获取方式:用户中心 -> 账户管理 -> 获取/重置秘钥
  • 移动端API密钥获取方式:我的 -> 接口管理 -> 获取/重置秘钥
  • 接口管理位置示意图

重要提示:返回不一定是 JSON,请勿直接判定失败!

当返回 不是 JSON(如 HTML 文本、502 网关页、CDN/WAF 拦截提示、空响应等)时,不得直接当做失败处理。

应进入 “未知状态”,立即/稍后调用【订单查询接口】或人工核实结果,并记录原始响应内容以便排障。

2 开发指南

2.1 接口约定

  • 传输采用HTTP协议。
  • 传输数据采用UTF-8编码。
  • 请求方式为POST。

每次请求需传入以下Header参数:

Header 参数 类型 是否必填 描述
Sign string 签名(计算规则见下方说明)
Timestamp string 13位时间戳(毫秒)
UserId string 您的用户接口APPID(后台接口为管理员登录账号)

2.2 签名计算方式

为了防止请求被伪造、篡改,每一次接口请求都需传入根据本次请求的13位时间戳(毫秒)+body参数(json格式)+apikey(密钥)计算获得的sign(签名)

sign生成规则: sha1(time+data+apikey)

重要注意事项

  • 请求参数参数名ASCII码从小到大排序
  • 请求Body参数为空时传{},并且data使用{}参与签名
  • 请求参数和签名内容需要UTF-8编码
  • 回调地址请原样进行签名
  • 参数名区分大小写

接口示例(以订单查询接口为例)

UserId: 2uIkTrXNdAFc7OKhbRenzjDtgPoZ6s5C

apikey: H0YnuPpcVtx7rQdMTbjN6932s5oDOqFa

Header 参数

Sign: 待计算

Timestamp: 1696645385740

UserId: 2uIkTrXNdAFc7OKhbRenzjDtgPoZ6s5C

Body 参数

{
    "day": 10,
    "external_orderno": "",
    "ordersn": "D100759082558859640832"
}
第一步: 将请求Body参数中多个键值对,参数按照参数名的字典升序排列(a-z)。
{"day":10,"external_orderno":"","ordersn":"D100759082558859640832"}
第二步: 将 13位时间戳+第一步中排序后的字符串+apikey 拼接得到待签名字符串
1696645385740{"day":10,"external_orderno":"","ordersn":"D100759082558859640832"}H0YnuPpcVtx7rQdMTbjN6932s5oDOqFa
第三步: 使用sha1算法加密待加密字符串即为sign
15b8f541eb10e3fbb33efd92c8d52d50ddca0784
第四步: 将sign添加到Header参数中

Sign: 15b8f541eb10e3fbb33efd92c8d52d50ddca0784

Timestamp: 1696645385740

UserId: 2uIkTrXNdAFc7OKhbRenzjDtgPoZ6s5C

PHP代码示例

public function sign($post = [], $key ='',$userid = '')
{
    if ($post) {
        ksort($post); //排序post参数
        $post = json_encode($post , JSON_UNESCAPED_SLASHES|JSON_UNESCAPED_UNICODE);
    } else {
        $post = "{}";
    }
    $time = time() . rand(100, 999);
    $header[] = "Content-Type: application/json; charset=utf-8";
    //用户密钥
    $header[] = "Sign: " . sha1($time . $post . $key);
    $header[] = "Timestamp: " . $time;
    //用户ID
    $header[] = "UserId: " . $userid;
    return [$post, $header];
}

2.3 全局状态码

状态码 (code) 描述 (msg)
200 成功
400 失败(msg返回错误信息)
500 未知错误

3 用户接口

3.1 用户余额

POST

获取当前用户的账户余额。

/api/v1/user/info

body参数

参数名 类型 是否必填 说明
- - -

响应示例

{
    "code": 200,
    "msg": "成功",
    "data": {
        "balance": "8888.88"
    }
}

返回参数说明

参数名 类型 说明
code int 状态码
msg string 状态描述
data object 返回数据
data.balance string 用户余额

4 商品接口

4.1 商品分类

POST

获取所有商品分类。

/api/v1/goods/cate

body参数

参数名 类型 是否必填 说明
- - -

响应示例

{
    "code": 200,
    "msg": "成功",
    "data": [
        {
            "id": 365,
            "name": "测试商品分类一",
            "pid": 0,
            "img": "http://imgs.demo.com/attach/2023/06/4d247202306110247593869.png",
            "children": [
                {
                    "id": 366,
                    "name": "测试",
                    "pid": 365,
                    "img": "http://imgs.demo.com/attach/2023/06/4d247202306110247593869.png",
                    "children": [
                        {
                            "id": 7327,
                            "name": "三级",
                            "pid": 365,
                            "img": "http://imgs.demo.com/attach/2023/06/4d247202306110247593869.png"
                        }
                    ]
                }
            ]
        },
        {
            "id": 367,
            "name": "测试商品分类二",
            "pid": 0,
            "img": "http://imgs.demo.com/attach/2023/06/4d247202306110247593869.png",
            "children": [
                {
                    "id": 368,
                    "name": "测试",
                    "pid": 367,
                    "img": "http://imgs.demo.com/attach/2023/06/4d247202306110247593869.png"
                }
            ]
        }
    ]
}
}

返回参数说明

参数名 类型 说明
code int 状态码
msg string 状态描述
data array 返回数据
data[].id int 一级分类ID
data[].name string 一级分类名称
data[].pid int 一级分类上级ID
data[].img string 一级分类图片
data[].children array 二级分类列表
data[].children[].id int 二级分类ID
data[].children[].name string 二级分类名称
data[].children[].pid int 二级分类上级ID
data[].children[].img string 二级分类图片
data[].children[].children array 三级分类列表
data[].children[].children[].id int 三级分类ID
data[].children[].children[].name string 三级分类名称
data[].children[].children[].pid int 三级分类上级ID
data[].children[].children[].img string 三级分类图片

4.2 商品列表

POST

获取商品列表。

/api/v1/goods/list

body参数

参数名 类型 是否必填 说明
cate_id int 二级分类ID
keyword string 搜索关键词
page int 页码,默认1
limit int 每页数量,默认100

响应示例


                    {
    "code": 200,
    "msg": "成功",
    "data": {
        "list": [
            {
                "id": 1,
                "goods_name": "测试商品1",
                "goods_img": "http://img.demo.com/Uploads%2FAttachment%2F2022-10-25%2F63578b642b6c1.jpg",
                "goods_type": 2,
                "face_value": "2.00",
                "goods_price": "2.00",
                "status": 1,
                "stock_num": 9999
            },
            {
                "id": 2,
                "goods_name": "测试商品2",
                "goods_img": "http://img.demo.com/Uploads%2FAttachment%2F2021-11-30%2F61a604627471e.jpeg",
                "goods_type": 2,
                "face_value": "1.10",
                "goods_price": "1.10",
                "status": 2,
                "stock_num": 1110
            }
        ],
        "total": 2
    }
}

返回参数说明

参数名 类型 说明
code int 状态码
msg string 状态描述
data object 返回数据
data.list array 商品列表
data.list[].id int 商品ID
data.list[].goods_name string 商品名称
data.list[].goods_img string 商品图片
data.list[].goods_type int 商品类型:1=卡密商品,2=虚拟商品
data.list[].face_value string 商品面值
data.list[].goods_price string 商品价格
data.list[].status int 商品状态:1=销售,2=暂停,3=禁售
data.list[].stock_num int 库存数量
data.total int 商品总数

4.3 商品详情

POST

获取单个商品的详细信息。

/api/v1/goods/info

body参数

参数名 类型 是否必填 说明
id int 商品ID

响应示例


                 {
    "code": 200,
    "msg": "成功",
    "data": {
        "id": 1,
        "goods_name": "测试商品1",
        "goods_img": "http://img.demo.com/Uploads%2FAttachment%2F2022-10-25%2F63578b642b6c1.jpg",
        "goods_type": 2,
        "face_value": "2.00",
        "goods_price": "2.00",
        "status": 1,
        "stock_num": 9999,
        "goods_info": "测试商品详情内容",
        "goods_notice": "",
        "start_count": 1,
        "end_count": 10,
        "attach": [
            {
                "key": "recharge_account",
                "type": "text",
                "tip": "测试1",
                "name": "测试1"
            },
            {
                "key": "lblName1",
                "type": "text",
                "tip": "测试2",
                "name": "测试2"
            }
        ]
    }
}
                    

返回参数说明

参数名 类型 说明
code int 状态码
msg string 状态描述
data object 返回数据
data.id int 商品ID
data.goods_name string 商品名称
data.goods_img string 商品图片URL
data.goods_type int 商品类型:1=卡密商品,2=虚拟商品
data.face_value string 商品面值
data.goods_price string 商品价格
data.status int 商品状态:1=销售,2=暂停,3=禁售
data.stock_num int 商品库存数量
data.goods_info string 商品详情
data.goods_notice string 注意事项
data.start_count int 最小购买数量
data.end_count int 最大购买数量
data.attach array 虚拟商品下单模板(卡密商品此数组为空)
data.attach[].key string 下单参数模板变量名
data.attach[].type string 类型:text=文本,password=密码框,checkbox=多选框,select=下拉,radio=单选框,cascader=级联组合
data.attach[].tip string 下单参数提示信息
data.attach[].name string 下单参数名称
data.attach[].options string 多选框、单选框、下拉框、 级联组合类型才存在此参数,其他类型无此参数

4.4 商品变动推送

CALLBACK

将商品的价格变动、销售状态、库存状态、供货状态等信息,通过POST的方式实时同步到客户服务器。
推送接口地址需要用户在接口管理中配置好商品通知地址。

  • 本接口为POST,验证回调sign不参与签名
  • 接收到推送后,请返回字符串ok,否则视为不成功,将会按照时间阶梯延迟5|10|15|20|25分钟继续进行通知回调,最多回调5次。

签名算法(PHP)

/**
 * 验证回调
 * @param $post 请求参数
 * @return bool
 */
public function verify($post)
{
    $sign = $post['sign'] ?? '';
    unset($post['sign']);
    $data = [
        'id' => $post['id'],
        'time' => $post['time'],
    ];
    ksort($data); //排序post参数
    try {
        $newsign = sha1($post['time'] . json_encode($data, 256) . 密钥);//签名
    } catch (\Throwable $e) {

    }
    return !empty($newsign) && $newsign == $sign;
}

请求body参数说明

参数名 类型 说明
id string 商品ID
goods_sku_id string 商品规格ID(存在则为多规格)
status string 商品状态(存在则更新),状态:1=销售/上架,2=暂停,3=禁售/下架
goods_price string 商品价格(存在则更新)
stock_num string 商品库存(存在则更新)
sign string 签名(参考上方签名算法)
time string 13位时间戳(毫秒)

返回响应

ok

4.5 商品下单模板

POST

商品下单模板参数获取

/api/v1/goods/attach

请求参数

参数名 类型 是否必填 说明
goods_id string 商品ID或规格编码

响应示例


               {
    "code": 200,
    "msg": "成功",
    "data": [
        {
            "type": "text",
            "name": "充值账号",
            "key": "recharge_account",
            "vali": "all",
            "tip": "请填写正确的充值账号",
            "options": "{\"type\":\"text\",\"maxlength\":20000,\"clearable\":false,\"disabled\":false,\"showPassword\":false,\"preg\":\"\",\"init_value\":0}"
        }
    ]
}  
                    

5 订单接口

5.1 提交订单

POST

创建新订单。

/api/v1/order/buy

POST请求,Content-Type必须设置为:application/json;

接口是异步,接口调用成功(即下单成功),不代表充值成功

最终“充值结果”,需要调用“订单详情接口”进行查询,由于取卡是异步操作,建议间隔1-3s循环调用,直至最终结果;

此接口不会返回卡密数据,需要再调用“订单详情接口”获取卡密信息;

“订单详情接口”必须接入;

下单接口如果请求超时,请调用订单详情接口确认下单结果;

body参数

参数名 类型 是否必填 说明
id int 商品ID
url string 订单回调地址(没有就不传)
external_orderno string 三方订单号(防重复)可传空,建议传值,若传需传唯一值
safe_price string 安全价格(防止调价导致亏本,传入此参数用于对比)
mark string 下单备注
quantity int 购买数量
attach object 下单参数(卡密商品不用传此参数),手工订单下单模板(以下属性为商品模板中key)

attach参数说明

参数名 类型 说明
recharge_account string 充值账号
lblName1 string 下单参数一
lblName2 string 下单参数二
... string 下单参数N

响应示例


{
    "code": 200,
    "msg": "下单成功",
    "data": {
        "ordersn": "API091952652791532879872",
        "external_orderno": "D091952644768932429824"
    }
}                 

返回参数说明

参数名 类型 说明
code int 状态码
msg string 状态描述
data object 返回数据
data.ordersn string 订单号
data.external_orderno string 三方订单号

5.2 订单查询

POST

订单详情查询接口(订单同步建议使用订单异步回调处理)

/api/v1/order/info

body参数

参数名 类型 是否必填 说明
external_orderno string 外部订单号(二选一) 多个订单用逗号隔开
ordersn string 本系统订单号(二选一) 多个订单用逗号隔开
day string 查多少天内订单,默认近30天订单,查全部请传0

直充响应示例

{
    "code": 200,
    "msg": "成功",
    "data": [
        {
            "ordersn": "D100759324935205552128",
            "external_orderno": "",
            "recharge_info": [
                {
                    "n": "测试1",
                    "v": "1",
                    "k": "recharge_account"
                },
                {
                    "n": "测试2",
                    "v": "1",
                    "k": "lblName1"
                }
            ],
            "recharge_hints": "订单已取消,资金已退回商城余额!",
            "status": 5,
            "card_list": []
        }
    ]
}

卡券响应示例

{
    "code": 200,
    "msg": "成功",
    "data": [
        {
            "ordersn": "D100759274105949519872",
            "external_orderno": "",
            "recharge_info": [],
            "recharge_hints": "订单已取消,资金已退回商城余额!",
            "status": 5,
            "card_list": [
                {
                    "card_no": "",
                    "card_password": "1",
                    "card_show_type": 1
                }
            ]
        }
    ]
}

返回参数说明

参数名 类型 说明
code int 状态码
msg string 状态描述
data array 返回数据
data[].ordersn string 本地订单号
data[].external_orderno string 外部订单号
data[].recharge_info array 下单参数
data[].recharge_hints string 订单返回信息
data[].status int 订单状态(1=等待处理,2=正在处理,3=交易成功,4=取消交易,5=已退款,-1=未支付)
data[].card_list array 卡密列表(卡密订单才返回此项)

recharge_info参数说明

参数名 类型 说明
n string 下单参数名称
v string 下单参数内容
k string 下单参数变量名

card_list参数说明

参数名 类型 说明
card_no string 卡号
card_password string 卡密
card_show_type int 卡密类型:1=普通卡号和卡密,2=图片二维码,3=条形码

5.3 订单异步回调

CALLBACK

订单异步回调接口,订单状态发生变化时,通过POST的方式实时同步到客户服务器。
推送接口地址需要用户在接口管理中配置好商品通知地址。

  • 本接口为POST,验证回调sign不参与签名
  • 接收到推送后,请返回字符串ok,否则视为不成功,将会按照时间阶梯延迟5|10|15|20|25分钟继续进行通知回调,最多回调5次。

签名算法(PHP)

/**
 * 验证回调
 * @param $post 请求参数
 * @return bool
 */
public function verify($post)
{
    $sign = $post['sign'] ?? '';
    unset($post['sign']);
    //卡密和物流信息 回调不签名
    if (isset($post['card_list'])) {
        unset($post['card_list']);
    }
    if (isset($post['express_list'])) {
        unset($post['express_list']);
    }
    ksort($post); //排序post参数
    $newsign = sha1($post['time'] . json_encode($post, 256) . 密钥);//签名
    return $newsign == $sign;
}

请求body参数

参数名 类型 说明
external_orderno string 外部订单号
ordersn string 本地订单号
status string 订单状态:2=正在处理,3=已完成,4=取消交易,5=已退款
has_back_money string 退款金额
total_price string 下单金额
recharge_hints string 订单处理返回信息
time string 13位时间戳(毫秒)
sign string 签名(参考上方签名算法示例)
card_list string 卡密列表(json格式)
express_list string 物流信息列表(json格式)

返回响应

ok

5.4 订单撤单

POST

申请撤单接口(订单撤单不代表订单退款,撤单成功后请等待订单回调)

/api/v1/order/close

body参数

参数名 类型 是否必填 说明
ordersn string 本系统订单号
card_list array 卡密列表

返回参数说明

参数名 类型 说明
code int 状态码
msg string 状态描述

6 电商对接

电商对接相关接口说明。

6.1 阿奇索标准系统

1、登录91卡券仓库,添加自有货源信息。

2、进入闲鱼鱼店长管理后台,点击宝贝发布,设置商品 标识为直充。

3、进入宝贝设置,配置自动发货规则即可

6.2 闲管家自研系统

1、打开闲管家,进入:应用—我的应用—添加应用,选择《我有自研系统》,进行添加

2、点击应用详情,填写货源授权信息即可

3、添加直充商品

4、选择闲鱼号并开启服务,及设置商品信息

5、设置货源及商品,及开启自动调价

6、发布商品,同个闲鱼店铺的商品请勿重复在多个平台配置直充,避免重复充值,造成资金损失