0.5API接口方式

优质

小牛编辑

132浏览

2023-12-01

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&timestamp=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"
}