1.Public Parameters
Public Parameters are required when an API is called. As shown in the table below.
Parameter | Type | Description | Required |
app_id | string | User application ID, used as public parameter | Y |
timestamp | long | Unix timestamp in second | Y |
random | long | A 6-10 digits random number | Y |
sign | string | Signature of the request | Y |
2.Request Structure
Address
The URL is used to identify which interface is called.
OpenAPI URLs looks like https://ip/openapi/apiType/action
The fields of URL are described as follows:
ip | The IPC’s IP address |
openapi | A uniform identifier that represents it is an OpenAPI URL |
apiType | API functional types |
action | the name of the corresponding interface |
Protocol
For security, all APIs use HTTPS Protocol.
Request method
Only HTTP POST method is supported to call the interfaces. The Message content-type is application/x-www-form-urlencoded. Special cases will be described in the corresponding API.
Request parameters
Each interface should be called with parameters. There are public parameters (please refer to Public Parameters ) and private parameters according to the interface.
3. Sign Rules
Each HTTPS request message needs to be signed, and the IPC will verify the signature.
SUNMI store open platform will assign the following parameters to all OpenAPI users:
- app_id: the unique identifier of a user ( for some special API, the app_id can be skipped)
- secret_key: the signing key of the user
Sign rules
- There must be a parameter named ‘random’, it is a random string combination of number and alphabets with a length of 6 to 10 digits.
- There must be a parameter named ‘timestamp’, it is the current 10-digit unix timestamp, for details please visit: https://tool.chinaz.com/tools/unixtime.aspx
- There must be a parameter named ‘app_id’
- Sort all parameter in the key’s alphabetic order. Create a string which concatenate all key-value pair in such order.
- Sort all key-value pairs in the key’s alphabetic order and concatenate them to a string.
- Concatenate the user’s secret_key at the tail of the string. For details, please read the example
- Generate the MD5 signature of the string and convert the MD5 sign to uppercase.
Validation
After receiving the request message, the IPC will use the same rules to check if the sign is valid.
Sign example
Suppose the parameter of the request is the following:
product_id: 389238 user_id: 29389 content: newproductmask environment: test |
Then, by the rules above, we can generate our sign below:
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() |
By the code above, our final request will contains the parameters below:
app_id:2039dds product_id: 389238 user_id: 29389 content: newproductmask environment: test sign: IDKNFLK392038KDS932K timestamp: 1593029283 random:289192 |
4. Example
Request Example
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 |
Response Example
The response to the HTTP request is in json format. Here is a simple example.
As follows, the “code” field always exists, which presents the result of calling. The “data” field is optional depend on different APIs.
{
"code": 0,
"data": {
"ssid": "SUNMI_IPC",
"password": "1234567890"
}
}