美而鲜接口文档

一、准备

• 售货机供应商需要提供一个固定的主机地址，所有接口均基于此地址完成
• 对不同的请求，在主机地址的基础上增加不同二级地址和参数，以GET或POST方式完成

GET http://host_url/action_url?param1=val1&param2=val2...
POST http://host_url/action_url

请为POST请求加入以下请求头：

Content-Type: application/json; charset=utf-8

以下是一个完整的POST请求体：

{"supplier":"JHAaMFbxlLjkHwEe","validate":"00db0cf64f900dfdfc6533886111db5da4d308afb5d843b485e73625826621bc","timestamp":1532835342,"machine_id":"abc001","code":"asc001","count":2,"price":34,"sheetNumber":"20180725033542462","hash":"3a3ba31a16a128ac942ffa630ef70d2e44e495c180689aa38d3fa8c400a40b37"}

以下是一个完整的返回消息：

{"status":1,"msg":"ok","data":{"name":"水果套餐1","count":50,"price":34,"code":30131c3f1e5ff734b93,"status":1,"imgUrl":"http://abc.com/sale/sale1photo.jpg"}

注意，每个返回消息都应该包含以下3个基本字段：

参数	必须	类型	缺省值	说明
status	true	int	-	返回码，1表示正常返回，其余表示非正常返回
msg	true	string	-	返回说明，当status为非1值时说明错误的原因
data	true	object	-	返回数据体

二、鉴权

后台服务器对售货机发起的所有请求均将进行鉴权，鉴权涉及以下3个字段：

supplier 由字符、数字组成的，长度为16字节的字符串，用以区分不同的售货机供应商
timestamp 当前的LINUX时间戳，每次请求的有效期为30秒，不在此范围内的请求将被忽略
validate 由supplier、token*、timestamp的值拼接后再进行hash-sha256运算得到的字符串

* token为由字符、数字组成的，长度为32字节的字符串，与supplier一起发放。请确保supplier与token均被妥善保护，任何时候token都不允许以明文形式出现在接口的数据传输过程，否则可能造成严重后果。

三、数据的Hash校验

除前述的3个关键字段外，售货机向后台服务器发起的每次请求，都必须附带以下1个字段：

hash 由所有提交字段的值拼合后再进行hash-sha256运算得出。hash校验失败的请求将被忽略

---

四、接口

1、商品同步接口

GET http://host_url/mex_sync_sales?machine_id=1

接口功能
同步某台售货机的所有商品

发起方
美而鲜后台

接收方
售货机后台

url
http://host_url/mex_sync_sales

请求方式
GET

请求参数

参数	二级参数	必须	类型	缺省值	说明
machine_id	-	true	string	-	供应商提供的机器唯一标识

返回data参数

参数	二级参数	必须	类型	缺省值	说明
sales	-	true	array of object	-	商品列表
-	name	true	string	-	商品名称
-	code	true	string	-	商品唯一编码*
-	price	true	int	-	商品正常售价，用整型表示，如123表示1.23元
-	count	true	int	-	商品当前剩余数量，非负值
-	status	true	int	-	可售状态，1表示在售，0表示禁售
-	imageUrl	true	string	-	商品图地址

* 为免混淆，即使是同样的商品，在不同售货机上也建议采用不同编码。

2、请求支付二维码字符串

POST https://www.meierxian.cn/api/payUrl

接口功能
发送用户在售货机选购的商品，从美而鲜后台获得支付二维码字符串

发起方
售货机后台

接收方
美而鲜后台

url
https://www.meierxian.cn/api/payUrl

请求方式
POST

请求参数

参数	二级参数	必须	类型	缺省值	说明
machine_id	-	true	string	-	供应商提供的机器唯一标识
sheetNumber	-	true	string	-	售货机后台的订单编码*
sales	-	true	array of object	-	商品列表
-	code	true	string	-	商品唯一编码*
-	price	true	int	-	商品正常售价，用整型表示，如123表示1.23元
-	count	true	int	-	商品购买数量，非负值

* 此订单编码用于售货机后台的订单数据维护，由售货机后台生成，允许与美而鲜后台的订单编码不相同

hash计算（伪代码）

hash = sha256(supplier+timestamp+validate+machine_id+sheetNumber+json_encode(sales))

请求示例

{"supplier":"JHAaMFbxlLjkHwEe","validate":"00db0cf64f900dfdfc6533886111db5da4d308afb5d843b485e73625826621bc","timestamp":1532835342,"machine_id":"abc001","sheetNumber":"20180725174123335","sales":[{"code":"asc001","count":2,"price":34},{"code":"asc002","count":3,"price":45}],"hash":"fa62ef2653ab05aa17c68f19ededab53087082cac956de6d9b5c75c721203c29"}

返回data参数

参数	二级参数	必须	类型	缺省值	说明
machine_id	-	true	string	-	供应商提供的机器唯一标识
sheetNumber	-	true	string	-	此前提供的售货机后台的订单编码
url	-	true	string	-	支付页面地址*
sales	-	true	array of object	-	商品列表
-	code	true	string	-	商品唯一编码
-	count	true	int	-	商品购买数量，非负值

* 请在售货机上以二维码方式显示此地址，并引导用户扫码支付

返回示例

{"status":1,"msg":"success","data":{"machine_id":"abc001","sheetNumber":"20180725174123335","url":"https:\/\/www.meierxian.cn\/api\/pay?s=1532918251749793695","sales":[{"code":"asc001","count":2},{"code":"asc002","count":3}]}}

3、支付回调接口

POST http://host_url/mex_pay_callback

接口功能
向售货机后台推送支付结果，完成应答

发起方
美而鲜后台

接收方
售货机后台

url
http://host_url/mex_pay_callback

请求方式
POST

请求参数

参数	二级参数	必须	类型	缺省值	说明
machine_id	-	true	string	-	此前提供的机器唯一标识
sheetNumber	-	true	string	-	此前提供的售货机后台的订单编码
payResult	-	true	int	-	支付结果，1表示成功，否则表示失败
payResultMsg	-	true	string	''	支付结果消息，当payResult为非1值时，提示支付失败的原因
sales	-	true	array of object	-	商品列表
-	code	true	string	-	商品唯一编码
-	out_count	true	int	-	商品应出仓数量，非负值*

hash计算（伪代码）

hash = sha256(supplier+timestamp+validate+machine_id+sheetNumber+payResult+payResultMsg+json_encode(sales))

* 售货机后台在接收到此请求时，必须先完成鉴权和Hash校验，确认数据有效再行出仓

请求示例

{"supplier":"JHAaMFbxlLjkHwEe","validate":"00db0cf64f900dfdfc6533886111db5da4d308afb5d843b485e73625826621bc","timestamp":1532835342,"machine_id":"abc001","payResult":1,"payResultMsg":"","sheetNumber":"20180725174123335","sales":[{"code":"asc001","out_count":2},{"code":"asc002","out_count":3}],"hash":"fa62ef2653ab05aa17c68f19ededab53087082cac956de6d9b5c75c721203c29"}

返回data参数

参数	二级参数	必须	类型	缺省值	说明
machine_id	-	true	string	-	此前提供的机器唯一标识
sheetNumber	-	true	string	-	此前提供的售货机后台的订单编码

返回示例

{"status":1,"msg":"success","data":{"machine_id":"abc001","sheetNumber":"20180725174123335"}}

4、出仓结果通知接口

POST https://www.meierxian.cn/api/outResult

接口功能
售货机在执行出仓动作后，向美而鲜后台推送出仓结果

发起方
售货机后台

接收方
美而鲜后台

url
https://www.meierxian.cn/api/outResult

请求方式
POST

请求参数

参数	二级参数	必须	类型	缺省值	说明
machine_id	-	true	string	-	此前提供的机器唯一标识
sheetNumber	-	true	string	-	此前提供的售货机后台的订单编码
sales	-	true	array of object	-	商品列表
-	code	true	string	-	商品唯一编码
-	out_count	true	int	-	此前提供的商品应出仓数量，非负值
-	success_count	true	int	-	商品成功出仓数量，非负值
-	left_count	true	int	-	商品成功出仓后的剩余数量，非负值

hash计算（伪代码）

hash = sha256(supplier+timestamp+validate+machine_id+sheetNumber+json_encode(sales))

请求示例

{"supplier":"JHAaMFbxlLjkHwEe","validate":"00db0cf64f900dfdfc6533886111db5da4d308afb5d843b485e73625826621bc","timestamp":1532835342,"machine_id":"abc001","sheetNumber":"20180725174123335","sales":[{"code":"asc001","out_count":2,"success_count":2,"left_count":34},{"code":"asc002","out_count":4,"success_count":4,"left_count":30}],"hash":"fa62ef2653ab05aa17c68f19ededab53087082cac956de6d9b5c75c721203c29"}

返回data参数

参数	二级参数	必须	类型	缺省值	说明
machine_id	-	true	string	-	此前提供的机器唯一标识
sheetNumber	-	true	string	-	此前提供的售货机后台的订单编码