电商API

开发人员可以调用JoinChat的电商API，实现符合电商场景的垂直功能

介绍

JoinChat针对电商客户提供了三个功能卡片, 分别是

• 商品查找

• 商品搜索

• 订单查找

使用JoinChat电商机器人的商户，可以实现自己的商品和订单查询接口，并和JoinChat的电商模板三个功能卡片集成，随后即可让用户以便捷的方式查询商品和订单信息。

接口安全性验证

JoinChat会为每一个机器人生成独一无二的私钥。JoinChat调取API时，先用此密钥对整个请求参数进行sha256、base64加密，并将签名加在请求Header的x-joinchat-signature字段里。商户需要验证此字段来证明此请求确实来自JoinChat，并注意不要泄露自己的私钥。 商户可以随时在后台设置--API管理页面更改自己的私钥

开发者可以使用如下代码验证签名：

<?php
// API管理中秘钥
const API_SECRET  = 'xxxxx';

// 伪代码, 从请求头获取签名
$src_sign = $request->header('x-joinchat-signature');

// 伪代码, 获取请求参数, 字符串格式
$input = $request->getContentRaw();

// 对请求参数进行加密生成签名并对比header里的签名
$result_sign = base64_encode(hash_hmac('sha256', $input, API_SECRET, true));
$result = hash_equals($src_sign, $result_sign);

var_dump($result);

获取商品

当用户想查询商品或者，JoinChat将向商户的webhook发送请求参数进行查询

请求参数

{
    "method":"products",
    "params":{
        "title":"T_shirt",
        "product_type":"clothes",
        "vendor":"JACK & JONES",
        "order_type":"title,desc"
    },
    "pagination":{
        "page":1,
        "limit":3
    }
}

• title: 根据商品标题进行模糊查询

• product_type: 根据商品分类来查询

• vendor: 根据商品品牌来查询

• 以上三者之间是 或关系

• order_type是排序规则，以逗号分隔，前面是要排序的字段，后面是升序或者降序。可以排序的值有title,created_at,updated_at,排序只有asc,desc两种

成功返回

{
    "success":true,
    "total" : 1,   //搜索结果的数量
    "data":[
        {
            "title":"商品name",
            "image_url":"商品pic",
            "product_type":"商品类型",
            "vendor":"商品品牌",
            "desc":"商品描述", // 可选
            "detail_url":"商品详情连接", // 可选
            "buy_url":"商品购买链接",
            "price":"商品price",
        }
    ]
}

失败返回

{
    "success": false,
    "errors": "Unknow errors".
}

获取商品品牌和类别

当商店想给顾客更多查询选择，但是考虑到顾客不知道输入什么，JoinChat将向商户的webhook发送请求参数进行查询，获取商家的商品分类和品牌，展示给客户，让客户有明确的选择。

请求参数

{ 
	"method" : "property",
	"params" : { 
		"search_type" : "product_type|vendor", //product_type: 商品类型 vendor: 商品品牌
	} 
}

字段值说明情况如下：

• product_type: 获取商品的所有分类

• vendor: 获取商品的所有品牌

返回结果

品牌接口

{ 
	"success": true,
	"data" :[ 
		"Nike","LiNing","xxx"
	]
}

分类接口

{ 
	"success": true,
	"data" :[ 
		"clothes","T_shirt","xxx"
	]
}

失败返回

{
    "success": false,
    "errors": "Unknow errors".
}

获取订单

• 当用户查询订单时, JoinChat提供给用户两种查询方式, 账户查询和订单号查询

• 查询时JoinChat将向商户的webhook提交请求参数进行查询，获取用户的订单, 然后通过messenger呈现给用户

请求参数

{
    "method":"orders",
    "params":{
        "order_number":"12345678902",                //订单号
        "user_account":"[e-mail]",    //邮箱或者手机号
        //user_account与order_number只能发送一个
        "filter":"open" // 当根据用户账户进行查询时, 可以查询未完成和已完成的订单        
    },
    "pagination":{
        "page":1,
        "limit":3
    }
}

• 如果跟据用户账户获取，params中是user_amount代表用户账号，filter则代表要取什么类型的订单

• • open 代表所有正在进行中的订单

  • closed 代表所有已完成的订单

• 如果根据订单号获取，params中是order_number，代表订单号.

• user_account和order_number只能指定一个

• pagination是用于分页。在用户以账号获取订单列表时给出。page表示页数，limit表示一页的订单数

成功返回

• 返回数据字段含义和是否必传可以参考facebook文档, JoinChat不做处理, 直接传递给facebook

• facebook messenger 回执模板文档

  https://developers.facebook.com/docs/messenger-platform/reference/template/receipt/

	"success": true,
	"total" : 2,
	"data" : [
	{
		"template_type":"receipt", // 必须为receipt
		"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",        
		"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"
		  }
		]
	}, 
	{
		"template_type":"receipt", //必须为receipt
		"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",    
		"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,
    "errors": "Unknow errors".
}