网站商城接入
目录
修改历史记录
| 版本 |
日期 |
备注 |
修改人 |
| 1.0.0 |
2019/04/04 |
1. 店铺接口描述
2. 商品接口描述
3. 签名及状态码 |
刘强 |
后台相关设置
EndPoint & AppKey
在创建好机器人后，需要在后台配置EndPoint以及相应AppKey，EndPoint需要实现相应的接口需求以提供给晓多调用。为了保证晓多智能客服机器人的基本使用，现阶段至少需要实现店铺和商品相关接口。
焦点商品识别方式
为了让晓多智能客服机器人拥有识别焦点商品的能力，可以配置若干个正则表达式来从聊天语句中捕捉商品ID。正则表达式必须至少有一个捕获组，并且它匹配到的刚好是对应的商品ID。举例如下:
假设用户的商品链接是: https://item.example.com/item.htm?id=586926839203&spm=2015.23446002.0.0
我们知道其中的商品ID是 586926839203 这一段，为了捕捉到它，那么我们可以配置对应的正则表达式为:
item.example.com/item.htm\?id=([0-9]+)
其中 ([0-9]+) 就是一个商品ID的捕获组，它可以匹配到数字类型的商品ID(需要注意 ? 是关键字符，需要加 \ 转义)
接口需求汇总
为了更好地使用智能客服机器人，渠道需要提供给晓多调用的API，现阶段的需求如下:
| 接口 |
方式 |
路径 |
签名 |
请求格式 |
响应格式 |
| 获取店铺基本信息 |
GET |
/shop/info |
是 |
|
application/json |
| 获取商品基本信息 |
GET |
/item/info |
是 |
|
application/json |
| 获取商品信息列表 |
GET |
/item/list |
是 |
|
application/json |
| 搜索商品信息列表 |
GET |
/item/search |
是 |
|
application/json |
获取店铺基本信息
请求参数
响应参数
| 名称 |
类型 |
可选 |
描述 |
code |
Integer |
|
响应码 (示例: 0) |
message |
String |
|
响应消息 (示例: "OK") |
shop |
Shop |
是 |
店铺信息 |
店铺信息
| 名称 |
类型 |
可选 |
描述 |
shop_name |
String |
|
店铺名 (示例: "晓多智能客服机器人") |
shop_logo |
String |
是 |
店铺图标 (示例: "https://www.xiaoduoai.com/logo.png") |
shop_link |
String |
是 |
店铺链接 (示例: "https://www.xiaoduoai.com/shop") |
shop_desc |
String |
是 |
店铺描述 (示例: "专业的智能客服机器人，成就您的业务") |
获取商品基本信息
请求参数
| 名称 |
类型 |
可选 |
描述 |
item_id |
String |
|
商品ID (示例: "18273773737") |
响应参数
| 名称 |
类型 |
可选 |
描述 |
code |
Integer |
|
响应码 (示例: 0) |
message |
String |
|
响应消息 (示例: "OK") |
item |
Item |
是 |
商品信息 |
商品信息
| 名称 |
类型 |
可选 |
描述 |
item_id |
String |
|
商品ID (示例: "18273773737") |
item_name |
String |
|
商品名 (示例: "耐克运动鞋") |
item_logo |
String |
|
商品图标 (示例: "https://www.xiaoduoai.com/logo-18273773737.png") |
item_link |
String |
|
商品链接 (示例: "https://www.xiaoduoai.com/item?id=18273773737") |
props |
Prop[] |
|
属性列表 |
skus |
Sku[] |
|
SKU列表 |
create_time |
String |
|
创建时间 (示例: "2019-03-28 15:12:09") |
modify_time |
String |
|
修改时间 (示例: "2019-03-28 15:12:09") |
属性信息
| 名称 |
类型 |
可选 |
描述 |
name |
String |
|
属性名 (示例: "颜色") |
value |
String[] |
|
属性值 (示例: ["红", "白", "透明"]) |
SKU信息
| 名称 |
类型 |
可选 |
描述 |
sku_id |
String |
|
SKU ID (示例: "326783287") |
sku_name |
String |
是 |
SKU 名 (示例: "连衣裙粉色") |
sku_logo |
String |
是 |
SKU 图标 (示例: "https://www.xiaoduoai.com/logo-326783287.png") |
sku_link |
String |
是 |
SKU 链接 (示例: "https://www.xiaoduoai.com/sku?id=326783287") |
props |
Prop[] |
|
属性列表 |
price |
String |
|
价格 (示例: "998元") |
quantity |
Integer |
|
价格 (示例: 5) |
create_time |
String |
|
创建时间 (示例: "2019-03-28 15:12:09") |
modify_time |
String |
|
修改时间 (示例: "2019-03-28 15:12:09") |
获取商品信息列表
请求参数
| 名称 |
类型 |
可选 |
描述 |
item_ids |
String[] |
|
商品ID列表 (示例: ["18273773737", "18273773738"]) |
响应参数
| 名称 |
类型 |
可选 |
描述 |
code |
Integer |
|
响应码 (示例: 0) |
message |
String |
|
响应消息 (示例: "OK") |
items |
Item[] |
是 |
商品信息列表 |
搜索商品信息列表
请求参数
| 名称 |
类型 |
可选 |
描述 |
q |
String |
|
关键词 (示例: "男鞋") |
page_no |
Integer |
|
目标页码 (示例: 3) |
page_size |
Integer |
|
每页条数 (示例: 40) |
order_by |
String |
|
排序方式 (示例: "item_id:desc") |
响应参数
| 名称 |
类型 |
可选 |
描述 |
code |
Integer |
|
响应码 (示例: 0) |
message |
String |
|
响应消息 (示例: "OK") |
items |
Item[] |
是 |
商品信息列表 |
total |
Integer |
|
总数量 (示例: 2) |
其它补充说明
验签方法
- 将请求参数规范化成键值对形式，其中值为数字类型的，直接转成字符串类型。如果值为数组类型，则拆分成多个键值对: 譬如
"item_ids": ["18273773737", "18273773738"]，我们需要拆成"item_ids": "18273773737" 和 "item_ids": "18273773738" 两对
- 将编码后的键值对进行字典序升序排列，优先依照键排列，如果键一样则依照值排列
- 将请求路径和排列后的键值对(除sign以外)按序拼接，拼接方式为
key1val1key2val2key3val3，我们记为URI
- 将
URI和密钥进行拼接后进行md5哈希(小写)作为签名值，附加到最终的请求参数中发送
举个例子，搜索商品信息列表原始的请求是 {"q": "男鞋", "page_no": 3, "page_size": 40, "order_by": "item_id:desc"}
- 我们将其拆分成多个标准键值对
{"q": "男鞋", "page_no": "3", "page_size": "40", "order_by": "item_id:desc"}
- 重排列
{"order_by": "item_id:desc", "page_no": "3", "page_size": "40", "q": "男鞋"}
- 拼接
URI order_byitem_id:descpage_no3page_size40q男鞋
- 计算签名
md5(order_byitem_id:descpage_no3page_size40q男鞋dead01234567beaf)
这里 dead01234567beaf 是后台配置好的AppKey，最终签名结果是 a76863c3220c691c7d2e303f28d2bf89
响应码说明
响应参数里统一包含 code 代表响应码，message 代表响应消息。这里唯一的硬性约束是 code 为 0 时表示正确响应。
建议错误响应时的 code 返回负数，message 能准确描述具体的错误类型，方便双方对接同学在出问题时进行迅速排查。