电商机器人第三方接入标准API

版本历史记录

版本	日期	备注
v1.0.0	2018/11/17	接口格式定义、消息相关接口、订单相关接口、商品相关接口
v1.0.1	2018/12/11	1.订单详情接口删除0未知状态 2.问答消息接收，content_type、content字段收归到Message结构体内 3.商品相关接口 palt_cid 、sku_cid字段类型修改为String 4.订单详情接口、物流详情接口，添加对于一订单号多物流单号情况的备注 5.问答消息发送，去掉create_time字段
v1.0.2	2021/06/04	问答接口添加question_id和readable_question返回场景id和场景label

1.API开发指南

前期准备

环境	域名
测试环境	https://xxx.test.com
生产环境	https://xxx.com

API调用参数说明

API接口实现统一使用POST请求方式，Content-Type为applicatioin/json格式。

字段	字段类型	是否必须	描述
Authorization	String	是	API入参的签名计算结果，用于鉴权
Version	String	是	请求的API版本号。目前固定为1。

请求Body

见各业务接口入参定义

请求返回

字段	字段类型	是否必须	描述
code	Number	是	返回码，见下方定义
msg	String	是	返回描述
data	Map	是	返回数据内容

返回码定义

返回码	描述
400000	成功
401000	参数错误
401001	系统错误
402000	验签失败
402001	消息不能为空
402002	消息发送异常，请重试
402003	消息发送失败

签名算法

鉴权字段 authorization 的生成规则

sign = lowercase(md5(app_id.timestamp.secret.nonce.secret)) 
authorization = app_id.timestamp.nonce.sign

字段	描述
app_id	由晓多提供，唯一标识电商机器人。
timestamp	当前unix时间戳,如1557894000
nonce	随机串，长度为8位(英文字母数字)，
secret	加签因子。由晓多提供。

签名验证

获取到authorization后，检查 app_id 和 sign计算值是否正确。

2.订单相关API标准

订单详情

接口地址：/open/order/detail

请求方式：POST

请求参数：

参数名	参数类型	是否必须	示例值	描述
order_id	String	是		订单Id

返回参数：

备注：一订单号多物流单号的情况，多物流信息放在子订单列表中，子订单没有的信息为空即可。

参数名	参数类型	是否必须	描述
order_id	String	是	订单id
app_id	String	是	电商机器人app_id
buyer_id	String	是	买家id
buyer_nick	String	否	买家昵称
created_time	Number	是	订单创建时间。精度毫秒，如1605771308000
update_time	Number	是	订单更新时间。精度毫秒，如1605771308000
status	Number	是	订单状态。10:待付款 20:已付款 30:已发货 31:部分已发货 40:已签收 41:部分已签收 50:已成功 60:订单失败
address	String	否	收货地址
mobile	String	否	收获人手机号
items	[]Item	是	订单内商品信息。
logistics	Logistics	否	订单物流信息。使用物流催促功能必填。
orders	[]Order	是	子订单列表

Order:

参数名	参数类型	是否必须	描述
order_id	String	是	订单id
app_id	String	是	电商机器人app_id
buyer_id	String	是	买家id
buyer_nick	String	否	买家昵称
created_time	Number	是	订单创建时间。
update_time	Number	是	订单更新时间
status	Number	是	订单状态。10:待付款 20:已付款 30:已发货 40:已签收 50:已成功 60:订单失败
address	String	否	收货地址
mobile	String	否	收获人手机号
items	[]Item	是	订单内商品信息
logistics	Logistics	否	订单物流信息。使用物流催促功能必填。

Item：

参数名	参数类型	是否必须	描述
item_id	String	是	商品id
item_name	String	否	商品名称
sku_id	String	否	商品skuid
sku_name	String	否	商品sku名称
count	Number	否	购买个数

Logistics：

参数名	参数类型	是否必须	示例值	描述
out_sid	String	是		物流单id
company_name	String	是		物流公司

获取物流信息

接口地址：/open/order/logistics/info

请求方式：POST

请求参数：

参数名	参数类型	是否必须	示例值	描述
order_id	String	是		订单Id

返回参数：

备注：一订单号多物流单号的情况，不支持催物流功能。此处返回其中一个物流信息即可。

参数名	参数类型	是否必须	描述
order_id	String	是	订单id
out_sid	String	是	物流单id
company_name	String	是	物流公司
status	Number	是	当前物流状态。1.已发货 2.已揽件 3.已完成
traces	[]Trace	是	物流详情（所有步骤）

Trace：

参数名	参数类型	是否必须	描述
time	String	是	时间。格式如"2020-11-12 12:00:00"
desc	String	是	步骤描述
action	Number	是	步骤对应的状态

3.消息相关API标准

3.1 问答消息

消息接收

消息接收地址：由晓多提供

消息体：

参数名	参数类型	是否必须	描述
request_id	String	是	唯一请求ID
app_id	String	是	电商机器人app_id
create_time	Number	是	消息时间戳
originator	Number	是	消息的发起者： 1.代表是电商平台侧发起的会话 2.代表客服主动发起的会话
from_user	User	是	消息的发送者
to_user	User	是	消息的接收者
message	Message	是	消息体
context	Context	是	消息上下文
reception_mode	Number	是	接待模式 1.前置接待（无人值守） 2.辅助接待

User：

参数名	参数类型	是否必须	描述
user_id	String	是	电商平台方用户唯一标识
role	Number	是	身份角色：1.买家 2.卖家
nick_name	String	是	用户昵称

Message：

参数名	参数类型	是否必须	示例值	描述
content_type	Number	是		消息类型。 1.文本消息 2.图片消息 3.商品卡片消息 4.订单卡片消息
content	Content	是		消息内容

Content

1）文本消息

参数名	参数类型	是否必须	示例值	描述
text	String	是	你好	文本内容

2）图片消息

参数名	参数类型	是否必须	示例值	描述
uri	String	是	https://www.test.com/pic/abc.jpg	图片链接，以.jpg / .png等图片的格式结尾
width	Number	是	700	图片高度
height	Number	是	400	图片宽度

3）商品卡片消息

参数名	参数类型	是否必须	示例值	描述
text	String	是	589635658607	商品id

3）订单卡片消息

参数名	参数类型	是否必须	示例值	描述
text	String	是	2019300006376384	订单id

Context：

参数名	参数类型	是否必须	示例值	描述
app_id	String	是		电商机器人app_id

返回码说明：见返回码定义

返回结果：同请求返回定义

{
    "code": 400000，
    "msg": "",
    "data": {}
}

消息发送

接口地址：/open/message/send

请求方法：POST

参数名	参数类型	是否必须	描述
request_id	String	是	唯一请求ID
app_id	String	是	电商机器人app_id
type	Number	是	事件类型 1.消息 2.转接
originator	Number	是	消息的发起者： 1.代表是电商平台侧发起的会话 2.代表客服主动发起的会话
from_user	User	是	消息的发送者
to_user	User	是	消息的接收者
message_list	[]Message	是	回复消息列表
transfer	String	否	转接客服
hint_list	[]Hint	否	消息提示
question_id	Number(int64)	是	问题所属的场景id
readable_question	String	是	问题所属的场景label

User：

参数名	参数类型	是否必须	描述
user_id	String	是	电商平台方用户唯一标识
role	Number	是	身份角色：1.买家 2.卖家
nick_name	String	是	用户昵称

Message：

参数名	参数类型	是否必须	示例值	描述
content_type	Number	是		消息类型
content	Content	是		消息内容

Hint:

参数名	参数类型	是否必须	示例值	描述
text	String	是		文本消息
pics	[]Pic	是		图片消息

Pic:

参数名	参数类型	是否必须	示例值	描述
url	String	是		图片链接

Content：同消息接收Content

返回码说明：见返回码定义

返回结果：同请求返回定义

{
    "code": 400000,
    "msg": "SUCCESS",
    "data": {}
}

3.2 订单消息推送

发生以下事件时，需要推送订单消息。

事件类型	消息类型标识
订单状态变更	order.update
新增订单	order.add

消息接收地址：由晓多提供

消息结构：

参数名	类型	是否必须	示例值	描述
event_id	String	是		消息唯一id
order_id	Number	是		订单id
app_id	String	是		电商机器人app_id
buyer_id	Number	是		买家id
event_type	String	是	order.add	消息类型标识。
create_time	Number	是		创建时间.
status	Number	是		订单状态。
test	Boolean	是		是否心跳测试事件

3.3 商品消息推送

发生以下事件时，需要推送商品消息。

事件类型	消息类型标识
新增商品	goods.add
商品上下架状态变更	goods.update
商品名称变更	goods.update
删除商品	goods.delete

消息接收地址：由晓多提供

消息结构：

参数名	类型	是否必须	示例值	描述
event_id	String	是		消息唯一id
goods_id	Number	是		商品id
app_id	String	是		电商机器人app_id
event_type	String	是	goods.add	消息类型标识。
create_time	Number	是		创建时间
status	Number	是		商品状态。
title	String	否		商品名称。变更时必填。
test	Boolean	是		是否心跳测试事件

4. 商品相关API标准

商品详情

接口地址：/open/goods/info

请求方式：POST

请求参数：

参数名	参数类型	是否必须	示例值	描述
goods_id	String	是		商品Id

返回参数：

参数名	参数类型	是否必须	描述
goods_id	String	是	商品id
goods_name	String	是	商品名称
goods_url	String	是	商品链接
goods_img	String	是	商品图片链接
plat_cid	String	是	商品平台分类id
status	Number	是	商品状态 1.上架 2.下架 3.删除 4.从未上架
app_id	String	是	电商机器人app_id
sku_list	[]Sku	是	sku列表
props	[]Prop	否	商品属性。使用尺码表必填。

Sku:

参数名	参数类型	是否必须	描述
sku_id	String	是	sku的id
sku_name	String	是	sku名称
sku_url	String	是	sku链接
sku_cid	String	是	sku类别id
price	String	否	sku价格
status	Number	是	sku状态
quantity	Number	否	sku数量
props	Prop	否	商品属性。使用尺码表必填。

Prop：

参数名	参数类型	是否必须	描述
name	String	是	属性名称。尺码表固定名称：尺码、尺寸、鞋码
value	[]String	是	属性值列表

商品列表

接口地址：/open/goods/list

请求方式：POST

请求参数：

参数名	参数类型	是否必须	描述
app_id	String	是	电商机器人app_id
page	Number	是	第几页。0 < 数值 < TotalPageCount
page_size	Number	是	每页条数。范围为10～100，默认为20

返回参数：

参数名	参数类型	是否必须	示例值	描述
items	[]Item	是		商品列表
total	Number	是		商品总数

Item：同商品详情/open/goods/info返回的单个商品。

获取类目属性列表

接口地址：/open/goods/category/list

请求方式：POST

请求参数：

参数名	参数类型	是否必须	示例值	描述
app_id	String	是		电商机器人app_id

请求返回：

参数名	参数类型	是否必须	示例值	描述
categorys	[]Category	是		商品类别列表

Category：

参数名	参数类型	是否必须	示例值	描述
cid	String	是		商品类别Id
name	String	是		商品类别名称

电商机器人第三方接入标准

电商机器人第三方接入标准API

1.API开发指南

前期准备

API调用参数说明

请求Header

请求Body

请求返回

返回码定义

签名算法

2.订单相关API标准

订单详情

获取物流信息

3.消息相关API标准

3.1 问答消息

消息接收

Content

消息发送

3.2 订单消息推送

3.3 商品消息推送

4. 商品相关API标准

商品详情

商品列表

获取类目属性列表

results matching ""

No results matching ""