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

Developers /

Версии API

Версия v5

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

Отличия от v4

1. Появление метода /api/v5/users/{id}/status

Данный метод меняет статус пользователя в системе. Позволяет сихронизировать статус пользователя с внешней системой (например, телефонией).

2. Появление метода получения списка сегментов /api/v5/segments

Данный метод возвращает список сегментов. Позволяет сихронизировать сегменты клиентов с внешней системой.

3. Появление методов объединения клиентов и объединения заказов

Добавлены методы /api/v5/customers/combine и /api/v5/orders/combine.

Метод /api/v5/customers/combine позволяет объединить несколько клиентов в одного. При конфликте полей будут сохраняться данные конечного клиента. Соответственно, если нужные вам данные в удаляемых клиентах, то нужно предварительно их перенести в основного клиента.

Метод /api/v5/orders/combine позволяет объединить 2 заказа. При этом будут сохранены данные конечного заказа, а состав объединен в соответствии с указанной стратегией.

4. Появление метода /api/v5/store/product-groups

Данный метод возвращает список групп товаров каталогов.

5. Появление методов работы с пользовательскими полями

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

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

6. Поле с коллекцией изображений в товаре

В методе /api/v5/store/products доступно поле products[][offers][][images][] с коллекцией изображений, прикрепленных к торговому предложению.

7. Поле Пол в клиенте

В методах /api/v5/customers* доступно поле customer[sex] со значениями male|female. Поле доступно как на запись, так и на чтение. Также в методе списка клиентов доступен фильтр по данному полю.

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

Добавлено 4 метода для работы задачами:

9. Изменение состава полей оплаты в заказе

В методах /api/v5/orders* убраны следующие поля:

В методах получения информации о заказе /api/v5/orders и /api/v5/orders/get добавлены поля:

Подробнее об изменениях в оплате заказов.

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

Добавлено 2 метода для работы с платежами заказа:

Подробнее об изменениях в оплате заказов.

11. Появление ставки НДС у товаров в заказе

В методах получения информации о заказе /api/v5/orders и /api/v5/orders/get добавлены поля:

В методах создания /api/v5/orders/create и редактирования /api/v5/orders/{externalId}/edit заказа для каждой позиции можно указать индивидуальную ставку НДС order[items][][vatRate].

12. Появление методов работы с заметками о клиенте и удаление поля customer[commentary]

В сущности Клиент на место поля Комментарий пришли заметки. Поэтому в методах работы с клиентом удалено поле customer[commentary].

Также добавлено 3 метода для работы с заметками о клиенте:

13. Изменение работы со скидками заказа

Убраны поля order[discount], order[discountPercent], order[items][][discount], order[items][][discountPercent] во всех методах работы с заказами.

В методах создания и редактирования заказа /api/v5/orders/create, /api/v5/orders/{externalId}/edit, /api/v5/orders/upload можно передавать скидки на заказ и товары в полях order[discountManualAmount], order[discountManualPercent], order[items][][discountManualAmount], order[items][][discountManualPercent], при этом скидки на заказ будут распределяться между товарами.

В методах получения заказов /api/v5/orders, /api/v5/orders/{externalId} возвращается итоговая расчетная денежная скидка на единицу товара для каждой позиции товара в поле order[items][][discountTotal], которая учитывает и скидки на текущий товар, и скидки на заказ, распределенные между товарами.

Стоит отметить, что могут возникать случаи, когда скидки на заказ не могут быть разделены между товарами (например, в заказе передается одна позиция товара в количестве 3 штуки, а также скидка на заказ 1000 рублей). Если возникает такой случай, то будет выдана ошибка. Чтобы этого избежать мы добавили настройку, при включении которой система сама определит ближайший размер скидки на заказ который позволит разделить ее между товарами.

Подробнее о работе со скидками.

14. Поле с группами в товаре

В методе /api/v5/store/products доступно поле products[][groups][] с ID групп товаров, к которым относится товар.

15. Справочник свойств товаров и фильтрация товаров по свойствам

Добавлен метод /api/v5/store/products/properties, позволяющий получить перечень свойств, используемых в каталоге. Кроме того, в методе /api/v5/store/products добавлен фильтр filter[properties][], дающий возможность выбирать товары с указанными значениями определенных свойств.

16. Методы для оформления заявки на забор товаров службой доставки

Добавлено 4 API-метода:

А также 2 callback-метода:

Подробнее в статье про API доставок.

17. Изменение методов регистрации модуля

Старые методы регистрации модулей и получения информации о модуле убраны, а именно:

Вместо них введено 2 единых метода регистрации модуля:

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

Также был введен callback-метод:

18. Методы работы с курьерами

Добавлено 3 API-метода:

19. Информация о сегментах в API-методах получения информации о клиентах

В API-методах получения информации о клиентах доступны данные о сегментах, к которым они относятся:

20. Справочник единиц измерений

Добавлено 2 API-метода для работы с единицами измерения:

Кроме того, информация об единицах измерения доступна в следующих методах:

Версия v4

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

Отличия от 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 и запрещена к использованию.

retailCRM
Печать ∙ Править ∙ История
Редакция от 19.02.2019 11:10