1.公共参数
公共接口参数是指每次调用API都需要带上的参数。如下表所示。
参数名称 | 类型 | 描述 | 是否必须 |
app_id | string | 用户应用ID,公共参数 | Y |
timestamp | long | unix格式时间戳,秒级 | Y |
random | long | 随机数,6-10位 | Y |
sign | string | 整个请求参数的签名 | Y |
2.请求结构
服务地址
对于每一个API调用,都是通过URL来标志具体调用哪个功能接口的。
URL格式形如https://ip/openapi/apiType/action 。
各字段描述如下:
ip | 对应IPC的IP地址 |
openapi | 统一标识符,表示开放API |
apiType | API类别 |
action | 表示对应的接口动作名称 |
通信协议
为了通信安全,通过HTTPS通道来请求调用API。
请求方法
目前只支持HTTPS POST方法来进行请求调用。报文Content-Type为application/x-www-form-urlencoded。 如有特殊情况,会在对应的API接口中描述。
请求参数
每一次请求调用都需要带上参数,参数分为公共参数(见公共参数一节描述)和对应接口的特定参数。
3.签名规则
每个HTTPS请求报文都需要带上签名,IPC设备会验证签名是否合格。
对于所有的接入开发者,数字店铺开放平台会分配以下内容:
- app_id: 唯一标识接入身份 (如果是专用接口,暂时可以不提供app id)
- secret_key: 该用户独有的签名校验
签名规则
- 参数必须包含random字段,为一个随机字符串,由数字和字母组成,长度范围为6-10位。
- 参数必须包含timestamp字段 ,为当前的unix timestamp,精度到秒级,10位数字, 格式可以参考https://tool.chinaz.com/tools/unixtime.aspx。
- 参数必须包含app_id字段。
- 首先对于所有的非空参数按照ASCII码顺序从小到大排序,将key-value键值对依此组成字符串。
- 在字符串尾部拼接该开发者独有的签名秘钥secret key值。
- 对字符串进行MD5签名,对生成的MD5签名转化为全大写。
验证
IPC收到请求后,根据同样的规则来验证签名是否正确,以此判断请求是否合法。
签名示例
假如需要传入的参数如下:
product_id:
389238 user_id: 29389 content: newproductmask environment: test |
则按照规则生成签名为
str1= “app_id=2039dds&content=newproductmask&environment=test&product_id=389238&random=289192×tamp=1593029283&user_id=29389” str2 = str1 + “&key=kdsofkdsnflke9382938k” sign = MD5(str2).upper() |
最终HTTP报文请求中所带参数为
app_id:2039dds product_id: 389238 user_id: 29389 content: newproductmask environment: test sign: 6200690DDBBB9719749D4277B420E8C0 timestamp: 1593029283 random:289192 |
4.示例
请求示例
POST /openapi/config/setWifiConf HTTP/1.1 Host: 192.168.1.1 Content-Type: application/x-www-form-urlencoded app_id=mdk923idkf&random=289192×tamp=15930292837& sign=IDKNFLK392038KDS932K&ssid=sunmi_ipc&password=1234567890 |
返回结果示例
HTTP请求的返回结果为json格式的内容,下面是一个简单示例。
如下,code字段是一定会有的,表示处理结果。data字段因不同的API而不同,有的API有返回data字段,有的则没有。
{ ‘code’: 0, ‘data’: { ‘ssid’: ‘SUNMI_IPC’, ‘password’: ‘1234567890’ } } |