V5 is the current API version. When working with API, you must use it.
Differences between v4 and v5
1. The appearance of the method /api/v5/users/{id}/status
This method changes the user's status in the system. It allows you to synchronise the user's status with an external system (for example, telephony).
2 . The appearance of the method for obtaining the list of segments /api/v5/segments
This method returns a list of segments. It allows you to synchronise customer segments with an external system.
3 . The appearance of methods to combine customers and combine orders
Added methods /api/v5/customers/combine and /api/v5/orders/combine.
The /api/v5/customers/combine method allows you to combine several customers into one. In case of a conflict of fields, the data of the end customer will be saved. Accordingly, if the data you need is in the list of customers to be deleted, then you must first transfer it to the main customer.
The /api/v5/orders/combine method allows you to combine two orders. In this case, the data of the final order will be saved, and the content will be combined in accordance with the specified strategy.
4. The appearance of the method /api/v5/store/product-groups
This method returns a list of groups of catalogue products.
5. The appearance of methods for working with custom fields
4 methods for working with custom fields have been added:
/api/v5/custom-fields - getting a list of custom fields
/api/v5/custom-fields/{entity}/create - creating a custom field
/api/v5/custom-fields/{entity}/{code} - getting information about a custom field
/api/v5/custom-fields/{entity}/{code}/edit - editing a custom field
4 methods for working with custom data books have been added:
/api/v5/custom-fields/dictionaries - getting a list of custom data books
/api/v5/custom-fields/dictionaries/create - creating a custom data book
/api/v5/custom-fields/dictionaries/{code} - getting information about a custom data book
/api/v5/custom-fields/dictionaries/{code}/edit - editing a custom data book
6 . Field with a collection of images in a product
In the /api/v5/store/products method, the products[][offers][][images][] field is available with a collection of images attached to the trade offer.
7 . "Gender" field in the customer card
In the /api/v5/customers* methods, the customer[sex] field is available with the values male|female. The field is available both for writing and reading. Also in the customer list method, a filter is available on this field.
8. The appearance of methods for working with tasks
4 methods for working with tasks have been added:
/api/v5/tasks - getting a list of tasks
/api/v5/tasks/create - creating a task
/api/v5/tasks/{id} - getting information about a task
/api/v5/tasks/{id}/edit - editing a task
9. Changing the content of payment fields in the order
The following fields in the /api/v5/orders* methods have been removed:
order[paymentType]
order[paymentStatus]
order[paymentDetail]
The following fields have been added to the methods for obtaining order information /api/v5/orders and /api/v5/orders/get:
Payment collection order[payments][]
Date of full payment order[fullPaidAt]
10. The appearance of methods for creating and editing payments
3 methods for working with order payments have been added:
/api/v5/orders/payments/create - adding a payment
/api/v5/orders/payments/{id}/edit - editing a payment
/api/v5/orders/payments/{id}/delete - deleting a payment
11. The appearance of the VAT rate for products in the order
The following fields have been added to the methods for getting information about the order /api/v5/orders and /api/v5/orders/get:
VAT rate for item in order order[items][][vatRate]
VAT rate for a product in order order[items][][offer][vatRate]
In the methods for creating /api/v5/orders/create and editing /api/v5/orders/{externalId}/edit an order for each item, you can specify an individual VAT rate order[items][][vatRate].
12. Adding methods for working with customer notes and deleting the customer[commentary] field
Notes have replaced the Comment field in the Customer entity. Therefore, the customer[commentary] field has been deleted from the methods for working with the customer.
Also 3 methods for working with customer notes have been added:
/api/v5/customers/notes - getting a list of notes
/api/v5/customers/notes/create - adding a note
/api/v5/customers/notes/{id}/delete - deleting a note
13. Changing the work with order discounts
The fields order[discount], order[discountPercent], order[items][][discount], order[items][][discountPercent] have been removed in all methods of working with orders.
In the methods for creating and editing the order /api/v5/orders/create, /api/v5/orders/{externalId}/edit, /api/v5/orders/upload, you can transfer order discounts and products in the fields order[discountManualAmount], order[discountManualAmount], order[discountManualAmount], order[discountManualAmount], /api/v5/orders/{externalId}/edit order[items][][discountManualPercent], while order discounts will be distributed among the products.
The methods for getting orders /api/v5/orders, /api/v5/orders/{externalId} return the total monetary discount per product unit for each product item in the field order[items][][discountTotal], which takes into account both the discounts on the current order and the order discounts distributed among products.
It should be noted that there may be cases when discounts for an order cannot be divided between products (for example, one product item in the amount of 3 pieces is transferred in an order, as well as a discount for an order of 1000 euros). If such a case occurs, then an error will be shown. To avoid this, we added a setting, when enabled, the system will automatically determine the closest discount for an order, which will allow it to be divided between products.
14. Field with groups in the product
In the /api/v5/store/products method, the products[][groups][] field is available with the ID of the product groups to which the product belongs.
15. Reference book of product properties and filtering products by properties
The /api/v5/store/products/properties method has been added to get a list of properties that are used in the catalog. In addition, in the /api/v5/store/products method, the filter[properties][] filter has been added, which makes it possible to select products with specified values of certain properties.
16. Methods for making a request for the pick-up of products by the delivery service
4 API methods have been added:
GET /api/v5/delivery/shipments - getting a list of shipments to delivery services
POST /api/v5/delivery/shipments/create - creating a shipment
GET /api/v5/delivery/shipments/{id} - getting information about a shipment
POST /api/v5/delivery/shipments/{id}/edit - editing a shipment
And also 2 callback methods:
POST {integrationModule["baseUrl"]}/{configuration["actions"]["shipmentSave"]} - creating and editing a request for shipment
POST {integrationModule["baseUrl"]}/{configuration["actions"]["shipmentDelete»]} - deleting a request for shipment
Read more in the article about API of delivery services.
17 . Changing the methods of module registration
The old methods of registering modules and getting information about a module have been removed, namely:
/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
/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/marketplace/external/setting/{code}/edit - registration of the integration module with the marketplace platform
/api/v4/telephony/setting/{code}/edit - creating/editing the configuration of the telephony module
/api/v4/telephony/setting/{code} - getting the current configuration of the telephony module
Instead of them, 2 uniform methods for registering a module have been introduced:
/api/v5/integration-modules/{code}/edit - creating/editing the parameters of the integration module
/api/v5/integration-modules/{code} - getting the parameters of the integration module
Within these methods, you can also pass the specific settings of the certain modules.
A callback method was also introduced:
{integrationModule["baseUrl"]}/{integrationModule["actions"]["activity"]} - called when the module is enabled/disabled by the user in the system.
18. Methods for working with couriers
3 API methods have been added:
GET /api/v5/reference/couriers - list of couriers created in the system
POST /api/v5/reference/couriers/create - creating a courier
POST /api/v5/reference/couriers/{id}/edit - editing a courier
19. Information about segments in API methods for getting customer information
In API methods for obtaining information about customers, data about the segments to which they belong is available:
GET /api/v5/customers - in the field customers[][segments]
POST /api/v5/customers/{externalId} - in the field customer[segments]
20. Reference book for units of measurement
2 API methods for working with units of measurement have been added:
GET /api/v5/reference/units - getting information about the units of measurement in the system
POST /api/v5/reference/units/{code}/edit - creating and editing the units of measurement
In addition, information on units of measurement is available in the following methods:
GET /api/v5/store/products - field products[][offers][][unit]
POST {integrationModule["baseUrl"]}/{configuration["actions"]["save"]} - field save[packages][][items][][unit]
GET /api/v5/orders - field orders[items][][offer][unit]
GET /api/v5/orders/{externalId} - field order[items][][offer][unit]
GET /api/v5/orders/packs - field packs[unit]
GET /api/v5/orders/packs/{id} - field pack[unit]
21 . The appearance of coordinates for warehouses
In the /api/v5/reference/stores* method, the fields store[address][coordinates][latitude] and store[address][coordinates][longitude] are available (the fields with latitude and longitude, respectively). The fields are available for both writing and reading.
22 . The appearance of methods of working with files
The possibility to work with files attached to orders or customers has been added. 6 methods for working with files have been added:
/api/v5/files - getting a list of files
/api/v5/files/{id} - getting information about a specific file
/api/v5/files/{id}/download - downloading the file uploaded to the system
/api/v5/files/upload - uploading a file to the system
/api/v5/files/{id}/edit - editing the file name and editing the file binding to orders and customers
/api/v5/files/{id}/delete - deleting a file from the system
23 . The appearence of methods for working with corporate customers
The possibility of working with corporate customers and 20 new methods have been added:
/api/v5/customers-corporate - getting a list of corporate customers that match the specified filter
/api/v5/customers-corporate/combine - combining corporate customers
/api/v5/customers-corporate/create - creating a corporate customer
/api/v5/customers-corporate/fix-external-ids - adding external IDs of corporate customers in large numbers
/api/v5/customers-corporate/history - getting the history of changes of corporate customer
/api/v5/customers-corporate/notes - getting notes
/api/v5/customers-corporate/notes/create - creating a note
/api/v5/customers-corporate/notes/{id}/delete - deleting a note
/api/v5/customers-corporate/upload - uploading a large number of corporate customers
/api/v5/customers-corporate/{externalId} - getting information about a corporate customer
/api/v5/customers-corporate/{externalId}/addresses - a list of addresses of a corporate customer
/api/v5/customers-corporate/{externalId}/addresses/create - creating an address for a corporate customer
/api/v5/customers-corporate/{externalId}/addresses/{entityExternalId}/edit - editing the address of a corporate customer
/api/v5/customers-corporate/{externalId}/companies - a list of companies of the corporate customer
/api/v5/customers-corporate/{externalId}/companies/create - creating a company for a corporate customer
/api/v5/customers-corporate/{externalId}/companies/{entityExternalId}/edit - editing a company of the corporate customer
/api/v5/customers-corporate/{externalId}/contacts - a list of contact persons of the corporate customer
/api/v5/customers-corporate/{externalId}/contacts/create - creating a connection between the corporate customer and the contact person
/api/v5/customers-corporate/{externalId}/contacts/{entityExternalId}/edit - editing the connection between the corporate customer and the contact person
/api/v5/customers-corporate/{externalId}/edit - editing the corporate customer
To the methods of creating/editing orders and uploading them in large numbers /api/v5/orders/create, /api/v5/orders/upload, /api/v5/orders/{externalId}/edit have been added the following fields:
order[customer][type] - customer type, by default is customer. To create an order for a corporate customer, in field it is necessary to pass customer_corporate
order[customer][nickName] - the name of the contractor, passed when a new corporate customer needs to be created
order[contact] - a set of data to be inserted into the order of a contact person, used if the order is placed on a corporate customer
order[company] - a set of data to be substituted into the company's order, used if the order is placed on a corporate customer
The following fields have been added to the methods for getting the list and getting information about the order /api/v5/orders, /api/v5/orders/{externalId}:
order[customer][type] - type of customer for whom the order is placed
order[contact] - contact person of the order
order[company] - order company
The order for the corporate customer can be created only if the corporate customers’ functionality is enabled in the system.
Customers do not have the fields of the contractor anymore. The fields exist only in compatibility mode for the systems which did not activate the work with the corporate customers. Among these fields there are the following ones:
In the method for getting the list of customers /api/v5/customers:
filter[contragentName]
filter[contragentTypes][]
filter[contragentInn]
filter[contragentKpp]
filter[contragentBik]
filter[contragentCorrAccount]
filter[contragentBankAccount]
customers[][contragent]
In the methods for creating, editing, mass uploading and getting information about the customer: /api/v5/customers/create, /api/v5/customers/{externalId}/edit, /api/v5/customers/upload, /api/v5/customers/{externalId}:
customers[][contragent]
When activating work with corporate customers, if the system already has customers with filled in contractor data, migration is performed to convert these customers into corporate customers. These customers will no longer be available via the api/v5/customers/* methods, but their past history can still be got via the /api/v5/customers/history method. After completing the migration, a new entry will be added to the customer (to this history) where field will have the value type, oldValue - customer, newValue - customer_corporate. Thus, it will be possible to find out which of the customers were converted into corporate customers. When converting, id and externalId will be saved. You can learn more about the migration process in the documentation on working with the corporate customers.