顾客查询

可提供商户订单&包裹状态的查询功能，是客户自助解决问题的高效方案。

介绍

顾客查询：订单 & 包裹状态

使用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".
  }
}

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

下一篇介绍商家主动推送订单回执 & 物流状态更新的接口设置

Previous配置你的电商机器人 Next商家推送

Last updated 5 years ago