HTTP接口调用

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： 该用户独有的签名校验

签名规则

  1. 参数必须包含random字段，为一个随机字符串，由数字和字母组成，长度范围为6-10位。
  2. 参数必须包含timestamp字段 ，为当前的unix timestamp，精度到秒级，10位数字， 格式可以参考https://tool.chinaz.com/tools/unixtime.aspx。
  3. 参数必须包含app_id字段。
  4. 首先对于所有的非空参数按照ASCII码顺序从小到大排序，将key-value键值对依此组成字符串。
  5. 在字符串尾部拼接该开发者独有的签名秘钥secret key值。
  6. 对字符串进行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&timestamp=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&timestamp=15930292837& sign=IDKNFLK392038KDS932K&ssid=sunmi_ipc&password=1234567890

返回结果示例

HTTP请求的返回结果为json格式的内容,下面是一个简单示例。

如下，code字段是一定会有的，表示处理结果。data字段因不同的API而不同，有的API有返回data字段，有的则没有。

{
    ‘code’:              0,
    ‘data’: {
        ‘ssid’:              ‘SUNMI_IPC’,
        ‘password’:         ‘1234567890’
  }
}