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

API Evidra

CRM, сайт или касса передают контакт клиента в Evidra. Evidra запускает запрос отзыва. Оценку клиента и сбой доставки Evidra присылает на ваш адрес.

Что можно сделать

Передать контакт и сразу поставить его в каскад. Одно событие «заказ закрыт» — один вызов.
Запустить каскад для списка получателей по сценарию организации или в один канал.
Получить персональную ссылку на отзыв, чтобы отправить её своими каналами.
Узнать статус каскада: кому что ушло, кто открыл, кто поставил оценку.
Получать события вебхуками: завершение каскада по клиенту, доставка и сбой сообщения.

Для первой интеграции откройте быстрый старт. Там три запроса.

Базовый адрес — https://evidra.ru/api/v1. Запросы и ответы приходят в JSON, UTF-8. Даты записаны в ISO 8601 с часовым поясом. Версия указана в пути. Несовместимые изменения выйдут отдельной версией.

Машиночитаемая спецификация — OpenAPI 3.1. Из неё можно собрать клиент. Справочник на сайте собран из той же спецификации.

Авторизация

Ключ выпускается в кабинете: Разработчикам → Ключи API. Он показывается один раз. Сохраните его в секретах своей системы. Ключ передаётся в заголовке:

HTTP

Authorization: Bearer evd_live_…

Конструктор без составного заголовка принимает X-Api-Key: evd_live_…. Оба варианта равнозначны.

Организацию определяет ключ. Идентификатор организации в запрос не передаётся. Локации, сценарии и каскады видны только у организации этого ключа.

Ключ открывает данные клиентов. Не вставляйте его в код браузера и не пересылайте в чатах. Отозванный ключ перестаёт работать сразу.

Права ключа

При выпуске ключа выбираются права. Метод без нужного права вернёт 403 insufficient_scope. Права выдаются по ресурсу, не по каждому методу.

Право	Что разрешает	По умолчанию
`locations:read`	Читать локации. Список локаций и их идентификаторы для поля locationId.	да
`contacts:write`	Передавать контакты. Создание и обновление контактов клиентов.	да
`cascades:write`	Запускать каскады. Запуск каскада запроса отзыва и отправка сообщений.	да
`cascades:read`	Читать статусы каскадов. Статус отправки и ответ клиента.	да
`review-requests:write`	Создавать ссылки на отзыв. Персональная ссылка /r/<token> для отправки своими каналами.	нет

Какое право нужно конкретному методу — указано у каждого метода в справочнике. Служебные методы (/ping, /channels) доступны любому действующему ключу.

Идемпотентность

Методы, которые отправляют сообщения, принимают заголовок Idempotency-Key. Это строка до 255 символов. Берите номер заказа или ID сделки. Повтор с тем же ключом в течение 24 часов вернёт сохранённый ответ и не отправит сообщения повторно.

Заголовок нужен, если вызов идёт из вебхука CRM. Без него каждый повтор отправит ещё одну рассылку. Повтор с тем же ключом и другим телом вернёт 409 conflict.

HTTP

Idempotency-Key: order-10423

Лимиты

Не больше 120 запросов в минуту на ключ. Текущее состояние — в заголовках каждого ответа:

HTTP

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1756576800

При превышении придёт 429 rate_limited с заголовком Retry-After в секундах. За один вызов каскада можно передать до 2000 получателей — для больших списков разбивайте на пачки.

Ошибки

Формат ошибки один для всех методов. Обработчик пишется один раз.

application/json

{
  "error": {
    "code": "invalid_request",
    "message": "Проверьте параметры запроса",
    "details": [
      { "field": "recipients.0.email", "message": "Некорректный email" }
    ]
  }
}

code стабилен. По нему ветвится код. message написан по-русски и может измениться. details есть только у ошибок валидации.

code	HTTP	Когда
`unauthorized`	401	Ключ не передан, не найден или отозван
`insufficient_scope`	403	Ключу не выдано право, которое требует метод
`forbidden`	403	Операция запрещена для организации (например, не подтверждён email)
`invalid_request`	400	Ошибка валидации — конкретные поля в details
`not_found`	404	Локация, сценарий или каскад не найдены в вашей организации
`conflict`	409	Повтор Idempotency-Key с другим телом
`channel_unavailable`	409	Канал не настроен на стороне Evidra
`plan_required`	402	Тариф ниже «Оптимального» или в сценарии только SMS без баланса
`rate_limited`	429	Превышен лимит запросов; см. Retry-After
`internal_error`	500	Ошибка на нашей стороне — повторите позже

Доступ по тарифу

Ключ и справочники доступны на любом тарифе. Запуск каскада доступен с тарифа «Оптимальный», включая пробные дни. Нужен подтверждённый email. Без денег на SMS шаг SMS пропускается. MAX и Telegram уходят. Тариф ниже «Оптимального» или сценарий только из SMS без баланса вернут 402 plan_required.