Версия v5
является актуальной на данный момент. При работе с API необходимо использовать данную версию.
/api/v5/users/{id}/status
Данный метод меняет статус пользователя в системе. Позволяет сихронизировать статус пользователя с внешней системой (например, телефонией).
/api/v5/segments
Данный метод возвращает список сегментов. Позволяет сихронизировать сегменты клиентов с внешней системой.
Добавлены методы /api/v5/customers/combine
и /api/v5/orders/combine
.
Метод /api/v5/customers/combine
позволяет объединить несколько клиентов в одного. При конфликте полей будут сохраняться данные конечного клиента. Соответственно, если нужные вам данные в удаляемых клиентах, то нужно предварительно их перенести в основного клиента.
Метод /api/v5/orders/combine
позволяет объединить 2 заказа. При этом будут сохранены данные конечного заказа, а состав объединен в соответствии с указанной стратегией.
/api/v5/store/product-groups
Данный метод возвращает список групп товаров каталогов.
Добавлено 4 метода для работы с пользовательскими полями:
/api/v5/custom-fields
– получение списка пользовательских полей
/api/v5/custom-fields/{entity}/create
– создание пользовательского поля
/api/v5/custom-fields/{entity}/{code}
– получение информации о пользовательском поле
/api/v5/custom-fields/{entity}/{code}/edit
– редактирование пользовательского поля
Добавлено 4 метода для работы с пользовательскими справочниками:
/api/v5/custom-fields/dictionaries
– получение списка пользовательских справочников
/api/v5/custom-fields/dictionaries/create
– создание пользовательского справочника
/api/v5/custom-fields/dictionaries/{code}
– получение информации о пользовательском справочнике
/api/v5/custom-fields/dictionaries/{code}/edit
– редактирование пользовательского справочника
В методе /api/v5/store/products
доступно поле products[][offers][][images][]
с коллекцией изображений, прикрепленных к торговому предложению.
В методах /api/v5/customers*
доступно поле customer[sex]
со значениями male|female
. Поле доступно как на запись, так и на чтение. Также в методе списка клиентов доступен фильтр по данному полю.
Добавлено 4 метода для работы задачами:
/api/v5/tasks
– получение списка задач
/api/v5/tasks/create
– создание задачи
/api/v5/tasks/{id}
– получение информации о задаче
/api/v5/tasks/{id}/edit
– редактирование задачи
В методах /api/v5/orders*
убраны следующие поля:
order[paymentType]
order[paymentStatus]
order[paymentDetail]
В методах получения информации о заказе /api/v5/orders
и /api/v5/orders/get
добавлены поля:
order[payments][]
order[fullPaidAt]
Подробнее об изменениях в оплате заказов.
Добавлено 3 метода для работы с платежами заказа:
/api/v5/orders/payments/create
– добавление платежа
/api/v5/orders/payments/{id}/edit
– редактирование платежа
/api/v5/orders/payments/{id}/delete
– удаление платежа
Подробнее об изменениях в оплате заказов.
В методах получения информации о заказе /api/v5/orders
и /api/v5/orders/get
добавлены поля:
order[items][][vatRate]
order[items][][offer][vatRate]
В методах создания /api/v5/orders/create
и редактирования /api/v5/orders/{externalId}/edit
заказа для каждой позиции можно указать индивидуальную ставку НДС order[items][][vatRate]
.
customer[commentary]
В сущности Клиент на место поля Комментарий пришли заметки. Поэтому в методах работы с клиентом удалено поле customer[commentary]
.
Также добавлено 3 метода для работы с заметками о клиенте:
/api/v5/customers/notes
– получение списка заметок
/api/v5/customers/notes/create
– добавление заметки
/api/v5/customers/notes/{id}/delete
– удаление заметки
Убраны поля 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 рублей). Если возникает такой случай, то будет выдана ошибка. Чтобы этого избежать мы добавили настройку, при включении которой система сама определит ближайший размер скидки на заказ который позволит разделить ее между товарами.
Подробнее о работе со скидками.
В методе /api/v5/store/products
доступно поле products[][groups][]
с ID групп товаров, к которым относится товар.
Добавлен метод /api/v5/store/products/properties
, позволяющий получить перечень свойств, используемых в каталоге. Кроме того, в методе
/api/v5/store/products
добавлен фильтр filter[properties][]
, дающий возможность выбирать товары с указанными значениями определенных свойств.
Добавлено 4 API-метода:
GET /api/v5/delivery/shipments
– получение списка отгрузок в службы доставки
POST /api/v5/delivery/shipments/create
– создание отгрузки
GET /api/v5/delivery/shipments/{id}
– получение информации об отгрузке
POST /api/v5/delivery/shipments/{id}/edit
– редактирование отгрузки
А также 2 callback-метода:
POST {integrationModule["baseUrl"]}/{configuration["actions"]["shipmentSave"]}
– создание и редактирование заявки на отгрузку
POST {integrationModule["baseUrl"]}/{configuration["actions"]["shipmentDelete»]}
– удаление заявки на отгрузку
Подробнее в статье про API доставок.
Старые методы регистрации модулей и получения информации о модуле убраны, а именно:
/api/v4/store/setting/{code}/edit
– регистрация и указание конфигурации складской системы
/api/v4/store/setting/{code}
– получение текущей конфигурации складской системы
/api/v4/delivery/generic/setting/{subcode}/edit
– регистрация и указание конфигурации службы доставки
/api/v4/delivery/generic/setting/{subcode}
– получение текущей конфигурации службы доставки
/api/v4/marketplace/external/setting/{code}/edit
– регистрация модуля интеграции с маркетплейс-площадкой
/api/v4/telephony/setting/{code}/edit
– создание/редактирование конфигурации модуля телефонии
/api/v4/telephony/setting/{code}
– получение текущей конфигурации модуля телефонии
Вместо них введено 2 единых метода регистрации модуля:
/api/v5/integration-modules/{code}/edit
– создание/редактирование параметров интеграционного модуля
/api/v5/integration-modules/{code}
– получение параметров интеграционного модуля
В рамках этих методов можно также передать специфичные для определенных типов модулей настройки.
Также был введен callback-метод:
{integrationModule["baseUrl"]}/{integrationModule["actions"]["activity"]}
– вызывается при включении/выключении модуля пользователем внутри системы.
Добавлено 3 API-метода:
GET /api/v5/reference/couriers
– список курьеров, заведенных в системе
POST /api/v5/reference/couriers/create
– создание курьера
POST /api/v5/reference/couriers/{id}/edit
– редактирование курьера
В API-методах получения информации о клиентах доступны данные о сегментах, к которым они относятся:
GET /api/v5/customers
– в поле customers[][segments]
POST /api/v5/customers/{externalId}
– в поле customer[segments]
Добавлено 2 API-метода для работы с единицами измерения:
GET /api/v5/reference/units
– получение информации об единицах измерения в системе
POST /api/v5/reference/units/{code}/edit
– создание и редактирование единиц измерения
Кроме того, информация об единицах измерения доступна в следующих методах:
GET /api/v5/store/products
– поле products[][offers][][unit]
POST {integrationModule["baseUrl"]}/{configuration["actions"]["save"]}
– поле save[packages][][items][][unit]
GET /api/v5/orders
– поле orders[items][][offer][unit]
GET /api/v5/orders/{externalId}
– поле order[items][][offer][unit]
GET /api/v5/orders/packs
– поле packs[unit]
GET /api/v5/orders/packs/{id}
– поле pack[unit]
В методе /api/v5/reference/stores*
доступны поля store[address][coordinates][latitude]
и store[address][coordinates][longitude]
с широтой и долготой, соответственно. Поля доступны как на запись, так и на чтение.
Добавлена возможность работать с прикреплёнными к заказам или клиентам файлами Добавлено 6 методов для работы с файлами:
/api/v5/files
– получение списка файлов
/api/v5/files/{id}
– получение информации о конкретном файле
/api/v5/files/{id}/download
– скачивание загруженного в систему файла
/api/v5/files/upload
– загрузка файла в систему
/api/v5/files/{id}/edit
– редактирование имени файла и редактирование привязки файла к заказам и клиентам
/api/v5/files/{id}/delete
– удаление файла из системы
Добавлена возможность работать с корпоративными клиентами. Добавлено 20 новых методов:
/api/v5/customers-corporate
- получение списка корпоративных клиентов, удовлетворяющих заданному фильтру
/api/v5/customers-corporate/combine
- объединение корпоративных клиентов
/api/v5/customers-corporate/create
- создание корпоративного клиента
/api/v5/customers-corporate/fix-external-ids
- массовая запись внешних ID корпоративных клиентов
/api/v5/customers-corporate/history
- получение истории изменения корпоративных клиентов
/api/v5/customers-corporate/notes
- получение заметок
/api/v5/customers-corporate/notes/create
- создание заметки
/api/v5/customers-corporate/notes/{id}/delete
- удаление заметки
/api/v5/customers-corporate/upload
- пакетная загрузка корпоративных клиентов
/api/v5/customers-corporate/{externalId}
- получение информации о корпоративном клиенте
/api/v5/customers-corporate/{externalId}/addresses
- список адресов корпоративного клиента
/api/v5/customers-corporate/{externalId}/addresses/create
- создание адреса для корпоративного клиента
/api/v5/customers-corporate/{externalId}/addresses/{entityExternalId}/edit
- редактирование адреса корпоративного клиента
/api/v5/customers-corporate/{externalId}/companies
- список компаний корпоративного клиента
/api/v5/customers-corporate/{externalId}/companies/create
- создание компании для корпоративного клиента
/api/v5/customers-corporate/{externalId}/companies/{entityExternalId}/edit
- редактирование компании корпоративного клиента
/api/v5/customers-corporate/{externalId}/contacts
- список контактных лиц корпоративного клиента
/api/v5/customers-corporate/{externalId}/contacts/create
- создание связи корпоративного клиента с контактным лицом
/api/v5/customers-corporate/{externalId}/contacts/{entityExternalId}/edit
- редактирование связи корпоративного клиента с контактным лицом
/api/v5/customers-corporate/{externalId}/edit
- редактирование корпоративного клиента
В методах создания, пакетной загрузки и редактирования заказов /api/v5/orders/create
, /api/v5/orders/upload
, /api/v5/orders/{externalId}/edit
добавлены поля:
order[customer][type]
- тип клиента, по умолчанию customer
. Для создания заказа на корпоративного клиента в этом поле надо передать customer_corporate
order[customer][nickName]
- наименование контрагента, передаётся когда нужно создать нового корпоративного клиента
order[contact]
- набор данных для подстановки в заказ контактного лица, используется если заказ оформляется на корпоративного клиента
order[company]
- набор данных для подстановки в заказ компании, используется если заказ оформляется на корпоративного клиента
В методах получения списка и получения информации о заказе /api/v5/orders
, /api/v5/orders/{externalId}
добавлены поля:
order[customer][type]
- тип клиента, на которого оформлен заказ
order[contact]
- контактное лицо заказа
order[company]
- компания заказа
Оформлять заказ на корпоративного клиента можно только в том случае, если в системе активирована работа с корпоративными клиентами.
Убраны поля контрагента у клиентов. Они могут существовать в режиме совместимости для ряда систем, которые не активировали работу с корпоративными клиентами. К таким полям относятся:
/api/v5/customers
:
filter[contragentName]
filter[contragentTypes][]
filter[contragentInn]
filter[contragentKpp]
filter[contragentBik]
filter[contragentCorrAccount]
filter[contragentBankAccount]
customers[][contragent]
/api/v5/customers/create
, /api/v5/customers/{externalId}/edit
, /api/v5/customers/upload
, /api/v5/customers/{externalId}
:
customers[][contragent]
При активации работы с корпоративными клиентами, если в системе уже есть клиенты с заполненными данными контрагента, выполняется миграция по конвертации этих клиентов в корпоративных клиентов. Эти клиенты уже не будут более доступны через методы api/v5/customers/*
, но их прошлую историю изменений можно всё так же получить через метод /api/v5/customers/history
. После выполнения миграции клиенту добавится новая запись в эту историю, где у field
будет значение type
, у oldValue
- customer
, newValue
- customer_corporate
. Таким образом можно будет узнать какие из клиентов были конвертированы в корпоративных клиентов. При конвертации сохранятся id и externalId. Подробнее про процесс миграции можно узнать в документации по работе с корпоративными клиентами.
Версия v4
является устаревшей deprecated
и не рекомендуется к использованию.
В методах работы с клиентами /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"
}
}
}
В методах работы с заказами /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": "после обеда"
}
}
}
customerId
из метода создания заказа /api/v4/orders/create
Для привязки заказа к клиенту вместо order[customerId]
теперь нужно указывать order[customer][id]
(привязка по внутреннему ID клиента), order[customer][externalId]
(привязка по внешнему ID клиента) или order[customer][browserId]
(привязка по ID клиента в Collector).
/api/v4/orders
В методе /api/v4/orders
убран фильтр по внешнему ID клиента filter[customerId]
. Вместо него добавлен фильтр по внутреннему ID клиента filter[customerId]
и фильтр по внешнему ID клиента filter[customerExternalId]
.
/api/v4/store/products
Метод /api/v4/store/products
можно использовать для получения списка товаров с SKU в соответствии с фильтром.
Для привязки торгового предложения к заказу вместо 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 в складской системе).
Добавлено 3 метода для работы с пользователями:
/api/v4/user-groups
– получение списка групп пользователей
/api/v4/users
– получение списка пользователей
/api/v4/users/{id}
– получение информации о пользователе
/api/v4/telephony/setting/{code}/edit
, при этом отправляемые данные обернуты в объект configuration
/api/v4/telephony/setting/{code}
additionalCodes
(добавочные коды, назначенные на менеджеров), externalPhones
(закрепление внешних номеров за магазинами), allowEdit
(разрешать или нет менять настройки через интерфейс системы), inputEventSupported
(указание того, что телефония уведомляет систему о входящем звонке), outputEventSupported
(указание того, что телефония уведомляет систему об исходящем звонке), hangupEventSupported
(указание того, что телефония уведомляет систему о завершении звонка), changeUserStatusUrl
(адрес, по которому система будет сообщать телефонию о смене статуса менеджера).
/api/v4/telephony/call/event
:
event
code
заменено на codes
и стало массивом (можно уведомить нескольких менеджеров о входящем звонке)
webAnalyticsData
для передачи данных веб-аналитики
callExternalId
для передачи внешнего ID звонка
Добавлено 2 метода:
/api/v4/store/setting/{code}/edit
– регистрация и указание конфигурации складской системы
/api/v4/store/setting/{code}
– получение текущей конфигурации складской системы
Добавлено методы для интеграции службы доставки:
/api/v4/delivery/generic/setting/{subcode}/edit
– регистрация и указание конфигурации службы доставки
/api/v4/delivery/generic/setting/{subcode}
– получение текущей конфигурации службы доставки
/api/v4/delivery/generic/{subcode}/tracking
– обновление статусов доставки
Изменения коснулись следующих методов:
/api/v4/orders
/api/v4/customers
/api/v4/orders/packs
/api/v4/store/inventories
/api/v4/users
В данных методах фильтры по полям типа Справочник стали множественными.
Было:
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
Метод /api/v3/orders/{externalId}/edit
создает заказ, если такого не существует в базе системы. Новый метод /api/v4/orders/{externalId}/edit
в случае отсутствия заказа в базе возвращает ошибку 404 с информацией о том, что заказ не найден.
/api/v4/customers/history
Метод /api/v4/customers/history
позволяет получить инкрементальную историю изменения клиентов. Более подробная информация о работе с методами истории.
/api/v4/orders/history
В методе предыдущей версии /api/v3/orders/history
история отдавалась, группируясь по заказам, из-за чего повторные изменения одного и того же поля склеивались в последнее изменение. Метод /api/v4/orders/history
в отличие от него отдает инкрементную историю изменения заказов, где каждого изменение представлено отдельной записью в истории. Более подробная информация о работе с методами истории.
Версия v3
является устаревшей deprecated
и запрещена к использованию.
Версия v2
более не поддерживается и её использование невозможно.
Версия v1
более не поддерживается и её использование невозможно.