When using the Udesk Open API (v2), the following rules must be followed:
- The default frequency limit for APIs is 60 times/minute, so any API can be called up to 60 times in 1 minute;
- All APIs are designed for server-side calls, please do not call them on the client side (web front-end pages, mobile applications, etc.), otherwise there may be a risk of authentication token leakage.
Call Format
HTTP Method
The Udesk Open API (v2) may use the following HTTP methods:
- GET: Used to obtain data interface
- POST: Used to create interface
- PUT: Used to modify interface
- DELETE: Used to delete interface
We will indicate the HTTP method used in each interface document. Please refer to the specific interface document when calling the interface.
Call Address
The call address of the Udesk development interface conforms to the following format:
https://[subdomain].udesk.cn/open_api_v1/[interface_relative_address]?[URL_parameters]&email=[administrator_email]×tamp=[timestamp]&sign=[signature]&nonce=[unique_identifier_of_request]&sign_version=[signature_algorithm_version]
The meanings of the parts enclosed in brackets are as follows:
| Variable | Description |
|---|---|
| a | b |
| Variable | Description |
|---|---|
| subdomain | The subdomain you use to access the Udesk customer service system. |
| interface_relative_address | The relative URL of the specific API you are calling, which will be indicated in each API. |
| URL_parameters | Query String parameters required by the interface. |
| administrator_email | Your super administrator email. |
| timestamp | The timestamp when the request was initiated, in Unix Time format, i.e. the number of seconds from "1970-01-01 00:00:00" to now. |
| signature | The signature for identity authentication. Unless otherwise specified, it needs to be carried with each API call. See Authentication Method for the calculation method. |
| unique_identifier_of_request | Can only be used once within 15 minutes. |
| signature_algorithm_version | The value is fixed as v2. |
Each interface document will give a call method similar to the following: GET /customers It contains the HTTP method and the relative address of the interface. Other parts need to be replaced according to the specific situation.
Parameters
There may be three types of parameters in the interface document:
- In the URL: Parameters embedded in the call address, such as
:idin/customers/:id; - Query String: Parameters in the Query String part of the call address, such as
pagein/customers?page=2; - Request Body: The content in the request body. When calling creation or modification interfaces, you need to convert the request data into UTF-8 text in JSON format and pass the encoded string as a Request Body parameter to the corresponding interface. Also set the Content-Type field in the request header to application/json.
Return Results
The return data of the Udesk Open API (v2) is also a UTF-8 string encoded in JSON format.
Code Error Code and Description
See Code Error Code Description
Authentication Method
Rule Description
All interface calls need to carry the signature parameter sign. Only when the sign value is legal will the request be accepted. The calculation method of sign is as follows:
sign=SHA256(email&open_api_token×tamp&nonce&sign_version)
Note: If SHA256 authentication fails, please use SHA1
Where:
- email is the email address of the super administrator;
- open_api_token is the API authentication token, which needs to be obtained by calling Get Authentication Token Interface;
- timestamp is Unix time, i.e. the number of seconds from "1970-01-01 00:00:00" to now;
- nonce is a unique string provided by the caller, which can only be used once within 15 minutes;
- sign_version is the signature algorithm version, and the value is fixed as v2.
Example
Suppose you want to call the following interface:
https://demo.udesk.cn/open_api_v1/customers
The data required for authentication is as follows:
| Name | Data |
|---|---|
| Administrator email | admin@udesk.cn |
| API Token | 233df89e-b4a2-42e0-89af-f295b1078686 |
| timestamp | 1494474404 |
| nonce | 2d931510-d99f-494a-8c67-87feb05e1594 |
| sign_version | v2 |
Calculate sign
sha256("admin@udesk.cn&233df89e-b4a2-42e0-89af-f295b1078686&1494474404&2d931510-d99f-494a-8c67-87feb05e1594&v2") #=> 6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52
Note: If sha256 authentication fails, please use sha1
The final request URL:
Authentication Failure Return Data
| Attribute Name | Value | Description | Remarks |
|---|---|---|---|
| code | 2059 | Open API signature is incorrect | Authentication failed (authentication parameter error) |
Common Data
Paging Information
When obtaining a list and other interfaces, the returned data usually carries paging information (meta), which is as follows:
| Attribute Name | Type | Description |
|---|---|---|
| current_page | Integer | Current page number |
| total_pages | Integer | Total number of pages |
| total_count | Integer | Total amount of data |
Code Error Code Description
| Error Code | Message Information | Exception: Message Information | Description |
|---|---|---|---|
| 2002 | Invalid subdomain | None | Domain name input error |
| 2005 | Parameter error | None | Password input error |
| 2015 | Non-administrators cannot operate | None | The identity used for authentication is not an administrator |
| The resource was not found | None | Account input error or no such account | |
| 2058 | Your company is not a professional version | None | The company has not paid |
| 2059 | Open API signature is incorrect | None | Authentication parameter error |
| 20621 | The timestamp format is incorrect | Same as message | Required parameter {timestamp} is not filled in or the format is incorrect |
| 20622 | The timestamp error cannot exceed 5 minutes | Same as message | The difference between parameter {timestamp} and the current time exceeds 5 minutes |
| 20623 | The request is only valid once, and the nonce value cannot be repeated within 15 minutes | Same as message | The authentication parameter {nonce} has been used within 15 minutes |
| 20624 | Open API nonce is empty | Same as message | The authentication parameter {nonce} is not filled in or is empty |
| 2000 | Unknown error | param is missing or the value is empty: notice_url notice_url parameter is empty | notice_url parameter cannot be empty |