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": {
"contragentType":"legal-entity",
"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",
"corrAccount":"30101810200000000555",
"bankAccount":"40702810400000041213"
}
}
}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:
/api/v4/orders
/api/v4/customers
/api/v4/orders/packs
/api/v4/store/inventories
/api/v4/users
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.