Как получить токен API и настроить вебхуки

Токен компании открывает внешним программам доступ к данным филиала через API RentProg. Вебхуки работают в обратную сторону: RentProg сам сообщает вашей программе, что бронирование, клиент или транспортное средство создано, изменено или удалено.

Обе настройки — в профиле компании, вкладка «Интеграции», панели «Токен для доступа к API» и Webhooks.

Кому доступно

Что	Условие
Панель «Токен для доступа к API»	Доступ к API: услуга API в тарифе и доступ не отключён администрацией RentProg
Скопировать и обновить токен	Менеджер и выше; партнёрам и гостям поле не показывается
Панель Webhooks	Доступ к API, отдельно включённый доступ к вебхукам и услуга вебхуков в тарифе
Добавлять, менять и удалять ссылки для вебхуков	Сотрудники компании
Видеть секрет подписи вебхука	Сотрудники компании; партнёрам и гостям не показывается

Как скопировать токен

1. Откройте профиль компании, вкладка «Интеграции», панель «Токен для доступа к API».
2. Нажмите поле «API Токен» или значок копирования в нём — токен попадёт в буфер обмена.

Токен свой у каждого филиала. Тот же токен нужен внешним сервисам, например форме бронирования на сайте.

Как обновить токен

1. Нажмите «Обновить токен» в панели «Токен для доступа к API».
2. Подтвердите обновление.
3. Скопируйте новый токен и замените его во всех внешних сервисах.

Важно

При обновлении токена все внешние сервисы, использующие старый токен, перестанут работать. Старый токен восстановить нельзя.

Как программа входит в API

Программа меняет токен компании на временный ключ доступа, а затем передаёт его в заголовке Authorization каждого запроса:

GET /api/v1/public/get_token?company_token=<токен компании>

Временный ключ действует 4 часа. Ограничения частоты запросов:

• обычное чтение — 120 запросов в минуту, отдельно на компанию и на IP-адрес; оба ограничения действуют одновременно;
• запись — 60 запросов в минуту, отдельно на компанию и на IP-адрес; оба ограничения действуют одновременно;
• free_cars_with_price, search_clients, search_bookings, search_cars, icalendar_event и active_bookings_icalendar — общий отдельный лимит 30 запросов в минуту на IP-адрес;
• получение временного ключа через get_token — 60 запросов в минуту на IP-адрес.

Важно

Если доступ к API отключён, сервер отвечает отказом и просит обратиться в поддержку. Если подписка компании отключена за неоплату, API тоже отвечает отказом до пополнения баланса компании.

Как добавить ссылку для вебхуков

1. Раскройте панель Webhooks и нажмите «Добавить ссылку для вебхуков».
2. Впишите адрес вашей программы в поле «URL для вебхуков».
3. Выберите события в поле «Подписки на события» — хотя бы одно.
4. Включите «Только созданные через API» или «Только обновленные через API», если нужны только записи, пришедшие через API.
5. Нажмите значок сохранения с подсказкой «Сохранить ссылку для вебхуков».

Без адреса или без событий ссылка не сохранится. Адрес проверяется на формат.

События для подписки: «Бронирование создано», «Бронирование обновлено», «Бронирование удалено», «Клиент создан», «Клиент обновлен», «Клиент удален», а также создание, изменение и удаление транспортного средства.

Ссылка принадлежит филиалу, в котором её создали: события приходят по записям этого филиала.

Как проверить подпись доставки

После сохранения у ссылки появляется поле секрета подписи. Секрет создаётся один раз при создании ссылки и не меняется при её правке. Скопируйте его значком копирования и храните на стороне вашей программы.

Каждая доставка — это запрос POST с телом в формате JSON:

{"event": "booking_create", "payload": "<данные записи в виде строки JSON>"}

Заголовки доставки:

Заголовок	Что в нём
X-Webhook-Signature	sha256= и подпись тела запроса по алгоритму HMAC-SHA256 секретом ссылки
X-Webhook-Event-Id	ID события
Idempotency-Key	Тот же ID события — одинаковый у всех повторов и переотправок

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

Когда доставка считается неудачной

Ответ вашей программы	Что делает RentProg
200, 201 или 204	Доставка успешна
408, 429, обрыв соединения или нет ответа за 10 секунд	Повторяет доставку с растущей паузой, всего до 8 попыток; после последней — ошибка
404	Отмечает ошибку и деактивирует ссылку
Ошибка защищённого соединения	Отмечает ошибку без повторов
Любой другой код	Отмечает ошибку без повторов

Важно

Ответ 404 выключает ссылку целиком: дальше события на неё не отправляются, пока вы её не активируете.

Как переотправить ошибочные доставки

1. Раскройте панель Webhooks и найдите блок «Последние ошибки вебхуков».
2. Проверьте у события адрес и код ответа, при необходимости исправьте вашу программу.
3. Нажмите «Переотправить» у события.

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

Как управлять ссылкой

У сохранённой ссылки есть значки:

• «Обновить ссылку для вебхуков» — сохранить изменённый адрес, события или переключатели;
• «Деактивировать ссылку для вебхуков» — временно перестать отправлять события;
• «Активировать ссылку для вебхуков» — снова включить отправку;
• «Удалить ссылку для вебхуков» — удалить ссылку вместе с историей её событий, после подтверждения.