Version v5
is a relevant at the moment. When working with API, you should use this version.
/api/v5/users/{id}/status
This method changes user's status in the system. Allows to synchronize the user's status with external system (for example, telephony).
/api/v5/segments
for getting the segment listThis method returns the segment list. Allows to synchronize customer segments with external system.
Methods /api/v5/customers/combine
and /api/v5/orders/combine
have been added.
Method /api/v5/customers/combine
allows to combine several customers into one. At the conflict of fields, the data of the last customer will be saved. Thus, if the data you need is in the customers you are going to delete, it is necessary to transfer it to the main customer.
Method /api/v5/orders/combine
allows to combine 2 orders. At the same time, the data of the last order will be saved and the content will be combined according to the specified strategy.
/api/v5/store/product-groups
This method returns the list of product groups in catalogues.
Four methods for working with custom fields have been added:
/api/v5/custom-fields
– getting the list of custom fields
/api/v5/custom-fields/{entity}/create
– creation of 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
Four methods for working with custom reference books have been added:
/api/v5/custom-fields/dictionaries
– getting the list of custom reference books
/api/v5/custom-fields/dictionaries/create
– creation of a custom reference book
/api/v5/custom-fields/dictionaries/{code}
– getting information about a custom reference book
/api/v5/custom-fields/dictionaries/{code}/edit
– editing a custom reference book
Field products[][offers][][images][]
with collection of images attached to the trade offer is available in method /api/v5/store/products
.
Field customer[sex]
with values male|female
is available in methods /api/v5/customers*
. The field is available for both writing and reading. Also, filter on this field is available in the method of customer list.
Four methods for working with tasks have been added:
/api/v5/tasks
– getting the list of tasks
/api/v5/tasks/create
– creation of a task
/api/v5/tasks/{id}
– getting information about a task
/api/v5/tasks/{id}/edit
– editing a task
The following fields have been removed in methods /api/v5/orders*
:
order[paymentType]
order[paymentStatus]
order[paymentDetail]
The following fields have been added to methods for getting information about the order /api/v5/orders
and /api/v5/orders/get
:
order[payments][]
order[fullPaidAt]
In details about changes in payment of orders.
Three methods have been added for working with payments of the order:
/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
In details about changes in payment of orders.
The following fields have been added to methods for getting information about the order /api/v5/orders
and /api/v5/orders/get
:
order[items][][vatRate]
order[items][][offer][vatRate]
In methods for order creation /api/v5/orders/create
and editing /api/v5/orders/{externalId}/edit
it is possible to specify an individual VAT rate order[items][][vatRate]
for each line item.
customer[commentary]
Notes have replaced the Comment field in the Customer object. Therefore, in methods for working with the customer, has been deleted the field customer[commentary]
.
Three methods for working with notes on the customer have been added:
/api/v5/customers/notes
– getting the list of notes
/api/v5/customers/notes/create
– adding a note
/api/v5/customers/notes/{id}/delete
– deleting a note
Fields order[discount]
, order[discountPercent]
, order[items][][discount]
, order[items][][discountPercent]
have been removed in all methods for working with orders.
In methods for order creation and editing /api/v5/orders/create
, /api/v5/orders/{externalId}/edit
, /api/v5/orders/upload
it is possible to transfer discounts for the order and goods in the fields order[discountManualAmount]
, order[discountManualPercent]
, order[items][][discountManualAmount]
, order[items][][discountManualPercent]
. Discounts for the order, in this case, will be distributed between goods.
Total monetary discount for a product unit for each line item of the good in the field order[items][][discountTotal]
has been returned in methods for getting orders /api/v5/orders
, /api/v5/orders/{externalId}
. It also includes discounts for a current product and discounts for an order, distributed between goods.
It should be noted that there are cases when discounts for the order can not be distributed between goods (for example, one line item of a product is transferred in amount of 3 pieces to the order and discount for the order of 100 euros). If this happens, error will be shown. To avoid this, we have added a setting; when it is enabled, the system will determine the closest amount of a discount for an order that will allow to divide the amount between goods.
In details about work with discounts.
Field products[][groups][]
with ID of product groups to which a product belongs, is available in method /api/v5/store/products
.
There has been added a method /api/v5/store/products/properties
allowing to receive the list of properties used in the catalog. Besides, filter filter[properties][]
giving chance to choose goods with specified values of certain properties, has been added to method /api/v5/store/products
.
Four API methods have been added:
GET /api/v5/delivery/shipments
– getting a list of shipments to delivery services
POST /api/v5/delivery/shipments/create
– shipment creation
GET /api/v5/delivery/shipments/{id}
– getting information about the shipment
POST /api/v5/delivery/shipments/{id}/edit
– editing the shipment
Two callback methods have also been added:
POST {integrationModule["baseUrl"]}/{configuration["actions"]["shipmentSave"]}
– creating and editing a request for shipment
POST {integrationModule["baseUrl"]}/{configuration["actions"]["shipmentDelete»]}
– deleting the request for shipment
In details about API of delivery services.
Deprecated methods for module registration and getting information about the module have been removed:
/api/v4/store/setting/{code}/edit
– registration and specifying a configuration of warehouse system
/api/v4/store/setting/{code}
– getting the current configuration of warehouse system
/api/v4/delivery/generic/setting/{subcode}/edit
– registration and specifying a configuration of delivery service
/api/v4/delivery/generic/setting/{subcode}
– getting the current configuration of delivery service
/api/v4/marketplace/external/setting/{code}/edit
– registration of integration module with marketplace
/api/v4/telephony/setting/{code}/edit
– creating / editing a configuration of telephony module
/api/v4/telephony/setting/{code}
– getting the current configuration of telephony module
2 standard methods have been added for the module registration:
/api/v5/integration-modules/{code}/edit
– creating / editing parameters of integration module
/api/v5/integration-modules/{code}
– getting the parameters of integration module
Using the above-mentioned methods, it is possible to transfer specific settings of certain module types.
Callback method has also been added:
{integrationModule["baseUrl"]}/{integrationModule["actions"]["activity"]}
– is called when enabling / disabling the module by the user in the system.
Three 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 the courier
Data on segments to which customers belong is available in API methods for getting customer information:
GET /api/v5/customers
– in field customers[][segments]
POST /api/v5/customers/{externalId}
– in field customer[segments]
Two API methods have been added to work with units of measurement:
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
Also, information about the 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]
Fields store[address][coordinates][latitude]
and store[address][coordinates][longitude]
with latitude and longitude respectively are available in method /api/v5/reference/stores*
. The fields are available both for writing and reading.
Possibility of working with files attached to orders or customers has been added. 6 methods for working with files:
/api/v5/files
– getting a list of files
/api/v5/files/{id}
– getting information about the specific file
/api/v5/files/{id}/download
– downloading the file uploaded to the system
/api/v5/files/upload
– uploading the file to the system
/api/v5/files/{id}/edit
– editing the file name and the file binding to orders and customers
/api/v5/files/{id}/delete
– deleting the file from the system
Possibility of working with corporate customers and 20 new methods have been added:
/api/v5/customers-corporate
- getting a list of corporate customers according to the selected filters;
/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 a history of changes of corporate customers
/api/v5/customers-corporate/notes
- getting notes
/api/v5/customers-corporate/notes/create
- creating a note
/api/v5/customers-corporate/notes/{id}/delete
- deleting the note
/api/v5/customers-corporate/upload
- uploading a large number of corporate customers
/api/v5/customers-corporate/{externalId}
- getting information about the corporate customer
/api/v5/customers-corporate/{externalId}/addresses
- a list of addresses of the corporate customer
/api/v5/customers-corporate/{externalId}/addresses/create
- creating an address for the corporate customer
/api/v5/customers-corporate/{externalId}/addresses/{entityExternalId}/edit
- editing the address of the 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 the corporate customer
/api/v5/customers-corporate/{externalId}/companies/{entityExternalId}/edit
- editing the 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
The following fields have been added 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
):
order[customer][type]
is a customer type; customer
is by default. To create an order for the corporate customer, pass customer_corporate in this field;
order[customer][nickName]
is a contractor type. It is transferred when it’s required to create a new corporate customer;
order[contact]
is a data array to add a contact person to the order. It is used if the order is created for the corporate customer
order[company]
is a data array to add a company to the order. It is used if the order is created for the corporate customer.
The following fields have been added to the methods for getting lists and information about the order (/api/v5/orders
, /api/v5/orders/{externalId
):
order[customer][type]
- type of the customer for whom the order was created
order[contact]
- contact person of the order
order[company]
- company of the order
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:
api/v5/customers
:
filter[contragentName]
filter[contragentTypes][]
filter[contragentInn]
filter[contragentKpp]
filter[contragentBik]
filter[contragentCorrAccount]
filter[contragentBankAccount]
customers[][contragent]
/api/v5/customers/create
, /api/v5/customers/{externalId}/edit
, /api/v5/customers/upload
, /api/v5/customers/{externalId}
:
customers[][contragent]
If the corporate customers’ functionality is enabled and there are customers with the completed data of the contractor in the system, then the migration on converting these customers to the corporate customers will be started. These customers will not be available via methods api/v5/customers/*
but their history of changes will remain available via the method /api/v5/customers/history
.
After the migration is completed, a new entry will be added to the customer: field
will have the type
value, oldValue
will have the customer
value and newValue will have the customer_corporate
value.
Thus, it will be possible to know which customers were converted to the corporate customers. ID and externalID will be saved while converting. Details about the migration process are described in the documentation on working with the corporate customers.
Version v4
is in status deprecated
at the moment and not recommended for usage.
In methods of working with customers /api/v4/customers*
and orders /api/v4/orders*
legal entity details are being specified in nested object contragent
.
Example for customer:
{
"customer": {
//...
"contragent": {
"contragentType": "individual"
}
}
}
Example for order:
{
"order": {
//...
"contragent": {
"contragentType":"legal-entity",
"legalName":"Success LLC",
"legalAddress":"125481, Russia, Moscow, Fomichevoy str., 18",
"INN":"7713252121",
"OKPO":"49330762",
"KPP":"772301001",
"OGRN":"1157346898831",
"BIK":"044525355",
"bank":"\u0022Promsvyazbank\u0022",
"bankAddress":"Moscow",
"corrAccount":"30101810200000000555",
"bankAccount":"40702810400000041213"
}
}
}
In methods of working with orders /api/v4/orders*
delivery time was moved from order[delivery][address][deliveryTime]
to order[delivery][time]
and is specified not as row but as structure.
If you need to transfer time range:
order={
//...
"delivery": {
//...
"time": {
"from": "13:00",
"to": "18:00"
}
}
}
If you need to transfer exact time:
order={
//...
"delivery": {
//...
"time": {
"from": "13:30",
"to": "13:30"
}
}
}
If you need to transfer non-formalized time:
order={
//...
"delivery": {
//...
"time": {
"custom": "after lunch"
}
}
}
customerId
was removed from order creation method /api/v4/orders/create
Now for binding the order to customer instead of order[customerId]
you should specify order[customer][id]
(binding by customer internal ID), order[customer][externalId]
(binding by customer external ID) или order[customer][browserId]
(binding by customer ID in Collector).
/api/v4/orders
In /api/v4/orders
method the filter by customer external ID filter[customerId]
was removed. Instead of it the filter by customer internal ID filter[customerId]
and the filter by customer external ID filter[customerExternalId]
were added.
/api/v4/store/products
method was added/api/v4/store/products
method can be used for getting the item list with SKU according to filter.
For binding the offer to order instead of order[items][][productId]
, order[items][][offerId]
and order[items][][xmlId]
you need to specify one of the following fields: order[items][][offer][id]
(SKU internal ID), order[items][][offer][externalId]
(item or SKU external ID), order[items][][offer][xmlId]
(SKU ID in warehouse system).
3 methods of working with users were added:
/api/v4/user-groups
– getting the list of user groups
/api/v4/users
– getting the list of users
/api/v4/users/{id}
– getting the information on user
/api/v4/telephony/setting/{code}/edit
, at the same time the data are wrapped in configuration
object
/api/v4/telephony/setting/{code}
method of getting the current settings of telephony was added
additionalCodes
(extension numbers assigned to managers), externalPhones
(binding external phone numbers with the shops), allowEdit
(allow or not allow to edit the settings through system interface), inputEventSupported
(indication that telephony informs the system about incoming call), outputEventSupported
(indication that telephony informs the system about outgoing call), hangupEventSupported
(indication that telephony informs the system about call finishing), changeUserStatusUrl
(address, to which the system will inform telephony about the manager status change).
/api/v4/telephony/call/event
method:
event
object
code
field has been replaced with codes
and has become an array (several managers can be notified about the incoming call)
webAnalyticsData
object for transferring data of web analytics
callExternalId
property for transferring the call external ID
There are 2 methods:
/api/v4/store/setting/{code}/edit
– registration and specifying of warehouse system configuration
/api/v4/store/setting/{code}
– getting the current configuration of warehouse system
Methods for delivery service integration are added:
/api/v4/delivery/generic/setting/{subcode}/edit
– registration and specifying of delivery service configuration
/api/v4/delivery/generic/setting/{subcode}
– getting the current configuration of delivery service
/api/v4/delivery/generic/{subcode}/tracking
– delivery statuses updating
Changes have been applied to the following methods:
/api/v4/orders
/api/v4/customers
/api/v4/orders/packs
/api/v4/store/inventories
/api/v4/users
Filters by Directory field type in these methods have become multiple.
It was:
https://demo.retailcrm.ru/api/v3/orders?filter[orderMethod]=shopping-cart&apiKey=23fawef5e34fadgaw432da
Now:
https://demo.retailcrm.ru/api/v4/orders?filter[orderMethods][]=shopping-cart&filter[orderMethods][]=phone&apiKey=23fawef5e34fadgaw432da
Method /api/v3/orders/{externalId}/edit
creates the order if there is no such in system database. New method /api/v4/orders/{externalId}/edit
returns 404 error with information that order is not found in case of order absence.
/api/v4/customers/history
is addedMethod /api/v4/customers/history
allows to get incremental history of customer changes. Read more detailed information on working with history methods.
/api/v4/orders/history
history method behaviorIn method /api/v3/orders/history
of previous version the history was returned grouping by orders, so that repeated changes of the same field were bound in last change. Method /api/v4/orders/history
returns incremental information on the order change history, where each change is the separate entry in history. Read more detailed information on working with history methods.
Version v3
is in status deprecated
at the moment and forbidden for usage.
Version v2
is not supported anymore and cannot be used.
Version v1
is not supported anymore and cannot be used.