retailCRM Документация

Версии API

Версия v4

Версия v4 является актуальной на данный момент. При работе с API необходимо использовать данную версию.

Отличия от v3

1. Свойства юридического лица в клиенте и заказе перенесены в объект contragent

В методах работы с клиентами /api/v4/customers* и заказами /api/v4/orders* реквизиты юридического лица указываются во вложенном объекте contragent.

Пример для клиента:

{
    "customer": {
        //...
        "contragent": {
            "contragentType": "individual"
        }        
    }
}

Пример для заказа:

{
    "order": {
        //...
        "contragent": {
            "contragentType":"legal-entity",
            "legalName":"ООО «Успех»",
            "legalAddress":"125481, РФ, Москва, ул. Фомичевой, д.18",
            "INN":"7713252121",
            "OKPO":"49330762",
            "KPP":"772301001",
            "OGRN":"1157346898831",
            "BIK":"044525355",
            "bank":"в ПАО \u0022Промсвязьбанк\u0022",
            "bankAddress":"г. Москва",
            "corrAccount":"30101810200000000555",
            "bankAccount":"40702810400000041213"
        }        
    }
}

2. Формализовано время доставки заказа

В методах работы с заказами /api/v4/orders* время доставки переехало из order[delivery][address][deliveryTime] в order[delivery][time] и задается не строкой, а структурой.

Если нужно передать диапазон времени:

order={
    //...
    "delivery": {
        //...
        "time": {
            "from": "13:00",
            "to": "18:00"
        }
    }
}

Если нужно передать точное время:

order={
    //...
    "delivery": {
        //...
        "time": {
            "from": "13:30",
            "to": "13:30"
        }
    }
}

Если нужно передать неформализованное время:

order={
    //...
    "delivery": {
        //...
        "time": {
            "custom": "после обеда"
        }
    }
}

3. Убрано поле customerId из метода создания заказа /api/v4/orders/create

Для привязки заказа к клиенту вместо order[customerId] теперь нужно указывать order[customer][id] (привязка по внутреннему ID клиента), order[customer][externalId] (привязка по внешнему ID клиента) или order[customer][browserId] (привязка по ID клиента в Collector).

4. Изменение фильтра заказов по ID клиента в /api/v4/orders

В методе /api/v4/orders убран фильтр по внешнему ID клиента filter[customerId]. Вместо него добавлен фильтр по внутреннему ID клиента filter[customerId] и фильтр по внешнему ID клиента filter[customerExternalId].

5. Добавлен метод /api/v4/store/products

Метод /api/v4/store/products можно использовать для получения списка товаров с SKU в соответствии с фильтром.

6. Убраны поля productId, offerId, xmlId из методов создания и редактирования заказа

Для привязки торгового предложения к заказу вместо order[items][][productId], order[items][][offerId] и order[items][][xmlId] нужно указывать одно из следующих полей: order[items][][offer][id] (внутренний ID SKU), order[items][][offer][externalId] (внешний ID товара или SKU), order[items][][offer][xmlId] (ID SKU в складской системе).

7. Методы для работы с пользователями

Добавлено 3 метода для работы с пользователями:

8. Изменения в методах работы с телефонией

9. Методы для регистрации складской системы

Добавлено 2 метода:

10. Методы для интеграции со службой доставки

Добавлено методы для интеграции службы доставки:

11. Множественные фильтры по справочникам в списковых методах

Изменения коснулись следующих методов:

В данных методах фильтры по полям типа Справочник стали множественными.

Было:

https://demo.retailcrm.ru/api/v3/orders?filter[orderMethod]=shopping-cart&apiKey=23fawef5e34fadgaw432da

Стало:

https://demo.retailcrm.ru/api/v4/orders?filter[orderMethods][]=shopping-cart&filter[orderMethods][]=phone&apiKey=23fawef5e34fadgaw432da

12. Метод редактирования заказа более не создает заказ при его отсутствии

Метод /api/v3/orders/{externalId}/edit создает заказ, если такого не существует в базе системы. Новый метод /api/v4/orders/{externalId}/edit в случае отсутствия заказа в базе возвращает ошибку 404 с информацией о том, что заказ не найден.

13. Добавлен метод /api/v4/customers/history

Метод /api/v4/customers/history позволяет получить инкрементальную историю изменения клиентов. Более подробная информация о работе с методами истории.

14. Изменение поведения метода истории /api/v4/orders/history

В методе предыдущей версии /api/v3/orders/history история отдавалась, группируясь по заказам, из-за чего повторные изменения одного и того же поля склеивались в последнее изменение. Метод /api/v4/orders/history в отличие от него отдает инкрементную историю изменения заказов, где каждого изменение представлено отдельной записью в истории. Более подробная информация о работе с методами истории.

Версия v3

Версия v3 является устаревшей deprecated и запрещена к использованию.

Отличия от v2

1. Изменение формата данных по доставке в заказе

В методах c префиксом /api/v3/orders из объекта заказа order убраны поля:

Вместо них введено поле delivery со следующей структурой:

{
    "order": {
         //...
        "delivery": {
            "code": "delivery-type-code",     // Символьный код типа доставки
            "integrationCode": "sdek",        // Код интеграционной доставки, связанной с типом доставки
            "data": {                         // Дополнительные данные для интеграционной доставки
                                              //     Данные отличаются в зависимости 
                                              //     от указанной интеграционной доставки
            },
            "service": {                      // Служба доставки
                "name": "Delivery Service 1",
                "code": "delivery-service-1"
            },
            "cost": 500,                      // Стоимость доставки
            "date": "2014-10-26",             // Дата доставки
            "address": {                      // Адрес доставки
                // ...
            }
        }
    }
}

Значения integrationCode и deliveryService взаимоисключающие, можно указывать только одно из значений. Подробнее о работе с данными по доставке можно ознакомиться в статье Данные о доставке в API.

2. Дополнительные свойства товара в заказе

В методах c префиксом /api/v3/orders теперь можно указывать индивидуальные параметры товара в заказе items[][properties]. Пример:

{
    "order": {
         //...
        "items": [
            {
                "productId": "1632",
                "initialPrice": 1520,
                "properties": [
                    "size": {
                        "name": "Размер",
                        "value": "41"
                    },
                    "material": {
                        "name": "Материал",
                        "value": "Кожа"
                    },
                ]
            },
            {
                //...
            }
        ]
    }
}

3. Поле managerId в заказе и клиенте

Появилась возможность указывать и получать через API ответственного менеджера заказа и клиента. За это отвечает поле managerId в методах /api/v3/orders* и /api/v3/customers*.

4. Удаление метода /api/v2/customers/{externalId}/orders

Данный метод отсутствует, начиная с версии v3. Вместо него предлагается использовать метод /api/v3/orders с фильтром filter[customerId].

5. Изменение поведения метода /api/v3/customers

В API версии v2 указанный метод принимал параметры fio, email, phone и отдавал список клиентов, которые удовлетворяют любому из параметров, без разбивки по страницам. Начиная с версии v3 метод принимает параметр filter[], а также параметры постраничного разбиения page и limit.

Стоит отметить, что в API v3 метод работает в старом режиме, если во входящих параметрах присутствуют fio, email или phone. В API с версии v4 данный метод будет вести себя только в новом режиме.

6. Появление метода /api/v3/orders/statuses

Данный метод был введен для случаев, когда сторонней по отношению к системе (интернет-магазин, учетная система и др.) требуется обновить статусы заказов данными, взятыми из системы. Метод позволяет запросить статусы нескольких заказов (до 500 заказов за один запрос). Заказы можно идентифицировать как по внутреннему ID заказа в систему id, так и по внешнему externalId.

7. Поля реквизитов в заказе

В методах c префиксом /api/v3/orders доступны следующие поля предназначенные для хранения реквизитов юридических лиц:

Данные поля доступны как на запись, так и на чтение.

8. Появление методов /api/v3/reference/stores и /api/v3/reference/stores/{code}/edit

Данные методы предоставляют возможность получать перечень доступных складов, а также редактировать и создавать новые склады.

9. Появление методов /api/v3/store/inventories и /api/v3/store/inventories/upload

Данные методы позволяют загружать и получать информацию об остатках и закупочных ценах товаров с детализацией по складам.

10. Появление методов для комплектации заказов

Появились методы для работы с комплектацией заказа:

Данные методы позволяют производить тесную интеграцию со складской системой. Менеджер может указывать комплектацию заказа (какие товары с каких складов брать) в систему, а складская система через указанные методы считывает эти данные и производит резервирование.

11. Появление методов для работы с магазинами

Появились методы для создания, редактирования и получения списка магазинов:

12. Появление метода /api/v3/reference/countries

Данный метод позволяет получить список стран, которые активированы в настройках системы.

13. Появление аналитических полей в данных клиента

В методах /api/v3/customers и /api/v3/customers/{externalId} в объекте customer возвращаются аналитические поля:

14. Данные по источнику в методах групп Заказы и Клиенты

В методах групп Заказы и Клиенты появилась возможность записать и получить данные по источнику (source, medium, campaign) заказа и клиента из полей:

15. Данные по отгрузке в заказе

В методах группы Заказы /api/v3/orders* добавлены поля:

16. Возможность добавления товара в заказ по внутреннему ID товара или ID товара в складкой системе

В методах /api/v3/orders/create, /api/v3/orders/{externalId}/edit, /api/v3/orders/upload наряду с прежней возможностью передачи товара по внешнему ID товара order[items][][productId] добавлена возможность передачи товара в заказ по внутреннему ID товара order[items][][offerId] и ID товара в складкой системе order[items][][xmlId].

17. Поле День рождения в клиенте

В методах /api/v3/customer* добавлено поле customer[birthday], доступное как на запись, так и на чтение.

18. Поле страны и идентификаторы Geohelper в адресах

В методах заказа и клиента в объектах адреса order[delivery][address] и customer[address] добавлены следующие поля, доступные как на чтение, так и на запись:

19. Появление методов группы Телефония

Добавлены методы для интеграции службы телефонии с системой:

Версия v2

Версия v2 практически аналогична версии v1. В данный момент в статусе deprecated и запрещена к использованию.

Отличия от v1

1. Изменения в методе /api/v2/orders/history

В ответе данного метода введен параметр generatedAt, в котором API указывает дату и время генерации ответа.

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

При работе с методом истории внешнему приложению необходимо сохранять значение из поля generateAt и подставлять его при следующем запросе в GET-параметре startDate. Это позволяет избежать потери данных из истории, если система и внешнее приложение работают в разных часовых поясах.

2. Поле fromApi в заказе

В ответе методов /api/v2/orders/{externalId}, /api/v2/orders/history у заказов дополнительно указывается поле fromApi = true|false, которое показывает, каким образом был создан заказ: через API или в системе.

Версия v1

Первая версия API. В данный момент в статусе deprecated и запрещена к использованию.


Редакция от 26.12.2016 15:50