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

Справочник методов

Все методы под одним базовым адресом, с JSON в обе стороны и единым форматом ошибок. Каждый метод указывает право ключа, без которого вернёт 403.

Содержание

Служебные

getПроверить ключ
getКаталог каналов
getСписок точек

Контакты

postПередать контакт клиента

Каскады

getСценарии каскада
postЗапустить каскад
getСтатус каскада
postСоздать ссылку на отзыв

Каналы

postОтправить запрос отзыва: Email
postОтправить запрос отзыва: SMS

Авторизация, идемпотентность, лимиты и формат ошибок — в обзоре. Базовый адрес: https://evidra.ru/api/v1.

Служебные

Проверка ключа и справочники

get

/api/v1/pingлюбой действующий ключ

Проверить ключ

Ответ `200`Ключ действителен

Поле	Тип	Описание
`ok`	boolean	—
`organization`	object	—
`organization.id`	string	—
`organization.name`	string	—
`scopes`	string[]	—

Ошибки

401 Ключ не передан или недействителен
429 Превышен лимит запросов

Формат тела ошибки — в разделе «Ошибки» обзора.

get

/api/v1/channelsлюбой действующий ключ

Каталог каналов

Список каналов каскада и их готовность. Читайте его вместо того, чтобы зашивать список каналов в код: новые каналы появляются здесь автоматически.

Ответ `200`Каналы

Поле	Тип	Описание
`channels`	object[]	—
`channels[].key`	"EMAIL" \| "SMS"	—
`channels[].slug`	string	—
`channels[].label`	string	—
`channels[].contactField`	string	—
`channels[].configured`	boolean	—
`channels[].sendEndpoint`	string	—

Ошибки

401 Ключ не передан или недействителен
429 Превышен лимит запросов

Формат тела ошибки — в разделе «Ошибки» обзора.

get

/api/v1/locationsправо locations:read

Список точек

Ответ `200`Точки организации

Поле	Тип	Описание
`locations`	object[]	—
`locations[].id`	string	—
`locations[].name`	string	—
`locations[].address`	string	—
`locations[].city`	string	—

Ошибки

401 Ключ не передан или недействителен
403 Ключу не выдано нужное право
429 Превышен лимит запросов

Формат тела ошибки — в разделе «Ошибки» обзора.

Контакты

Передача клиентов бизнеса из вашей системы

post

/api/v1/contactsправо contacts:write

Передать контакт клиента

Создаёт или обновляет контакт по вашему externalId. С флагом startCascade сразу ставит его в каскад — это самый короткий путь для интеграции с CRM: одно событие «заказ закрыт» → один вызов.

Заголовки

Idempotency-Key (необязательный) — Повтор запроса с тем же ключом вернёт сохранённый ответ и НЕ отправит сообщения повторно. Обязателен, если запрос инициирует вебхук вашей CRM с ретраями.

Тело запроса

JSON, заголовок Content-Type: application/json.

Поле	Тип	Описание
`externalId`	string	ID клиента в вашей системе — ключ дедупликации
`name`	string	—
`email`	string (email)	—
`phone`	string	—
`locationId`	string	—
`consentAt`	string (date-time)	Когда клиент дал согласие на коммуникацию
`attributes`	object	Произвольные поля вашей системы
`startCascade`	boolean	Сразу поставить контакт в каскад запроса отзыва (по умолчанию false)
`flowId`	string	Сценарий каскада; по умолчанию — сценарий организации

Ответ `200`Контакт сохранён

Поле	Тип	Описание
`contact`	object	—
`cascade`	object	(может быть null)
`cascade.id`	string	—
`cascade.queued`	integer	—

Ошибки

400 Некорректный запрос
401 Ключ не передан или недействителен
402 Тариф не позволяет операцию
403 Ключу не выдано нужное право
404 Объект не найден
409 Конфликт: повтор Idempotency-Key с другим телом или канал не настроен
429 Превышен лимит запросов

Формат тела ошибки — в разделе «Ошибки» обзора.

Каскады

Запуск и статус каскадных рассылок

get

/api/v1/flowsправо cascades:read

Сценарии каскада

Последовательности шагов «канал + задержка». Идентификатор сценария передаётся в POST /api/v1/cascades.

Ответ `200`Сценарии

Поле	Тип	Описание
`flows`	object[]	—
`flows[].id`	string	—
`flows[].name`	string	—
`flows[].isDefault`	boolean	—
`flows[].steps`	object[]	—
`flows[].steps[].order`	integer	—
`flows[].steps[].channel`	"EMAIL" \| "SMS"	—
`flows[].steps[].delayMinutes`	integer	—

Ошибки

401 Ключ не передан или недействителен
403 Ключу не выдано нужное право
429 Превышен лимит запросов

Формат тела ошибки — в разделе «Ошибки» обзора.

post

/api/v1/cascadesправо cascades:write

Запустить каскад

Ставит получателей в сценарий каскада. Шаги исполняются фоново: первый уходит сразу, следующие — по задержкам сценария, если клиент так и не поставил оценку.

Заголовки

Idempotency-Key (необязательный) — Повтор запроса с тем же ключом вернёт сохранённый ответ и НЕ отправит сообщения повторно. Обязателен, если запрос инициирует вебхук вашей CRM с ретраями.

Тело запроса

JSON, заголовок Content-Type: application/json.

Поле	Тип	Описание
`locationId`обяз.	string	—
`name`	string	—
`flowId`	string	Сценарий; по умолчанию — сценарий организации
`channel`	"EMAIL" \| "SMS"	Одношаговый каскад в один канал. Взаимоисключимо с flowId.
`externalId`	string	—
`recipients`обяз.	object[]	(от 1 до 500)
`recipients[].name`	string	—
`recipients[].email`	string (email)	—
`recipients[].phone`	string	—

Ответ `202`Каскад принят в работу

Поле	Тип	Описание
`id`	string	—
`status`	string	—
`queued`	integer	—
`skipped`	integer	—
`flow`	object	—

Ошибки

400 Некорректный запрос
401 Ключ не передан или недействителен
402 Тариф не позволяет операцию
403 Ключу не выдано нужное право
404 Объект не найден
409 Конфликт: повтор Idempotency-Key с другим телом или канал не настроен
429 Превышен лимит запросов

Формат тела ошибки — в разделе «Ошибки» обзора.

get

/api/v1/cascades/{id}право cascades:read

Статус каскада

Параметры пути

id

Ответ `200`Состояние каскада и получателей

Поле	Тип	Описание
`id`	string	—
`status`	string	—
`externalId`	string	(может быть null)
`counts`	object<integer>	—
`recipients`	object[]	—

Ошибки

401 Ключ не передан или недействителен
403 Ключу не выдано нужное право
404 Объект не найден
429 Превышен лимит запросов

Формат тела ошибки — в разделе «Ошибки» обзора.

post

/api/v1/review-requestsправо review-requests:write

Создать ссылку на отзыв

Возвращает персональную ссылку /r/<token>, которую вы отправите своими каналами. Отзыв и перехват негатива работают так же, как в каскаде.

Заголовки

Idempotency-Key (необязательный) — Повтор запроса с тем же ключом вернёт сохранённый ответ и НЕ отправит сообщения повторно. Обязателен, если запрос инициирует вебхук вашей CRM с ретраями.

Тело запроса

JSON, заголовок Content-Type: application/json.

Поле	Тип	Описание
`locationId`обяз.	string	—
`customerName`	string	—
`contact`	string	Email или телефон — только для вашей отчётности

Ответ `201`Ссылка создана

Поле	Тип	Описание
`id`	string	—
`token`	string	—
`url`	string	—
`status`	string	—

Ошибки

400 Некорректный запрос
401 Ключ не передан или недействителен
403 Ключу не выдано нужное право
404 Объект не найден
429 Превышен лимит запросов

Формат тела ошибки — в разделе «Ошибки» обзора.

Каналы

Методы отправки по конкретному каналу

post

/api/v1/channels/email/sendправо cascades:write

Отправить запрос отзыва: Email

Письмо со ссылкой на форму отзыва. Тема и текст берутся из шаблона организации, вёрстка и ссылка отписки — наши. Метод сгенерирован из реестра каналов — появляется автоматически при подключении нового канала.

Заголовки

Idempotency-Key (необязательный) — Повтор запроса с тем же ключом вернёт сохранённый ответ и НЕ отправит сообщения повторно. Обязателен, если запрос инициирует вебхук вашей CRM с ретраями.

Тело запроса

JSON, заголовок Content-Type: application/json.

Поле	Тип	Описание
`locationId`обяз.	string	Идентификатор точки; список — в GET /api/v1/locations
`name`	string	Название рассылки для истории в кабинете
`externalId`	string	Ваш идентификатор (номер заказа, ID сделки) — вернётся в ответах
`recipients`обяз.	object[]	(от 1 до 500)
`recipients[].name`	string	Имя клиента для подстановки {{name}}
`recipients[].email`обяз.	string	Email получателя

Ответ `202`Рассылка принята в работу

Поле	Тип	Описание
`id`	string	—
`status`	string	—
`channel`	"EMAIL"	—
`queued`	integer	—
`skipped`	integer	—

Ошибки

400 Некорректный запрос
401 Ключ не передан или недействителен
402 Тариф не позволяет операцию
403 Ключу не выдано нужное право
404 Объект не найден
409 Конфликт: повтор Idempotency-Key с другим телом или канал не настроен
429 Превышен лимит запросов

Формат тела ошибки — в разделе «Ошибки» обзора.

post

/api/v1/channels/sms/sendправо cascades:write

Отправить запрос отзыва: SMS

Короткое сообщение со ссылкой на форму отзыва. Текст — первая строка шаблона организации, обрезанная до одной SMS-части. Метод сгенерирован из реестра каналов — появляется автоматически при подключении нового канала.

Заголовки

Idempotency-Key (необязательный) — Повтор запроса с тем же ключом вернёт сохранённый ответ и НЕ отправит сообщения повторно. Обязателен, если запрос инициирует вебхук вашей CRM с ретраями.

Тело запроса

JSON, заголовок Content-Type: application/json.

Поле	Тип	Описание
`locationId`обяз.	string	Идентификатор точки; список — в GET /api/v1/locations
`name`	string	Название рассылки для истории в кабинете
`externalId`	string	Ваш идентификатор (номер заказа, ID сделки) — вернётся в ответах
`recipients`обяз.	object[]	(от 1 до 500)
`recipients[].name`	string	Имя клиента для подстановки {{name}}
`recipients[].phone`обяз.	string	Телефон получателя в любом формате — нормализуем сами

Ответ `202`Рассылка принята в работу

Поле	Тип	Описание
`id`	string	—
`status`	string	—
`channel`	"SMS"	—
`queued`	integer	—
`skipped`	integer	—

Ошибки

400 Некорректный запрос
401 Ключ не передан или недействителен
402 Тариф не позволяет операцию
403 Ключу не выдано нужное право
404 Объект не найден
409 Конфликт: повтор Idempotency-Key с другим телом или канал не настроен
429 Превышен лимит запросов

Формат тела ошибки — в разделе «Ошибки» обзора.

Служебные

Ответ 200Ключ действителен

Ошибки

Ответ 200Каналы

Ошибки

Ответ 200Точки организации

Ошибки

Контакты

Заголовки

Тело запроса

Ответ 200Контакт сохранён

Ошибки

Каскады

Ответ 200Сценарии

Ошибки

Заголовки

Тело запроса

Ответ 202Каскад принят в работу

Ошибки

Параметры пути

Ответ 200Состояние каскада и получателей

Ошибки

Заголовки

Тело запроса

Ответ 201Ссылка создана

Ошибки

Каналы

Заголовки

Тело запроса

Ответ 202Рассылка принята в работу

Ошибки

Заголовки

Тело запроса

Ответ 202Рассылка принята в работу

Ошибки

Ответ `200`Ключ действителен

Ответ `200`Каналы

Ответ `200`Точки организации

Ответ `200`Контакт сохранён

Ответ `200`Сценарии

Ответ `202`Каскад принят в работу

Ответ `200`Состояние каскада и получателей

Ответ `201`Ссылка создана

Ответ `202`Рассылка принята в работу

Ответ `202`Рассылка принята в работу