Differences between API v4 and v3
Copy the link to the article

The version v4 is deprecated deprecated and is not recommended for use.

Differences from v3

1. Legal entity properties in customer and order were moved to "contragent" object

In the methods of working with customers /api/v4/customers* and orders /api/v4/orders*, the details of the legal entity are specified in the nested object contragent.

Example for the customer:

 "customer": {
 "contragent": {
 "contragentType": "individual"

Example for order:

 "order": {
 "contragent": {
 "legalName": "Success LLC",
  "legalAddress": "125481, Russian Federation, Moscow, Fomicheva st., 18",
  "INN": "7713252121",
  "OKPO": "49330762",
  "KPP": "772301001",
  "OGRN": "1157346898831",
  "BIK": "044525355",
  "bank": "in PJSC \ u0022Promsvyazbank \ u0022",
  "bankAddress": "Moscow",

2. Delivery time is formalized

In the methods of working with orders /api/v4/orders*, the delivery time has moved from order[delivery][address][deliveryTime] to order[delivery][time] and is set not by a string, but by a structure.

If you need to pass a time range:

 "delivery": {
 "time": {
 "from": "13:00",
 "to": "18:00"

If you need to pass the exact time:

 "delivery": {
 "time": {
 "from": "13:30",
 "to": "13:30"

If you need to transfer unformalized time:

 "delivery": {
 "time": {
 "custom": "after lunch"

3. The customerId field has been removed from the order creation method /api/v4/orders/create

To bind an order to a customer, instead of order[customerId], you now need to specify order[customer][id] ''(binding by internal customer ID)'', order[customer][externalId] ''(binding by external customer ID)'' or order[customer][browserId] ''(binding by customer ID in Collector)''.

4. Changing order filter by customer ID in /api/v4/orders

In the /api/v4/orders method, the filter on external customer ID filter[customerId] has been removed. Instead, a filter by internal customer ID filter[customerId] and a filter by external customer ID filter[customerExternalId] have been added.

5. The method /api/v4/store/products has been added

The /api/v4/store/products method can be used to get a list of products with SKUs according to the filter.

6. The productId, offerId, xmlId fields have been removed from the methods of order creation and editing

To bind a trade offer to an order, instead of order[items][][productId], order[items][][offerId] and order[items][][xmlId], you must specify one of the following fields: order[items][][offer][id] ''(internal ID of SKU)" order[items][][offer][externalId] ''(external ID of a product or SKU)'', order[items][][offer][xmlId] '' (SKU ID in the warehouse system)''.

7. Methods for working with users

3 methods for working with users have been added:

/api/v4/user-groups - getting a list of user groups

/api/v4/users - getting a list of users

/api/v4/users/{id} - getting information about the user

8. Changes in methods of working with telephony

The method of editing telephony settings has changed the address to /api/v4/telephony/setting/{code}/edit, while the data to be sent is wrapped in the configuration object

The method for receiving current telephony settings /api/v4/telephony/setting/{code} has been added

In the above-mentioned methods, the following properties have appeared: additionalCodes ''(extension codes assigned to managers)'', externalPhones ''(assigning external numbers to stores)'', allowEdit ''(whether or not to change the settings via the system interface)'', inputEventSupported '' (specifying that telephony notifies the system of an incoming call) '', outputEventSupported '' (specifying that telephony notifies the system about outgoing call) '', hangupEventSupported '' (specifying that telephony notifies the system about the end of the call) '', changeUserStatusUrl '' (the address where the system will inform telephony about the change of the manager's status)".

In method /api/v4/telephony/call/event:

The data is wrapped in an object event

Field code has been replaced with codes and has become an array (you can notify several managers about an incoming call)

The webAnalyticsData object has appeared to transfer web analytics data

The property callExternalId has appeared to transfer the external ID of the call.

9. Methods for registering a warehouse system

2 methods have been added:

/api/v4/store/setting/{code}/edit - registration and specifying the configuration of the warehouse system

/api/v4/store/setting/{code} - getting the current configuration of the warehouse system

10. Methods for integration with a delivery service

Methods for integrating delivery service have been added:

/api/v4/delivery/generic/setting/{subcode}/edit - registration and specifying the configuration of the delivery service

/api/v4/delivery/generic/setting/{subcode} - getting the current configuration of the delivery service

/api/v4/delivery/generic/{subcode}/tracking - updating delivery statuses

11. Multiple filters by references in list methods

The changes affected the following methods:






In these methods, filters by fields of the Data book type have become multiple.

It was:

https://demo.retailcrm.ru/api/v3/orders?filter [orderMethod ]=shopping-cart&apiKey=23fawef5e34fadgaw432da

It became:

https://demo.retailcrm.ru/api/v4/orders?filter [orderMethods [[] ]=shopping-cart&filter [orderMethods] [[]=phone&apiKey=23fawef5e34fadgaw432da

12. The method of order editing no longer creates an order if it is missing

The /api/v3/orders/{externalId}/edit method creates an order if it does not exist in the system database. The new method /api/v4/orders/{externalId}/edit, if there is no order in the database, returns a 404 error with information that the order was not found.

13. The method /api/v4/customers/history has been added

The /api/v4/customers/history method allows you to get an incremental history of customer changes. More information about working with methods of history.

14. Changing the behavior of the history method /api/v4/orders/history

In the method of the previous version /api/v3/orders/history, the history was given, grouped by orders, due to which repeated changes of the same field were merged into the last change. The /api/v4/orders/history method, on the other hand, gives an incremental history of order changes, where each change is represented by a separate record in the history. More information about working with history methods.

Thank you for your feedback.
Was this article helpful?
  • Рекомендации не помогли
  • Нет ответа на мой вопрос
  • Текст трудно понять
  • Не нравится описанный функционал
Previous article
Differences between API v5 and v4
The article describes new methods and extensions that are available in API v5.