retailCRM Documentation

API version

Version v5

Version v5 is relevant at the moment. When working with API you need to use this version.

Difference from v4

1. Emergence 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. Emergence 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. Emergence 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. Emergence of method /api/v5/store/product-groups

This method returns the list of product groups in catalogues.

5. Emergence 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. Emergence 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 in methods for getting information about the order /api/v5/orders and /api/v5/orders/get:

In details about changes in payment of orders.

10. Emergence of methods for payment creation and editing

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

In details about changes in payment of orders.

11. Emergence of VAT rate for goods in the order

The following fields have been added in 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. Emergence 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 good 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 good 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.

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.

Difference from v2

1. Change of data on delivery format in order

In methods with prefix /api/v3/orders from order object order was removed the fields:

instead of them there will be created the field delivery with the following structure:

{
    "order": {
         //...
        "delivery": {
            "code": "delivery-type-code",     // Symbolic code of delivery type
            "integrationCode": "sdek",        // Code of inegrated delivery service associated with delivery type
            "data": {                         // Additional data for integrated delivery service
                                              //     Data may be different   
                                              //     depending on delivery service
            },
            "service": {                      // Delivery service
                "name": "Delivery Service 1",
                "code": "delivery-service-1"
            },
            "cost": 500,                      // Delivery cost
            "date": "2014-10-26",             // Delivery date
            "address": {                      // Delivery address
                // ...
            }
        }
    }
}

Values integrationCode and deliveryService are mutually exclusive, you may indicate only one of them. You can read more about working with delivery data in article Information on delivery in API.

2. Additional item properties in order

In methods with prefix /api/v3/orders now you can specify individual parameters of item in the order items[][properties]. Example:

{
    "order": {
         //...
        "items": [
            {
                "productId": "1632",
                "initialPrice": 1520,
                "properties": [
                    "size": {
                        "name": "Size",
                        "value": "41"
                    },
                    "material": {
                        "name": "Material",
                        "value": "Leather"
                    },
                ]
            },
            {
                //...
            }
        ]
    }
}

3. Field managerId in order and customer

There is an opportunity to specify and get responsible manager of order and customer by API. The responsible field for that data is managerId in methods /api/v3/orders* and /api/v3/customers*.

4. Method /api/v2/customers/{externalId}/orders removing

This method is absent starting version v3. Instead of that recommended to use method /api/v3/orders with filter filter[customerId].

5. Change of method /api/v3/customers behavior

In API version v2 this method receives parameters fio, email, phone and returns customer list that match any of the parameters, without pagination. Starting from version v3 method receives parameter filter[] and parameters of pagination page и limit.

It is worth noting that in API v3 method works in old mode, if in the incoming parameters are present fio, email или phone. In API starting from version v4 this metod will work only in new mode.

6. Appearance of method /api/v3/orders/statuses

This method was introduced for cases, when a third-party system in relation to system (web-store, warehouse system, etc.) require updating of order statuses by data taken from system . Method allows to request statuses of several orders (up to 500 orders per one request). Orders may be identified either by internal order ID in system id or by external externalId.

7. Fields of requisites in order

In methods with prefix /api/v3/orders the following fields are available for storage of legal requisites:

These fields are available both for writing and reading.

8. Appearance of methods /api/v3/reference/stores and /api/v3/reference/stores/{code}/edit

These methods allow to get the list of available warehouses and also to edit and create new warehouses.

9. Appearance of methods /api/v3/store/inventories and /api/v3/store/inventories/upload

These methods allow to upload and get information on leftover stocks and purchasing price of items with detalization by warehouses.

10. Appearance of methods for order packing

There are methods for working with order packing:

These methods allow to realize close integration with warehouse system. Manager can specify the packing steps (warehouses for necessary items) in system, and the warehouse system can get these data by such methods and nake reservation.

11. Appearance of methods for working with stores

There are new methods for creating, editing and getting the list of stores:

12. Appearance of method /api/v3/reference/countries

This method allows to get the list of countries, which are active in the system settings.

13. Appearance of analytic fields in customer data

In methods /api/v3/customers and /api/v3/customers/{externalId} in the object customer will be returned the following analytic fields:

14. Data on source in methods of groups Orders and Customers

In methods of groups Orders and Customers appeared the opportunity to record and get data on source (source, medium, campaign) of order and customer from the fields:

15. Data on shipment in the order

In methods of group Orders /api/v3/orders* are added the following fields:

16. Ability to add the item in order by internal item ID or by item ID in the warehouse system

In methods /api/v3/orders/create, /api/v3/orders/{externalId}/edit, /api/v3/orders/upload together with existing opportunity of item transfer by external item ID order[items][][productId] is added the opportunity of item transfer to the order by internal item ID order[items][][offerId] and item ID in the warehouse system order[items][][xmlId].

17. Field Birthday in customer card

In methods /api/v3/customer* was added the field customer[birthday], available both for reading and for editing.

18. Field of country and Geohelper identificators in addresses

In methods of order and customer in the address objects order[delivery][address] and customer[address] were added the following fields, available both for reading and for editing:

19. Appearance of methods of Telephony group

Added methods for integration of the telephony service with system:

Version v2

Version v2 is substantially similar with version v1. At the moment it is in status deprecated and forbidden for usage.

Difference from v1

1. Changes in method /api/v2/orders/history

In response of this method was included parameter generatedAt, in which API spicified date and time of response generation.

{
    "success": true,
    "generatedAt": "2014-10-22 14:51:26",
    "orders": {
        //...
    }
}

When working with the history method, the external application needs to keep the value of the field generateAt and to substitute it with the following query in GET-parameter startDate. It allows to avoid losing of history data, if third-party application and system work in different time zones.

2. Field fromApi in order

In response of methods /api/v2/orders/{externalId}, /api/v2/orders/history, in orders there are additionally specified field fromApi = true|false, which shows how the order was created: by API or in system.

Version v1

The first API version. At the moment it is in status deprecated and forbidden for usage.


PrintEditHistory
Page last modified on June 26, 2018, at 03:06 PM