REST API и вебхуки для разработчика

Всё, что доступно в кабинете, доступно и через REST API: запуск кампаний, импорт баз, версии сценариев, списки звонков и выгрузки. API — для тех, кто встраивает обзвоны в свой процесс: CRM запускает кампанию, ERP забирает результаты, роботизация на вашей стороне.

Коммерческий обзор возможностей — на странице «Платформа для разработчиков»; эта статья — про практику вызовов.

Подключение

1. Менеджер выдаёт базовый адрес API и токен вида rcd_… (персональный, по ролям — как пользователи кабинета).
2. Токен передаётся в заголовке каждого запроса.
3. Полная спецификация OpenAPI (схемы всех методов) прилагается к доступу — она же используется для генерации клиентов под ваш язык.

Токен — секрет: храните в секрет-хранилище, не в коде и не в репозитории.

Группы методов

Основные сущности API повторяют кабинет:

• кампании — создание, запуск/пауза/стоп, прогресс, сводные отчёты;
• сценарии — версии, активация, валидация DSL (битый сценарий отклоняется с указанием узла и причины);
• контакты и базы — импорт (тот же CSV с маппингом колонок, что и в кабинете), списки, правка фактов;
• звонки и диалоги — списки с фильтрами, карточки с транскриптами и переменными, выгрузки CSV;
• каналы — управление ботами и текстовыми каналами;
• вебхуки — подписки на события.

Имена полей и коды ответов — в спецификации; ниже — только скелет вызова:

POST {base}/api/v1/campaigns
Authorization: Bearer rcd_…

{"name": "Напоминания-октябрь", "scenario_id": "…", "base_ids": ["…"]}

Лимиты и ошибки

• Ставка запросов ограничена (защита от случайных циклов); при превышении API отвечает 429 с заголовком Retry-After — повторяйте с задержкой, а не в лоб.
• Ошибки валидации — 422 с текстом по-русски: то же сообщение, что показал бы кабинет, можно показывать пользователю вашей системы.
• Времена — ISO 8601, часовой пояс UTC.

Вебхуки событий

Подписайтесь на события диалогов — платформа будет присылать HTTP POST на ваш URL по ходу разговора: статусы звонка, распознанные реплики, результаты узлов, переменные.

Каждый запрос подписан: заголовок с HMAC-подписью тела запроса, ключ — отдельный секрет вебхука (не токен API). Проверяйте подпись до разбора тела:

X-Rechedar-Signature: sha256=<hex HMAC от тела запроса>

Порядок и повторы:

• события несут сквозной номер (seq) — по нему видно пропуски и дубли;
• дубликаты подавляются платформой при повторной доставке, но ваш обработчик должен быть идемпотентным (по event id);
• ваш сервер должен ответить 2xx быстро; тяжёлую обработку — в очередь, не в обработчик вебхука.

Куда звонит платформа

Вебхуки платформа шлёт только на адреса из вашего списка — при подключении согласуйте URL. Внутренние адреса и «серые» диапазоны отклоняются политикой платформы.

Дальше

• Готовые коннекторы вместо своего кода: интеграции.
• Обработка данных внутри платформы: плагины.