旺POS平台业务接入指南 -

1. 旺POS平台业务接入介绍

1.1 旺POS平台介绍

1.2 业务接入步骤说明

参考业务接入平台网站：http://bp.weipass.cn

2.接口整体说明

2.1 接口预览

2.2 访问安全控制说明

接口有两大类：旺POS平台侧实现和业务提供方实现，针对不同类型的接口有不同的访问安全控制方式。

旺POS平台侧实现的接口：通过access_token加上https来实现访问的权限和数据安全。
业务提供方侧实现的接口：通过消息签名来确定访问的数据据真实性和完整性，如果业务数据对安全比较敏感，建议业务提供方实现https访问协议。

2.2.1 获取access token

access_token是业务接入的全局唯一票据，调用各接口时都需使用access_token。正常情况下access_token有效期为7200秒，重复获取将导致上次获取的access_token失效。由于获取access_token的api调用次数非常有限，建议开发者全局存储与更新access_token，频繁刷新access_token会导致api调用受限，影响自身业务。接口调用者可以使用AppID和AppSecret调用本接口来获取access_token。AppID和AppSecret可在业务接入平台中获得。接口详见下一节的接口定义。

2.2.2 验证旺POS平台请求数据的真实性

所有由旺POS平台访问到业务提供方的接口，都会带上三个参数（signature、timestamp、nonce）访问业务提供方设置的URL，业务提供者通过对签名的效验判断此条消息的真实性。

参数	描述
signature	加密签名，signature结合了开发者填写的token参数和请求中的timestamp参数、nonce参数
timestamp	时间戳
nonce	随机数

业务提供者通过检验signature对请求进行校验。加密/校验流程如下：

1. 将token、timestamp、nonce三个参数进行字典序排序
2. 将三个参数字符串拼接成一个字符串进行sha1加密
3. 获得加密后的字符串可与signature对比，标识该请求来源于旺POS平台

2.3 全局返回码说明

返回码	说明
-1	系统繁忙
0	请求成功
10	不支持的操作
11	通用操作错误
12	通用系统错误
101	获取access_token时AppSecret错误，或者access_token无效

3. 接口详细定义

3.1 测试接口（Echo）

该接口用来测试业务提供者的接口是否能正确调用，由业务提供侧实现。

接口调用请求说明

http请求方式: POST

参数说明

参数	是否必须	说明
event	是	“Echo”
echo_str	是	需返回的字符串

【注】：用于验证消息真实性的3个参数（signature、timestamp、nonce）已略。
返回说明

正常情况下，需要返回下述JSON数据包给调用者：

{
    result : 0
    data: {
            "echo_str ":"xxxx"      //传入的字符串
          }
}

错误时会返回错误码等信息，JSON数据包示例如下:

{"result":11," error ":"xxxx"}

3.2 获取access_token

该接口用来获取access_token，由旺POS平台侧实现。

接口调用请求说明

http请求方式: GET或POST

1.业务应用接入：
http://pos.weipass.cn/WeiposAcc/service/GetAccessToken?appid=APPID&secret=APPSECRET


2. 服务接入：
http://pos.weipass.cn/WeiposAcc/service/GetAccessToken?serviceid=serviceid&secret=APPSECRET

PS:
注意两种接入方式参数不一样

参数

参数	是否必须	说明
appid	否	业务接入唯一凭证
serviceid	否	服务接入唯一凭证
secret	是	业务接入唯一凭证密钥，即appsecret

返回说明

正常情况下，会返回下述JSON数据包给调用者：

{
  result : 0
  data: {"access_token":"ACCESS_TOKEN","expires_in":7200}
}

错误时会返回错误码等信息，JSON数据包示例如下（该示例为AppID无效错误）:

{"result":11," error ":"xxxx"}

3.3 数据上行（DataReceived）

当商户在旺POS上有数据需要传递到业务提供方时，会通过该接口通知到业务接入方，由业务提供侧实现。

接口调用请求说明

http请求方式: POST

参数说明

参数	是否必须	说明
event	是	“DataReceived”
store_id	是	旺POS系统中的店铺ID
device_en	是	设备号
apply_key	是	业务方的商户身份标志，建议申请业务时填写业务方的身份ID，如果不填，则默认等于store_id
data	是	上行的数据内容，字符串，一般用JSON格式表述。
msg_type	是	消息类型：biz_app--业务APP;service_invoke--服务调用

【注】：用于验证消息真实性的3个参数（signature、timestamp、nonce）已略。

返回说明

正常情况下，会返回下述JSON数据包给调用者：

1. msg_type=biz_app,业务APP的消息上行，说明此消息是业务app发起,具体格式如下：
{
    
    "msg_type":biz_app
    "data": {" qr_content ":"xxxx"}         // 业务数据
}

2. msg_type=service_invoke, 服务调用结果的消息上行，当业务侧发起服务调用结束后，服务调用的结果通过此接口传递给业务侧，具体格式如下：
{
    
    "msg_type":service_invoke
    "data": {
               "seq_no":"xxxx" ,    //服务调用流水号
               "base64_val":"xxxx"  // 经过Base64加密后的业务数据
    }    
}

错误时会返回错误码等信息，JSON数据包示例如下:

{"result":11," error ":"xxxx"}

3.4 获取设备状态（GetDeviceStatus）

该接口用来获取旺POS设备运行状态，由旺POS平台侧实现。

接口调用请求说明

http请求方式: GET或POST

url: http://pos.weipass.cn/WeiposAcc/service/GetDeviceStatus

参数

参数|是否必须|说明 access_token|是|access_token device_en|是|数据下行的目标设备号

返回说明

返回说明
{
    "result" : 0
    "data": {
                "status":1          //设备运行状态：0-未激活，1-正常，2-禁用
                ,"online":1         //设备在线状态：0-离线，1-在线
                ,"store_id":"xxxxx" //设备目前归属的店铺id
            }
}

错误时会返回错误码等信息，JSON数据包示例如下:

{"result":11,"error":"xxxx"}

3.5 获取店铺信息（GetStoreInfo）

该接口用来获取店铺信息，由旺POS平台侧实现。

接口调用请求说明

http请求方式: GET
http://pos.weipass.cn/WeiposAcc/service/GetStoreInfo

参数说明

参数	是否必须	说明
access_token	是	access_token
store_id	否	店铺ID
mcode	否	店铺CODE

PS: store_id/mcode 至少传递一个。如果二者都传了，以store_id为准。

返回说明

{
  "result" : 0 ,
  "data" : {
       "mcode" : 100069 ,
       "name" : "1号当铺" ,
       "address" :
               {
                    "address_detail" : "湖南省长沙市岳麓区麓龙路" ,
                    "province" : "湖南省" ,
                    "city" : "长沙市" ,
                    "area" : "岳麓区" ,
                    "location" : [ 112.903384 , 28.219224]
                } ,
      "tel" : "13988888888"
    }
}

错误时会返回错误码等信息，JSON数据包示例如下:

{"result":11,"error":"xxxx"}

3.6 数据下行（PushDataV2）

该接口用来向旺POS设备传输数据，用来控制旺POS设备与线下用户完成近场通讯，由旺POS平台侧实现。

数据下行提供了不同的消息类型用以满足不同的业务场景。消息类型的说明如下：

普通APP消息

适用于将消息发送到业务方自己的应用APP上，旺POS平台对业务数据完全透彻，没有消息格式的要求。

APP通知类消息

适用于将消息发送到旺POS设备上的通知栏。有消息格式的要求，业务数据部分完全透传。

服务调用消息

旺POS的BP平台为业务方提供了一些基础的服务能力，现在已经开放的有"消息"，"收银","订单"等基础服务。业务方可以在BP平台中选择开通此类服务，业务方就具备了对其他业务提供基础服务的能力。“消息基础服务”是由旺POS平台官方实现，其他的业务方可以开通此基础服务，然后通过推送此类型的消息，将消息发送到旺POS设备的"消息服务APP"上。"服务调用"类型的消息不需要业务方开发应用APP并上线，直接服务端对接即可，降低接入门槛。

服务中心模板消息

“模板消息”是“服务调用消息”的早期版，现在已经不再更新维护，建议使用“服务调用消息”进行低门槛接入。

接口调用请求说明

http请求方式: POST
http://pos.weipass.cn/WeiposAcc/service/PushDataV2

参数
普通APP消息POST参数：

access_token=ACCESS_TOKEN,
device_en=xxxxx,
msg_type=’app’,
data={…}

服务中心模板消息POST参数：

access_token=ACCESS_TOKEN,
device_en=xxxxx,
msg_type=’template’,
data=
{
    template_code:xxx,       // 模板code
    key1:xxx,                // 模板中定义的key1,具体参见模板定义
    key2:xxx,                // 模板中定义的key2,具体参见模板定义
    ......
    
}

APP 通知类消息

access_token=ACCESS_TOKEN,
device_en=xxxxx,
msg_type=’notify’,
data=
{
  "icon":"http://wpos.qlogo.cn/a.jpg"     //通知图标
 ,"title":"会员中心"                       // 通知标题
 ,"content":"XXX注册了会员"                // 通知内容
 ,"activity":"cn.shellinfo.weipos.member.MainActivity"     
                                         // 点击通知进入的页面，非必填
 ,"voice":"您有一位新会员注册成功"          // 收到通知时的语音播报， 非必填
 ,”ext”:{                               // 附加数据,参数等， 非必填
     "k1": "echo str"
     ...
   }

}

服务调用类消息

access_token=ACCESS_TOKEN,
device_en=xxxxx,
msg_type=’service_invoke’,
data=
{
  a:1,     // 业务数据
  b:2,     // 业务数据 

}

返回说明

正常情况下，会返回下述JSON数据包给调用者：

- app消息的返回:   {" result ":0}
- template模板消息的返回: {" result ":0, "msg_id":”xxxxx”}
- notify通知消息的返回：{" result ":0}
- service_invoke服务调用消息的返回：{ "result" : 0 , "seq_no" : "xxxx"}, seq_no是此次服务调用的流水号，当服务调用结束，需要通知业务侧本次服务调用的结果时，会通过DataReceived接口通知到业务侧，在DataReceived方法中会把seq_no回传，方便业务侧处理，详情参考DataReceived接口说明。

错误时会返回错误码等信息，JSON数据包示例如下:

{"result":11,"error":"xxxx"}

PS: 服务调用详细文档请参考旺POS服务接入指南

3.7 授权设备使用服务回调通知（ServiceAuthCallback）

该接口用来通知旺POS平台，BP业务侧授权了某个设备对服务的使用，由旺POS平台侧实现。

接口调用请求说明

http请求方式: Post

1.业务应用接入：
http://pos.weipass.cn/WeiposAcc/service/ServiceAuthCallback

参数

参数	是否必须	说明
access_token	是	accessToken
device_en	是	设备En号

返回说明

正常情况下，会返回下述JSON数据包给调用者：

{
  result : 0
  data: {}
}

错误时会返回错误码等信息，JSON数据包示例如下:

{"result":11," error ":"xxxx"}

3.8 消息投递状态查询（getMessageDeliveryStatus）

该接口用来查询推送消息的投递状态，由旺POS平台侧实现。

接口调用请求说明

http请求方式: GET

1.业务应用接入：
http://pos.weipass.cn/WeiposAcc/service/getMessageDeliveryStatus

参数

参数	是否必须	说明
access_token	是	accessToken
seq_no	是	消息id

返回说明

正常情况下，会返回下述JSON数据包给调用者：

{
  result : 0
  data: {
    delivery:1    // 1-投递成功  0-未投递
  }
}

错误时会返回错误码等信息，JSON数据包示例如下:

{"result":11," error ":"xxxx"}

3.9 获取设备公钥（getDevicePublicKey）

该接口用来查询设备的公钥，由旺POS平台侧实现。

接口调用请求说明

http请求方式: GET

1.业务应用接入：
http://pos.weipass.cn/WeiposAcc/service/getDevicePublicKey

参数

参数	是否必须	说明
access_token	是	accessToken
device_en	是	设备En号

返回说明

正常情况下，会返回下述JSON数据包给调用者：

{
  result : 0
  data: {
    public_key:"xxxxxx"
  }
}

错误时会返回错误码等信息，JSON数据包示例如下:

{"result":11," error ":"xxxx"}

3.10 取消订单（cancelPush）

该接口用来取消旺立方订单，由旺POS平台侧实现。

接口调用请求说明

http请求方式: Post

1.业务应用接入：
http://pos.weipass.cn/WeiposAcc/service/cancelPush

参数

参数	是否必须	说明
access_token	是	accessToken
seq_no	是	消息序列号

返回说明

正常情况下，会返回下述JSON数据包给调用者：

{
  result : 0
  data: {
    action:1 | 2 ; // 1-直接取消 2-已经成功下发取消指令，等待设备处理
    info:"成功取消订单"
  }
}

错误时会返回错误码等信息，JSON数据包示例如下:

{"result":11," error ":"xxxx"}