使用Bothub电商机器人的商户,可以实现自己的订单和物流查询接口,并和Bothub的电商模板接口集成,随后即可让用户以便捷的方式查询自己的订单和物流信息。 正确集成API后用户将可以以如下方式查询订单和物流:
电商机器人提供的入口,如欢迎消息和菜单里的My Orders, Bothub将引导用户输入自己的信息来进行集成
电商机器人内置的识别引擎可以识别用户查询订单的意图,并从用户的话语中分析出邮箱作为账号来进行查询
Bothub会为每一个Bot生成独一无二的私钥。在用户进行订单查询时,Bothub将用此密钥对整个请求的Body进行SHA256加密,并将签名加在请求Header的X-Hub-signature字段里。商户需要验证此字段来证明此请求确实来自Bothub,并注意不要泄露自己的私钥。
商户可以随时在后台更改自己的私钥。
Bothub在电商机器人webhook配置页提供了测试接口的功能,以便商户了解Bothub的请求结构,签名算法等。以验证webhook的有效性。
{"request":{"category": "ecommerce","method": "test","id": "test_12582312","page_id": "231231232134111","meta": ""},"params": {"test_token" : "12345"}}
Bothub会在params字段中放置随机生成的test_token字段。商户需要读取该字段并返回。如果商户返回是正确的,Bothub则认为该webhook验证通过。
{"success": true,"object": "test","test_token" : "12345"}
{"request":{"category": "ecommerce","method": "orders","id": "order_list_12582312","page_id": "231231232134111","meta": ""},"params": {"user_account" : "jicheng@bothub.ai""filter": "open","order_number": 12344556, // user_account和order_number只能取一个},"pagination": {"page": 1,"limit": 3}}
根据用户账户,或者订单号获取订单列表。
如果跟据用户账户获取,params中是user_account代表用户账号,filter则代表要取什么类型的订单
open 代表所有正在进行中的订单
unpaid 代表所有未支付的订单
past 代表所有已完成的订单
如果根据订单号获取,params中是order_number,代表订单号.
user_account和order_number只能指定一个
pagination是用于分页。在用户以账号获取订单列表时给出。page表示页数,limit表示一页的订单数
{"success": true,"object": "orders","has_next_page" : true,"orders" : [{"recipient_name":"Stephane Crozatier", // 收货人姓名"order_number":"12345678902", // 订单号"currency":"USD", // 订单货币"payment_method":"Visa 2345", // 支付方式"order_url":"http://petersapparel.parseapp.com/order?order_id=123456", // 订单Url,订单详情卡片会将此链接以按钮形式展示,供用户点击跳转"timestamp":"1428444852", // 订单发生的时间戳"status": "unpaid", // 订单状态"address":{ // 订单地址"street_1":"1 Hacker Way","street_2":"","city":"Menlo Park","postal_code":"94025","state":"CA","country":"US"},"summary":{ // 订单金额总结"subtotal":75.00,"shipping_cost":4.95,"total_tax":6.19,"total_cost":56.14},"adjustments":[ // 订单使用优惠情况{"name":"New Customer Discount","amount":20},{"name":"$10 Off Coupon","amount":10}],"elements":[ // 订单货品{"title":"Classic White T-Shirt","subtitle":"100% Soft and Luxurious Cotton","quantity":2,"price":50,"currency":"USD","image_url":"http://petersapparel.parseapp.com/img/whiteshirt.png"},{"title":"Classic Gray T-Shirt","subtitle":"100% Soft and Luxurious Cotton","quantity":1,"price":25,"currency":"USD","image_url":"http://petersapparel.parseapp.com/img/grayshirt.png"}]},{"recipient_name":"Stephane Crozatier","order_number":"12345678902","currency":"USD","payment_method":"Visa 2345","order_url":"http://petersapparel.parseapp.com/order?order_id=123456","timestamp":"1428444852","status": "unpaid","address":{"street_1":"1 Hacker Way","street_2":"","city":"Menlo Park","postal_code":"94025","state":"CA","country":"US"},"summary":{"subtotal":75.00,"shipping_cost":4.95,"total_tax":6.19,"total_cost":56.14},"adjustments":[{"name":"New Customer Discount","amount":20},{"name":"$10 Off Coupon","amount":10}],"elements":[{"title":"Classic White T-Shirt","subtitle":"100% Soft and Luxurious Cotton","quantity":2,"price":50,"currency":"USD","image_url":"http://petersapparel.parseapp.com/img/whiteshirt.png"},{"title":"Classic Gray T-Shirt","subtitle":"100% Soft and Luxurious Cotton","quantity":1,"price":25,"currency":"USD","image_url":"http://petersapparel.parseapp.com/img/grayshirt.png"}]}]}
{"success": false,"error": {"code": 14222,"message": "User not found".}}
10001 : User not found
{"request":{"category": "ecommerce","method": "packages","id": "packages_213124","page_id": "231231232134111","meta": ""},"params": {"order_number": "12345"},"pagination" : {"page": 1,"limit" : 3}}
当用户想查询一个订单的所有包裹,或者是查看某个特定的包裹的送达情况时,Bothub将向商户的webhook发出此接口进行查询。 params字段为用户以什么来查询的物流情况,可选值如下:
order_number: 查询该订单指定的所有包裹
package_number: 查询该包裹号对应的所有包裹
此两者不兼容,只能指定一个。
{"success": true,"object": "packages","has_next_page": true,"packages": [{"order_number": 12345, // 订单号"package_number" : "A1231411", // 包裹编号"product_name": "Classic White Shirt", // 包裹中主要商品的名字"carrier": "UPS", // 承运商"tracking_number": "UPS11012", // 承运商包裹编号"tracking_url": "http://www.ups.com?id=aaaaaa", // 包裹在承运商处的追踪地址"package_status": "Delivery in progress", //包裹状态"exp_delivery": "2017-12-12", // 预订送达日期。如果包裹是已送达状态,即位送达日期"image_url" : "http://image.com/image1" // 包裹图片},{"order_number": 23456,"package_number": "A12345zzz","product_name": "Classic White Shirt 2","carrier": "USPS","tracking_number": "USPS12345","tracking_url": "http://www.ups.com?id=aaaaaa","package_status": "Delivery in progress","exp_delivery": "2018-01-11","image_url" : "http://image.com/image1"}]}
{"success": false,"error": {"code": 14223,"message": "Order not found".}}
11001 : Order not found
下一篇介绍商家主动推送订单回执 & 物流状态更新的接口设置