API versions

Version v5

Version v5 is a relevant at the moment. When working with API, you should use this version.

Difference from v4

1. Appearance of method /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).

2. Appearance of method /api/v5/segments for getting the segment list

This method returns the segment list. Allows to synchronize customer segments with external system.

3. Appearance of methods for combining customers and orders

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.

4. Appearance of method /api/v5/store/product-groups

This method returns the list of product groups in catalogues.

5. Appearance of methods for working with custom fields

Four methods for working with custom fields have been added:

Four methods for working with custom reference books have been added:

6. Field with collection of images in the item

Field products[][offers][][images][] with collection of images attached to the trade offer is available in method /api/v5/store/products.

7. Gender field in the customer

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.

8. Appearance of methods for working with tasks

Four methods for working with tasks have been added:

9. Changes in content of payment fields in the order

The following fields have been removed in methods /api/v5/orders*:

The following fields have been added to methods for getting information about the order /api/v5/orders and /api/v5/orders/get:

In details about changes in payment of orders.

10. Appearance of methods for payment creation and editing

Three methods have been added for working with payments of the order:

In details about changes in payment of orders.

11. Appearance of VAT rate for goods in the order

The following fields have been added to methods for getting information about the order /api/v5/orders and /api/v5/orders/get:

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.

12. Appearance of methods for working with notes on the customer and deleting the field 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:

13. Changes in work with discounts for an order

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.

14. Field with groups in a product

Field products[][groups][] with ID of product groups to which a product belongs, is available in method /api/v5/store/products.

15. Reference book of item properties and filtration of items by properties

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.

16. Methods for request for a pick up by delivery service

Four API methods have been added:

Two callback methods have also been added:

In details about API of delivery services.

17. Changes in methods for module registration

Deprecated methods for module registration and getting information about the module have been removed:

2 standard methods have been added for the module registration:

Using the above-mentioned methods, it is possible to transfer specific settings of certain module types.

Callback method has also been added:

18. Methods for working with couriers

Three API methods have been added:

19. Information about segments in API methods for getting customer information

Data on segments to which customers belong is available in API methods for getting customer information:

20. Reference book for units of measurement

Two API methods have been added to work with units of measurement:

Also, information about the units of measurement is available in the following methods:

21. Appearance of coordinates for warehouses

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.

22. Appearance of methods for working with files

Possibility of working with files attached to orders or customers has been added. 6 methods for working with files:

23. Appearance of methods for working with corporate customers

Possibility of working with corporate customers and 20 new methods have been added:

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):

The following fields have been added to the methods for getting lists and information about the order (/api/v5/orders, /api/v5/orders/{externalId):

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:

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

Version v4 is in status deprecated at the moment and not recommended for usage.

Difference from v3

1. Legal entity details in customer and order are moved to contragent object

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"
        }        
    }
}

2. Formalized order delivery time

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"
        }
    }
}

3. Field 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).

4. Change of orders filter by customer ID in /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.

5. /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.

6. productId, offerId, xmlId were removed from methods of order creation and editing

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).

7. Methods for working with users

3 methods of working with users were added:

8. Changes in methods of working with telephony

9. Methods for warehouse system registration

There are 2 methods:

10. Methods for delivery service integration

Methods for delivery service integration are added:

11. Multiple filters by directories in list methods

Changes have been applied to the following methods:

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

12. Method of order editing does not create the order in case of its absence any more

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.

13. Method /api/v4/customers/history is added

Method /api/v4/customers/history allows to get incremental history of customer changes. Read more detailed information on working with history methods.

14. Change in /api/v4/orders/history history method behavior

In 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

Version v3 is in status deprecated at the moment and forbidden for usage.

Version v2

Version v2 is not supported anymore and cannot be used.

Version v1

Version v1 is not supported anymore and cannot be used.


PrintEditHistory
Page last modified on June 17, 2020, at 02:57 PM