Rocketly API

Используйте webhook и управление источниками, чтобы безопасно передавать лиды из веб-форм в Rocketly.

Ключевые возможности

Безопасная аутентификация

Управляющие эндпоинты защищены JWT, а входящий webhook проверяется ключом источника. Не помещайте управляющий токен в браузер; если ключ раскрыт, обновите его в настройках источника.

Приём входящих лидов

Передавайте данные формы или серверной интеграции в аутентифицированный источник webhook.

Управление источниками

Пользователи с доступом могут создавать и просматривать источники, а также настраивать поля.

Здоровье источника

Проверяйте состояние источника за последние 24 часа и проблемные доставки.

Интеграция webhook

Используйте URL webhook и скрипт отслеживания, созданные для каждого источника.

Журналы доставок

Просматривайте входящие запросы и находите неуспешные доставки по каждому источнику.

Эндпоинты API

Webhook и интеграция форм

POST/api/webhook/lead/{api_key}Получить лид из веб-формы

GET/api/webhook/sourcesСписок источников webhook

POST/api/webhook/sourcesСоздать источник webhook

GET/api/webhook/sources/{source_id}/healthПроверить состояние источника за 24 часа

GET/api/webhook/sources/{source_id}/logsПросмотреть журналы доставок источника

GET/api/webhook/tracker.jsСкрипт отслеживания сайта

Безопасный запуск

Эта страница описывает интеграцию Rocketly для приёма входящих лидов. Управляющие эндпоинты требуют входа, доступной функции тарифа и разрешения settings.integrations.

Создайте источник. В Настройки > Интеграции создайте источник webhook; созданный URL принимает только входящие лиды.
Проверьте доставку. Отправьте тестовые данные с сервера или из формы на POST /api/webhook/lead/{api_key}.
Проверьте здоровье и журналы. Посмотрите журналы доставок и состояние источника за 24 часа; если ключ раскрыт, сгенерируйте новый.

Пример использования

cURL - Создание лида

curl -X POST https://api.gorocketly.com/api/webhook/lead/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Иван",
    "last_name": "Иванов",
    "phone_raw": "+79991234567",
    "email": "[email protected]",
    "status": "Открыт"
  }'

Аутентификация

Существует два отдельных способа аутентификации: токен сессии или персональный токен доступа (PAT) для управляющих эндпоинтов и ключ конкретного источника для входящего webhook-эндпоинта.

Персональный токен доступа. Токен выпускается с префиксом fl_pat_ и показывается ровно один раз — при создании; на сервере хранится только его хеш. Передавайте его в одном из двух заголовков: Authorization: Bearer fl_pat_… или X-API-Key: fl_pat_….
Области доступа (scopes). Если список областей пуст, токен получает доступ в объёме собственных прав пользователя. Если области заданы, действующее право — это ПЕРЕСЕЧЕНИЕ с правами пользователя: область не может выдать право, которого у пользователя нет. Поддерживаются шаблоны вида leads.* и *; нераспознанная область отклоняется с кодом 422.
Срок действия и отзыв. Поле expires_in_days принимает значения от 1 до 365 дней; если оставить пустым, токен бессрочный. Токен немедленно отзывается запросом DELETE /api/pat/{token_id}. Недействительные или отозванные учётные данные возвращают 401 с заголовком WWW-Authenticate: Bearer.
Входящий webhook-эндпоинт. Этот эндпоинт проверяет запрос по ключу источника в URL, а не по подписи тела. Ключ выпускается с префиксом flwh_, хранится в виде SHA-256-хеша и сравнивается за постоянное время (timing-safe). Отдельного заголовка подписи нет, поэтому относитесь к webhook-URL как к секрету и обновляйте его в настройках источника при подозрении на утечку.
Дополнительные ограничения. Для каждого источника можно задать список разрешённых IP-адресов и доменов; запрос извне этих списков получает 403.

Персональные токены доступа

POST/api/patСоздать токен (открытое значение возвращается один раз)

GET/api/patСписок токенов в маскированном виде

DELETE/api/pat/{token_id}Отозвать токен

Ограничения частоты запросов

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

Входящий эндпоинт лидов. 60 запросов в минуту на ключ источника. При превышении возвращается 429 с заголовком Retry-After: 60.
Общая квота. Для остальных эндпоинтов по умолчанию действует 100 запросов в минуту; у некоторых эндпоинтов лимит строже.
Заголовки. Каждый ответ содержит X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset; ответ 429 дополнительно содержит Retry-After.
Тело ответа 429. Содержит поля error, limit, remaining и retry_after. Перед повтором дождитесь значения Retry-After.
Размер тела. Входящий запрос лида не должен превышать 100 КБ; более крупный запрос отклоняется с кодом 413.

Ответы и коды ошибок

Входящий эндпоинт лидов сообщает бизнес-результат в поле status тела ответа, а не в HTTP-коде; успешный запрос всегда возвращает 200.

created. Создан новый лид; в теле возвращается lead_id.
updated. Запись распознана как дубликат; новая запись не создаётся, обновляется существующий лид и возвращается его lead_id.
spam. Запрос помечен как спам; лид не создаётся.
error. Требуется хотя бы одно из полей — телефон или эл. почта; если нет ни одного, в теле возвращается success: false.
Коды ошибок. 400 нечитаемое или некорректное тело · 403 вне списка разрешённых IP/доменов · 404 недействительный или отключённый ключ webhook · 413 тело превышает 100 КБ · 429 превышение частоты запросов.
Открытие в браузере. Запрос GET по тому же URL не создаёт лид; эндпоинт возвращает информационный JSON с описанием ожидаемого тела.

Версионирование

Все эндпоинты публикуются под базовым путём /api. Новые поверхности добавляются под явным префиксом /api/v2 без нарушения работающих путей; существующие пути, такие как /api/webhook/…, остаются на месте. Храните базовый адрес в интеграции как единственное значение конфигурации и не зашивайте префиксы путей в код.

Начните сейчас

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

Бесплатная регистрация