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

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

Все методы лежат под одним адресом. Запросы и ответы приходят в JSON. Формат ошибок общий. У каждого метода указано право ключа. Без него метод вернёт 403.

Служебные

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

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" \| "MAX" \| "TELEGRAM"	—
`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 сразу ставит его в каскад. Один закрытый заказ — один вызов.

Заголовки

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" \| "MAX" \| "TELEGRAM"	—
`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" \| "MAX" \| "TELEGRAM"	Одношаговый каскад в один канал. Взаимоисключимо с flowId.
`externalId`	string	—
`recipients`обяз.	object[]	(от 1 до 2000)
`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 до 2000)
`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 до 2000)
`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 Превышен лимит запросов

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

post

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

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

Сообщение в MAX с рабочего аккаунта Evidra. Уходит первым по номеру телефона. Текст берётся из шаблона SMS, первой строкой стоит название локации. Метод берётся из реестра каналов. Новый канал появляется здесь сам.

Заголовки

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

Тело запроса

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

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

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

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

Ошибки

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

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

post

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

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

Сообщение в Telegram с рабочего аккаунта Evidra. Уходит по номеру телефона. Текст берётся из шаблона SMS, первой строкой стоит название локации. Метод берётся из реестра каналов. Новый канал появляется здесь сам.

Заголовки

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

Тело запроса

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

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

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

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

Ошибки

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

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

Служебные

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

Ошибки

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

Ошибки

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

Ошибки

Контакты

Заголовки

Тело запроса

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

Ошибки

Каскады

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

Ошибки

Заголовки

Тело запроса

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

Ошибки

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

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

Ошибки

Заголовки

Тело запроса

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

Ошибки

Каналы

Заголовки

Тело запроса

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

Ошибки

Заголовки

Тело запроса

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

Ошибки

Заголовки

Тело запроса

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

Ошибки

Заголовки

Тело запроса

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

Ошибки

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

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

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

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

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

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

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

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

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

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

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

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