# 顾客查询 ## 介绍 #### 顾客查询：订单 & 包裹状态 使用Bothub电商机器人的商户，可以实现自己的订单和物流查询接口，并和Bothub的电商模板接口集成，随后即可让用户以便捷的方式查询自己的订单和物流信息。 正确集成API后用户将可以以如下方式查询订单和物流: * 电商机器人提供的入口，如欢迎消息和菜单里的My Orders, Bothub将引导用户输入自己的信息来进行集成 * 电商机器人内置的识别引擎可以识别用户查询订单的意图，并从用户的话语中分析出邮箱作为账号来进行查询 ## 接口详述 ### 接口加密签名介绍 Bothub会为每一个Bot生成独一无二的私钥。在用户进行订单查询时，Bothub将用此密钥对整个请求的Body进行SHA256加密，并将签名加在请求Header的X-Hub-signature字段里。商户需要验证此字段来证明此请求确实来自Bothub，并注意不要泄露自己的私钥。 商户可以随时在后台更改自己的私钥。 ![](https://docs.bothub.ai/e-commerce-template/img/webhook-manager/key-management.png) ### 接口有效性验证 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". } } ``` ### **Error code** 10001 : User not found ### Package List 物流信息 ### 接口 ``` { "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". } } ``` ### **Error code** 11001 : Order not found 下一篇介绍商家主动推送订单回执 & 物流状态更新的接口设置 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://bothub.gitbook.io/project/advanced-tool/ec-bot/customer-enquiries.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.