• View
• Edit
• History
• Print

API rules

1. Scheme
2. Authorization
3. GET requests
4. POST requests
5. API handling rate
6. Response pagination
7. Error messages

This API is intended to interaction with system from the side of website server, online store, the mobile application or integration module. For interaction with the system by Javascript use Daemon Collector.

Scheme

When working with API should be used v5 version. Previous versions of API are deprecated and are not recommended to use. You may find more information on versions and their difference in separate article. Requests should be sent to:

https://{your-subdomain}.retailcrm.pro/api/{version}/
  or
https://{your-subdomain}.retailcrm.es/api/{version}/

All requests will be accepted only through https in charset UTF-8. The answer is formed in JSON-format.

Data type «Date» are specified in the format Y-m-d (for example 2014-03-21), data type «Date/time» are specified in the format Y-m-d H:i:s (for example 2014-03-21 05:14:07).

Authorization

Authorization is performed by API-key, which is transmitted in GET|POST-parameter apiKey:

https://demo.retailcrm.pro/api/v5/orders?apiKey=X2EDxEta9U3lcsSV0dwdF38UvtSCxIuGh

In administrative section of system you may find subsection API keys management. In case of absence of API-key or if the key is wrong, API reports an error.

If API-key gives access to data of several stores, then in some API-methods addirionally required specify symbolic code of store in GET|POST-parameter site. In reference book you may see which methods require specify store.

GET requests

When accessing the API-methods using GET, the parameters must be sent in the format GET parameters.

Example of transmitted data:

https://demo.retailcrm.pro/api/v5/orders?filter[numbers][]=1235C&filter[customFields][nps][min]=5&apiKey=X2EDxEta9U3lcsSV0dwdF38UvtSCxIuGh

POST requests

When accessing the API-methods using POST, the parameters must be sent in the format application/x-www-form-urlencoded. Herewith if the nested structure is passed in any of the parameters (for example, order data in the parameter order in method /api/v*/orders/create), then the value of these parameters must be sent as a JSON-string.

Example of transmitted data:

site=simple-site&order=%7B%22externalId%22%3A%22a123%22%2C%22firstName%22%3A%22Tom%22%7D

API handling rate

When referring to API it is allowed to handle not more often than 10 requests per second from a single IP. It is allowed to refer telephony methods /api/telephony/* not more often than 40 requests per second. In case of high load API will return answer:

HTTP/1.1 503 Service Temporarily Unavailable

Response pagination

Response pagination available in requests with potentially large answer, which will be divide by portions.

In these requests in addition to the response is present meta-information about pagination:

HTTP/1.1 200 OK
{ 
    "success": true, 
    "pagination": {
        "limit" => 20,
        "totalCount" => 1583,
        "currentPage" => 1,
        "totalPageCount" => 80
    },
    // data
}

Meta-information about pagination includes:

• limit — number of elements in current response
• totalCount — total number of elements
• currentPage — current page
• totalPageCount — total number of pages with repsonse

If answer consists of more than one page, GET-параметр page (1 by default) is available in request.

Error messages

When handling to API the errors may occur, and the system will report about it. Possible types of errors:

1) Not specified apiKey:

HTTP/1.1 403 Forbidden
{ 
    "errorMsg": "\u0022apiKey\u0022 is missing.", 
    "success": false 
}

2) Wrong apiKey:

HTTP/1.1 403 Forbidden
{ 
    "errorMsg": "Wrong \u0022apiKey\u0022 value.", 
    "success": false 
}

3) Access to API restricted by IP.

HTTP/1.1 403 Forbidden
{
    "success": false,
    "errorMsg": "Forbidden"
}

4) System account not found

HTTP/1.1 404 Not found
{
    "success": false,
    "errorMsg": "Account does not exist."
}

5) Error on server

HTTP/1.1 503 Service Unavailable
{
    "success": false,
    "errorMsg": "Service overloaded."
}

or

HTTP/1.1 500  Internal Server Error
{
    "success": false,
    "errorMsg": "Application error"
}

6) Incorrect data in request parameters

HTTP/1.1 400 Bad request
{
    "success": false,
    "errorMsg": "Invalid request: Errors in the input parameters",
    "errors": {
        "children[deliveryType]": "This value is not valid."
    }
}

7) Incorrect data in some elements of incoming data array (for example, orders array)

HTTP/1.1 460 Bad request
{
    "success": false,
    "uploadedOrders": [],
    "errorMsg": "Orders are loaded with errors",
    "errors": [
        "Order with externalId=4414145 already exists.",
        "OrderType with code 'some-code' not found. Order externalId=44141452"
    ]
}