API для разработчиков

Если ваша команда хочет связать RentraAI со своими системами — у платформы есть REST API. Эта статья про то, как получить доступ и как устроена авторизация. Подробный справочник методов работы с заявками — в отдельной статье API заявок.

Что можно делать через API

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

Шаг 1. Выпустить ключ

Ключи живут в Настройки → AI и администрирование → API Keys. Раздел открыт только владельцу и администраторам — если вкладки не видно, попросите выпустить ключ того, у кого есть эта роль.

1. Нажмите «Create Key» и дайте ключу понятное имя — по нему потом видно, какая интеграция его использует.
2. Выберите права:
   • Права в платформе — только чтение, чтение и запись или полный доступ. Это про сервисный API.
   • Заявки (публичный API) — нет доступа, чтение или чтение + ответы. Отдельное поле, по умолчанию выключено.
3. Укажите срок действия: 30, 90, 365 дней или бессрочно.
4. Скопируйте ключ. Он начинается с rta_ и показывается ровно один раз: в базе хранится только его необратимый отпечаток, восстановить значение невозможно.

Доступ к заявкам выдаётся отдельно

Ключ с полным доступом к платформе не открывает переписку с гостями, пока в поле «Заявки (публичный API)» не выбрано право явно. Это сделано намеренно: ключ, выданный когда-то для выгрузки броней, не должен однажды получить доступ к личным сообщениям гостей.

В таблице ключей видно префикс, права, срок и дату последнего использования — по ней легко понять, какие ключи уже никто не вызывает. Кнопка удаления отзывает ключ мгновенно.

Шаг 2. Авторизоваться

Базовый адрес всех запросов:

https://api.app.rentra.ai/functions/v1

Дальше есть два способа авторизации — какой нужен, зависит от контура.

Заявки: ключ передаётся напрямую

Никакого обмена и никаких промежуточных токенов: ключ идёт в заголовке, срок жизни у него тот, который вы задали при выпуске.

curl "https://api.app.rentra.ai/functions/v1/ops-public-api/v1/tickets?limit=5" \
  -H "Authorization: Bearer rta_ваш_ключ"

Сервисный API: ключ меняется на часовой токен

# 1. Получить токен
curl -X POST "https://api.app.rentra.ai/functions/v1/api-auth/token" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "rta_ваш_ключ"}'

В ответе — токен, срок его жизни и права:

{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scopes": ["read", "write"],
  "product_type": "hotel"
}

Дальше токен передаётся в каждом запросе — так же, как ключ в примере выше:

Authorization: Bearer eyJhbG...

Токен живёт 1 час, потом нужно получить новый. Обмен ключа на токен ограничен 10 запросами в минуту с одного адреса — это защита от перебора ключей, а не рабочий лимит. Получайте токен один раз и переиспользуйте его до истечения срока, а не перед каждым вызовом.

Проверить действующий токен можно через POST /api-auth/verify с тем же заголовком Authorization — ответ покажет организацию, права и время истечения.

Поле product_type в ответе говорит, с каким типом бизнеса связан ключ: hotel (отели), short_term (краткосрочная аренда), long_term (долгосрочная аренда). От него зависит и терминология, и состав доступных методов.

Права ключа

Право	Что открывает
read	Чтение в сервисном API: брони, услуги, задачи
write	Изменение: создание и отмена броней, задачи, контакты, лиды
admin	Полный доступ к сервисному API
tickets:read	Чтение заявок и переписки
tickets:write	Ответы гостю и смена статуса заявки (включает чтение)

Права в платформе и права на заявки независимы: admin не подразумевает tickets:*, а tickets:write не даёт доступа к броням.

Коды ошибок

Код	Что означает
400	Некорректный запрос: не хватает обязательного поля или значение недопустимо. В теле ответа — что именно не так
401	Ключ или токен не передан, просрочен, отозван либо не существует
403	У ключа нет нужного права. В теле ответа поле need — какое право требуется
404	Объекта нет. Заявка чужой организации тоже отдаётся как 404
429	Слишком частые запросы (обмен ключа на токен). Повторите через минуту
500	Ошибка на нашей стороне. Запрос можно повторить

Тело ошибки — всегда JSON, например:

{ "error": "forbidden", "need": "tickets:read" }

Безопасность

• Ключ — это доступ к данным вашей организации. Храните его там же, где остальные секреты (переменные окружения, хранилище секретов), и не кладите в репозиторий и не пересылайте в мессенджерах.
• Отдельный ключ на каждую интеграцию. Тогда при компрометации или отключении подрядчика вы отзываете один ключ, а не останавливаете все интеграции сразу.
• Ограничивайте права. Интеграции, которая только выгружает заявки в отчёт, достаточно tickets:read.
• Ставьте срок действия. Бессрочный ключ живёт до тех пор, пока про него кто-нибудь не вспомнит.
• Ключ утёк — удалите его и выпустите новый. Отзыв действует сразу, следующий же запрос с этим ключом получит 401.

Что дальше

• API заявок — полный справочник методов с примерами.
• Страница «API» в кабинете (/app/api) — базовый адрес вашего контура с кнопкой копирования и справочные материалы для разработчика.

Если что-то не сходится — например, метод отвечает не так, как здесь написано, — напишите менеджеру RentraAI: эта статья и есть источник, который мы поддерживаем в актуальном состоянии.