General principles of API integration
- All Retail Rocket APIs are available via HTTP/2;
- If a method call requires data to be passed in the request body, the system expects it in JSON format and the corresponding http header: content-type: application/json;
- All data returned as a result of a call is returned in JSON format;
- HTTP response statuses matter. Possible method statuses are described in its documentation;
- In order to optimize the speed of connection and data transfer, the connection should be cached;
- When sending events, you do not need to wait for a response, the only exception is the batch loading of events, the details of which are described in the corresponding section;
- Important: when using API methods in real applications/systems, it is imperative to take into account the possibility of API failure. It is necessary to request data asynchronously, with a maximum waiting time of 500ms. It is imperative to provide a fallback scenario in which the application/system should continue to work normally, even if the API method did not respond or responded with an error;
Online store identifier
To identify an online store in the API, the partnerId parameter is used. The value of the parameter is issued upon registration in the Retail Rocket system and can be obtained either by a request to a Retail Rocket account manager, or by contacting the support service (support@retailrocket.net), or in your Retail Rocket account.
The value is public and can be used in the open form.
Authorization
Access to some API methods is limited, and to use them you need to pass the apiKey parameter, the value of which can be obtained from a Retail Rocket employee.
- The apiKey value is secret and should not be transferred to third parties or stored on the client side (on a website or in a mobile application).
- In case of leakage of the apiKey value, you should request a new one from your account manager. The old value will no longer be valid.
Store the apiKey value in a storage where it can be changed without having to release a new version of the site/application.
Call timestamp
For the correct operation of many Retail Rocket products, it is necessary to know the time when the method was called, for this, some API methods provide an optional timestamp parameter, in the value of which the Retail Rocket system expects the date and time in ISO 8601 format.
If the optional parameter is not specified, then the Retail Rocket server time at the time of the call will be used as the timestamp.
Product database
If the API method requires product data (for example, product/warehouse ID, etc.), the value of such parameters must match the values transferred with the product base to Retail Rocket.
The product database in Retail Rocket can be transferred in two ways:
- Using an XML feed;
- Using the product API, additionally installed on the product card page, or on the backend of the online store;
Product Information
If the API method requires product data (for example, product/warehouse ID, etc.), the value of such parameters must match the values contained in the product database transferred to Retail Rocket.
Response codes
| Response code | Name | Description |
|---|---|---|
| 200 | OK | Request accepted |
| 204 | NoContent | Nothing found for the request |
| 400 | BadRequest | Error in the request, you need to check the correctness of the request construction |
| 401 | Unauthorized | Authorization error, you need to check the correctness of partnerId, apiKey |
| 403 | Forbidden | Access denied |
| 404 | NotFound | The requested resource was not found, you need to check the correctness of the URL |
| 429 | TooManyRequests | Exceeding the request limit |
Response time and limitations
The request processing time by the Retail Rocket platform is up to 100 ms. The response time may vary due to the peculiarities of the network infrastructure.
By default, there is a limit of 600 requests/second for a site. If necessary, it can be changed (with the help of an account manager).