Версия 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]
Подробнее об изменениях в оплате заказов.
Добавлено 2 метода для работы с платежами заказа:
/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]
Версия 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
и запрещена к использованию.
В методах c префиксом /api/v3/orders
из объекта заказа order
убраны поля:
deliveryDate
deliveryAddress
deliveryCost
deliveryService
deliveryType
Вместо них введено поле 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.
В методах c префиксом /api/v3/orders
теперь можно указывать индивидуальные параметры товара в заказе items[][properties]
. Пример:
{
"order": {
//...
"items": [
{
"productId": "1632",
"initialPrice": 1520,
"properties": [
"size": {
"name": "Размер",
"value": "41"
},
"material": {
"name": "Материал",
"value": "Кожа"
},
]
},
{
//...
}
]
}
}
Появилась возможность указывать и получать через API ответственного менеджера заказа и клиента. За это отвечает поле managerId
в методах /api/v3/orders*
и /api/v3/customers*
.
/api/v2/customers/{externalId}/orders
Данный метод отсутствует, начиная с версии v3
. Вместо него предлагается использовать метод /api/v3/orders
с фильтром filter[customerId]
.
/api/v3/customers
В API версии v2
указанный метод принимал параметры fio
, email
, phone
и отдавал список клиентов, которые удовлетворяют любому из параметров, без разбивки по страницам. Начиная с версии v3
метод принимает параметр filter[]
, а также параметры постраничного разбиения page
и limit
.
Стоит отметить, что в API v3
метод работает в старом режиме, если во входящих параметрах присутствуют fio
, email
или phone
. В API с версии v4
данный метод будет вести себя только в новом режиме.
/api/v3/orders/statuses
Данный метод был введен для случаев, когда сторонней по отношению к системе (интернет-магазин, учетная система и др.) требуется обновить статусы заказов данными, взятыми из системы. Метод позволяет запросить статусы нескольких заказов (до 500 заказов за один запрос). Заказы можно идентифицировать как по внутреннему ID заказа в систему id
, так и по внешнему externalId
.
В методах c префиксом /api/v3/orders
доступны следующие поля предназначенные для хранения реквизитов юридических лиц:
contragentType
(физ. лицо individual
, юр. лицо legal-entity
, ИП enterpreneur
)
legalName
(для legal-entity
и enterpreneur
)
legalAddress
(для legal-entity
и enterpreneur
)
INN
(для legal-entity
и enterpreneur
)
OKPO
(для legal-entity
и enterpreneur
)
KPP
(для legal-entity
)
OGRN
(для legal-entity
)
OGRNIP
(для enterpreneur
)
certificateNumber
(для enterpreneur
)
certificateDate
(для enterpreneur
)
BIK
(для legal-entity
и enterpreneur
)
bank
(для legal-entity
и enterpreneur
)
bankAddress
(для legal-entity
и enterpreneur
)
corrAccount
(для legal-entity
и enterpreneur
)
bankAccount
(для legal-entity
и enterpreneur
)
Данные поля доступны как на запись, так и на чтение.
/api/v3/reference/stores
и /api/v3/reference/stores/{code}/edit
Данные методы предоставляют возможность получать перечень доступных складов, а также редактировать и создавать новые склады.
/api/v3/store/inventories
и /api/v3/store/inventories/upload
Данные методы позволяют загружать и получать информацию об остатках и закупочных ценах товаров с детализацией по складам.
Появились методы для работы с комплектацией заказа:
/api/v3/orders/packs
/api/v3/orders/packs/create
/api/v3/orders/packs/history
/api/v3/orders/packs/{id}
/api/v3/orders/packs/{id}/delete
/api/v3/orders/packs/{id}/edit
Данные методы позволяют производить тесную интеграцию со складской системой. Менеджер может указывать комплектацию заказа (какие товары с каких складов брать) в систему, а складская система через указанные методы считывает эти данные и производит резервирование.
Появились методы для создания, редактирования и получения списка магазинов:
/api/v3/reference/sites
/api/v3/reference/sites/{code}/edit
/api/v3/reference/countries
Данный метод позволяет получить список стран, которые активированы в настройках системы.
В методах /api/v3/customers
и /api/v3/customers/{externalId}
в объекте customer
возвращаются аналитические поля:
avgMarginSumm
– средняя маржа с заказа клиента
marginSumm
– суммарная маржа с клиента
totalSumm
– общий доход с клиента
averageSumm
– средний чек
ordersCount
– количество неотмененных заказов клиента
В методах групп Заказы и Клиенты появилась возможность записать и получить данные по источнику (source, medium, campaign) заказа и клиента из полей:
order[source][source]
– источник, с которого пришел клиент и оформил заказ
order[source][medium]
– канал, с которого пришел клиент и оформил заказ
order[source][campaign]
– рекламная кампания
customer[source][source]
– источник, с которого впервые пришел клиент
customer[source][medium]
– канал, с которого впервые пришел клиент
customer[source][campaign]
– рекламная кампания
В методах группы Заказы /api/v3/orders*
добавлены поля:
order[shipmentStore]
– склад отгрузки заказа
order[shipmentDate]
– дата отгрузки заказа
order[shipped]
– факт отгрузки (доступен только на чтение)
В методах /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]
.
В методах /api/v3/customer*
добавлено поле customer[birthday]
, доступное как на запись, так и на чтение.
В методах заказа и клиента в объектах адреса order[delivery][address]
и customer[address]
добавлены следующие поля, доступные как на чтение, так и на запись:
countryIso
– код страны
regionId
– идентификатор региона в Geohelper
cityId
– идентификатор города в Geohelper
streetId
– идентификатор улицы в Geohelper
Добавлены методы для интеграции службы телефонии с системой:
/api/v3/telephony/call/event
/api/v3/telephony/calls/upload
/api/v3/telephony/manager
/api/v3/telephony/setting/{code}
Версия v2
практически аналогична версии v1
. В данный момент в статусе deprecated
и запрещена к использованию.
/api/v2/orders/history
В ответе данного метода введен параметр generatedAt
, в котором API указывает дату и время генерации ответа.
{
"success": true,
"generatedAt": "2014-10-22 14:51:26",
"orders": {
//...
}
}
При работе с методом истории внешнему приложению необходимо сохранять значение из поля generateAt
и подставлять его при следующем запросе в GET-параметре startDate
. Это позволяет избежать потери данных из истории, если система и внешнее приложение работают в разных часовых поясах.
В ответе методов /api/v2/orders/{externalId}
, /api/v2/orders/history
у заказов дополнительно указывается поле fromApi = true|false
, которое показывает, каким образом был создан заказ: через API или в системе.
Первая версия API. В данный момент в статусе deprecated
и запрещена к использованию.