This API is intended for interaction between the system and integration modules, the site servicer, an online store, or from a mobile application.
Scheme
When working with API, you must use version v5. Previous API versions are kept for compatibility and are not recommended for use. You can read about API versions and their differences in a separate article. Requests must be sent to:
https://{your-subdomain}.retailcrm.ru/api/{version}/
All requests are only accepted by https encoded in UTF-8. The answer is formed in JSON format.
Data of the "Date" type is specified in the Y-m-d format (for example, 2014-03-21), and data of the "Date/Time" type is specified in the format Y-m-d H:i:s format (for example,2014-03-21 05:14:07).
Authorisation
Authorisation is performed using an API key, which is passed in the GET|POST - parameter apiKey:
https://demo.retailcrm.ru/api/v5/orders?apiKey=X2EDxEta9U3lcsSV0dwdF38UvtSCxIuGh
The API key can also be passed via the header X-API-KEY: X2EDxEta9U3lcsSV0dwdF38UvtSCxIuGh
In the system administrative settings, you will find the API key management section. If the API key is missing or if it is incorrect, API will report an error.
If the API key provides access to the data of several stores, then in some API methods it is additionally required to specify the symbolic code of the store in the GET|POST parameter site. In the reference book, you can see which methods require specifying the store.
GET requests
When referring to API methods of the GET type, parameters must be sent as GET parameters.
An example of the data to be transferred:
https://demo.retailcrm.ru/api/v5/orders?filter[numbers][]=1235C&filter[customFields][nps][min]=5&apiKey=X2EDxEta9U3lcsSV0dwdF38UvtSCxIuGh
POST requests
When referring to API methods of the POST type, parameters must be sent in the application/x-www-form-urlencoded format. In this case, if a nested structure is passed in any of the parameters (for example, in the /api/v*/orders/create method, order data in the order parameter), then the values of such parameters must be passed as a JSON string.
An example of the data to be transferred:
site=simple-site&order=%7B%22externalId%22%3A%22a123%22%2C%22firstName%22%3A%22Tom%22%7D
Frequency of API calls
When accessing API, it cannot address more than 10 requests per second from one IP. Telephony methods /api/telephony/* cannot address more than 40 requests per second from one IP. In the case of a higher load, API will respond with:
HTTP/1.1 503 Service Temporarily Unavailable
Paginated response / Pagination
Pagination is available in requests with a potentially large response that is broken down into chunks.
In addition to the response itself, these requests contain meta information about pagination:
{
"success": true,
"pagination": {
"limit" =>20,
"totalCount" =>1583,
"currentPage" =>1,
"totalPageCount" =>80
},
// data
}Pagination meta information includes:
limit - the number of items in the current response
totalCount - total number of elements
currentPage - current page
totalPageCount - total number of pages with the response
If the response consists of more than one page, the GET parameter page is available in the request (by default it is equal to 1).