0.5API接口方式
API接口对接方式复杂难度大已不建议使用,强烈建议使用0.4DLL接口方式。
基本要求
1.请求地址URL大小写敏感,请按协议要求的大小写地址。
2.协议返回数据格式为json,如:{"status":1,"info":"提交成功"},
{"status":0,"info":"保存失败"}下面协议中不再重复说明。
返回数据中,status为返回码,协议约定1为正常返回,0或非1为出错,错误信息为info。
3.接口协议get部分公共参数如下:
gpid:应用id
msid:门店编号
timestamp:日期格式yyyyMMddHHmmss,如:20190820115428;注意:时间会进行校验,请保证时间误差不超过60分钟
nonce:随机数
signtype:签名方式,目前取值:sha1
公共参数每次接口请求都需要提供。后续的接口说明中为了简化,不再列出公共参数说明。
请求格式和接口地址
1.请求参数为单一的JSON数据,分为action,get, post三部分,其中get部分需要进行签名。例如:
{
"action": {
"action": "sys_init"
},
"get": {
"gpid": "gp1339f3a58baa98df",
"msid": "113",
"nonce": "1133496737",
"signtype": "sha1",
"timestamp": "20190820115428",
"protocal": "mqtt"
}
}
注意:JSON大小写敏感,请注意字母大小写。
2.请求数据提交方式:JSON数据POST方式提交.
3.接口地址:http://api.dc78.cn/Api,除第一次接口初始化请求外用此地址外,其它接口请求需要使用0.2返回的API接口地址(不同商户的地址有可能不同)
数字签名生成方式
每个客户会有一个对应的ApiKey如5d048e69ee55a71899392f5c2c8b24f1db07b7c5,开发商使用的应用ID(gpid)对应会有一个应用密钥(appsecret)如:30461a27b7b0871c0dc3aae05387ce09c4991756;最终签名密钥为:商家"ApiKey,应用密钥",在此例中为:5d048e69ee55a71899392f5c2c8b24f1db07b7c5,30461a27b7b0871c0dc3aae05387ce09c4991756。(注意中间半角逗号)
http请求时,将上述要求get参数部分按键名排序后,用&号连接,再最后再加上签名密钥,(签名密钥与前面串用逗号分隔)如下验证串
“gpid=gp1339f3a58baa98df&msid=113&nonce=1133496737&protocal=mqtt&signtype=sha1×tamp=20190820115428,5d048e69ee55a71899392f5c2c8b24f1db07b7c5,30461a27b7b0871c0dc3aae05387ce09c4991756”
msg_sign=sha1(验证串)
最后提交的请求为:
{
"action": {
"action": "sys_init"
},
"get": {
"gpid": "gp1339f3a58baa98df",
"msid": "113",
"nonce": "1133496737",
"signtype": "sha1",
"timestamp": "20190820115428",
"protocal": "mqtt",
"msg_sign": "57BC076DFC5843AD73E53270608737941F8C25E0"
}
}
注意:
1.ApiKey,appsecret仅仅在生成签名时需要用,在提交时不能加上!!。
2.POST部分参数不需要参与签名
涉及到URL参数中有中文,会涉及到转码问题。
首先URL参数的内容先进行AnsiToUtf8转换赋值后,再按要求进行签名。
门店系统接口启动时需要先做一次初始化,初始化接口类型及根据返回的商家接口地址来调用后续的所有接口请求。(不同的商户会对应不同的API接口地址)
请求参数说明
参数 | 描述 | 必填 | 示例值 | 类型 | 最大长度 |
action | 接口参数组 | 是 | object | ||
└action | 需要调用的接口名称 | 是 | sys_init | string | |
get | GET参数组,本组参数需要参与签名 | 是 | object | ||
└protocal | 推送接口采用的协议类型,建议为mqtt | 否 | mqtt | string | |
└processid | 接口程序进程id,记录日志,方便跟踪问题 | 否 | 18328 | number | |
└pcname | 接口程序电脑名称,记录日志,方便跟踪问题 | 否 | DESKTOP-2VDG1ET | string | |
└file | 接口程序文件名,记录日志,方便跟踪问题 | 否 | D:\work\dev\test.exe | string | |
└handle | 网关模式时接口程序接收消息句柄。记录日志,方便跟踪问题 | 否 | 133242 | number | |
└clientver | 客户端接口协议版本,3.2需要实现do-sync接口 | 否 | 3.2 | number |
请求示例
{ "action": { "action": "sys_init" }, "get": { "protocal": "mqtt", "processid": "18328", "pcname": "DESKTOP-2VDG1ET", "file": "D:\\work\\dev\\test.exe", "handle": "133242", "clientver": "3.2" } }
响应参数说明
参数 | 描述 | 必填 | 示例值 | 类型 | 最大长度 |
status | 返回状态。接口成功时为1,出错为0 | 是 | 1 | number | |
info | 返回信息。错误时会返回相应的错误信息 | 是 | ok | string | |
ver | API接口版本号 | 否 | 3.0 | string | |
mqtthost | 采用MQTT推送消息时的MQTT主机地址,当请求参数protocal=mqtt时返回 | 否 | emqtt.dc78.cn:1883 | string | |
expiryDate | 商户门店的过期时间 | 是 | 20240511 | string | |
apihost | 商户所在API主机域名,后续调用API接口使用此域名 | 是 | http://hz-api.dc78.cn/Api | string |
响应示例
{ "status": "1", "info": "ok", "server_timestamp": 1566038459, "server_time": "2019-08-17 18:40:59", "server_name": "wx-task2.hz", "ver": "3.0", "mqtthost": "emqtt.dc78.cn:1883", "apihost": "http://hz-api.dc78.cn/Api", "expiryDate": "20240511" }