Sunmi Developer Docs

1.Background

Authentication is designed to ensure the security of all Open APIs of SUNMI store Open Platform. All HTTP Request in the SUNMI store Open Platform will be authenticated by the method described below. The content below describes how to pass the Sunmi store authentication and use its service.

2. Specification

2.1 Protocol

All open API in SUNMI store open platform uses HTTPS protocol with POST method.

2.2 Sign rules

SUNMI store open platform will distribute the following to all who uses our API:

• 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

The sign of the HTTP request will be generated from the parameters with the following rules:

1. There must be a parameter named ‘random’, it is a random string combination of number and alphabets with the 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. Concatenate the user’s secret_key at the tail of the string. For details, please read the example
6. use the MD5 signature of the string
7. Convert the MD5 sign to all caps.

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

Sunmi Store Open Platform will check if the sign is valid, if the sign is invalid then it will return error code: 5090.
It will then check if the timestamp is within the reasonable time window, if the request is outdated, it will return error code: 5091.

3. Authentication Procedure

SUNMI Store Cloud Platform will conduct authentication in the following sequence. 

4. Return Value

4.1 Error Type

Error types will be returned in HTTP response. If the sign is invalid, then the http status code 401 will be returned.
If the sign is valid, then it will return HTTP status code 200 whatsoever, the error will be returned in the HTTP response body. The structure of our response body is normally:

{
    code：0
    msg: "success"
    data: {}
} 

4.2 Error Code

Error Code	Reason
0	success
5090	invalid sign
5091	timestamp outdated