电商机器人第三方接入标准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字段

1.API开发指南

前期准备

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

API调用参数说明

API接口实现统一使用POST请求方式,Content-Typeapplicatioin/json格式。

请求Header
字段 字段类型 是否必须 描述
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 消息提示

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 商品类别名称

results matching ""

    No results matching ""