API Evidra

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

Если вы только начинаете — идите в быстрый старт: три запроса покрывают типовую интеграцию с CRM.

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

Машиночитаемая спецификация — OpenAPI 3.1. Её можно отдать генератору клиентов и не писать HTTP-обвязку руками. Справочник на этом сайте собирается из неё же, поэтому они не расходятся.

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

Authorization: Bearer evd_live_…

Если конструктор интеграций не умеет составной заголовок, подойдёт X-Api-Key: evd_live_… — оба варианта равнозначны.

Организация определяется ключом. Ни один метод не принимает идентификатор организации в запросе — его нельзя ни передать, ни подменить. Точки, сценарии и каскады видны только те, что принадлежат организации ключа.

При выпуске ключа выбираются права. Метод, требующий права, которого у ключа нет, вернёт 403 insufficient_scope. Права крупные, по ресурсу, а не по методу — так проще выдать «читать точки + ставить каскады», чем собирать матрицу из десятка галочек.

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

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

Это обязательно, если вызов инициирует вебхук вашей CRM с автоматическими повторами: без ключа каждый повтор — ещё одна рассылка тем же людям. Повтор с тем же ключом, но другим телом отклоняется с 409 conflict.

Idempotency-Key: order-10423

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

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

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

Формат ошибки один на все методы — обработчик пишется один раз:

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

code — машинный и стабильный, по нему ветвитесь в коде. message — человекочитаемый, на русском, может меняться без предупреждения. details есть только у ошибок валидации.

Выпустить ключ и читать справочники можно на любом тарифе. Запуск каскада — то есть отправка сообщений клиентам — доступен на оплаченном тарифе с подтверждённым email; на пробном периоде такие методы вернут 402 plan_required. Это защита от спама с одноразовых аккаунтов, а не ограничение интеграции: как только тариф оплачен, тот же код начинает работать без изменений.