HTTP Request

  1. Public Parameters
  2. Request Structure
  3. Sign Rules
  4. Example

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

  1. 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.
  2. 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
  3. There must be a parameter named ‘app_id’
  4. Sort all parameter in the key’s alphabetic order. Create a string which concatenate all key-value pair in such order.
  5. Sort all key-value pairs in the key’s alphabetic order and concatenate them to a string.
  6. Concatenate the user’s secret_key at the tail of the string. For details, please read the example
  7. 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&timestamp=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"
    }
}