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. Появление методов создания и редактирования платежа

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

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

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-метода для работы с единицами измерения:

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

21. Появление координат у складов

В методе /api/v5/reference/stores* доступны поля store[address][coordinates][latitude] и store[address][coordinates][longitude] с широтой и долготой, соответственно. Поля доступны как на запись, так и на чтение.

22. Появление методов работы с файлами

Добавлена возможность работать с прикреплёнными к заказам или клиентам файлами Добавлено 6 методов для работы с файлами:

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

Добавлена возможность работать с корпоративными клиентами. Добавлено 20 новых методов:

В методах создания, пакетной загрузки и редактирования заказов /api/v5/orders/create, /api/v5/orders/upload, /api/v5/orders/{externalId}/edit добавлены поля:

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

Оформлять заказ на корпоративного клиента можно только в том случае, если в системе активирована работа с корпоративными клиентами.

Убраны поля контрагента у клиентов. Они могут существовать в режиме совместимости для ряда систем, которые не активировали работу с корпоративными клиентами. К таким полям относятся:

При активации работы с корпоративными клиентами, если в системе уже есть клиенты с заполненными данными контрагента, выполняется миграция по конвертации этих клиентов в корпоративных клиентов. Эти клиенты уже не будут более доступны через методы api/v5/customers/*, но их прошлую историю изменений можно всё так же получить через метод /api/v5/customers/history. После выполнения миграции клиенту добавится новая запись в эту историю, где у field будет значение type, у oldValue - customer, newValue - customer_corporate. Таким образом можно будет узнать какие из клиентов были конвертированы в корпоративных клиентов. При конвертации сохранятся id и externalId. Подробнее про процесс миграции можно узнать в документации по работе с корпоративными клиентами.

Версия 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

Версия v2 более не поддерживается и её использование невозможно.

Версия v1

Версия v1 более не поддерживается и её использование невозможно.

RetailCRM
Печать ∙ Править ∙ История
Редакция от 17.06.2020 14:57