API заявок

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

Общие правила — выпуск ключа, права, безопасность — в статье API для разработчиков.

Базовый адрес

https://api.app.rentra.ai/functions/v1/ops-public-api/v1

Версия в пути обязательна. Контракт v1 не меняется без предупреждения: новые поля в ответах появляться могут, существующие не исчезают и не меняют смысл. Запрос к неизвестной версии вернёт 400 unsupported_version.

Авторизация

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

Authorization: Bearer rta_ваш_ключ

Нужное право выбирается при выпуске ключа в поле «Заявки (публичный API)»:

• чтение (tickets:read) — методы GET;
• чтение + ответы (tickets:write) — плюс отправка сообщений и смена статуса.

Организация определяется самим ключом. Передавать её в запросе не нужно — и нельзя: чужие заявки не видны, а запрос по идентификатору чужой заявки вернёт 404, а не 403 (мы не подтверждаем даже сам факт её существования).

Повторные вызовы

Изменяющие запросы принимают заголовок Idempotency-Key с вашим собственным идентификатором операции:

Idempotency-Key: crm-42-reply-1

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

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

Методы

Список заявок

GET /tickets

Требует tickets:read. Заявки отсортированы от новых к старым.

Параметры запроса (все необязательные):

Параметр	Описание
status	Точное совпадение статуса: new, assigned, in_progress, done, completed, confirmed, cancelled
department	Код отдела, как он задан у вас в кабинете, — например housekeeping
limit	Сколько вернуть. По умолчанию 50, максимум 200

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

{
  "tickets": [
    {
      "id": "aee515cb-d4c4-4c4f-a1cc-be3a218f69fb",
      "department": "housekeeping",
      "status": "new",
      "task_description": "Просьба заменить полотенца (номер 306)",
      "origin": "guest",
      "guest_rating": null,
      "target_due_at": "2026-07-31T09:30:00+00:00",
      "created_at": "2026-07-31T08:52:33.462887+00:00",
      "updated_at": "2026-07-31T08:52:33.462887+00:00"
    }
  ]
}

Поля заявки:

Поле	Значение
id	Идентификатор заявки, используется во всех остальных методах
department	Отдел-исполнитель
status	Текущий статус
task_description	Суть заявки — то, что видно в карточке в кабинете
origin	Откуда пришла заявка: guest — от гостя, staff — заведена сотрудником, internal — внутренняя работа (плановое обслуживание и т.п.)
guest_rating	Оценка гостя после закрытия, null — пока не оценена
target_due_at	Срок, к которому заявку нужно закрыть, null — срок не задан
created_at, updated_at	Время создания и последнего изменения

Все отметки времени — ISO 8601 в UTC, с микросекундами и явным смещением +00:00. Разбирайте их полноценным парсером даты, а не сравнением строк.

Постраничного обхода нет

limit ограничен 200 записями, а параметров offset, курсора или фильтра «изменённые после» у метода нет. Выгрузить всю историю заявок через этот API не получится: он рассчитан на работу с текущей очередью — опрашивайте по фильтру status, а закрытые заявки складывайте у себя по мере обработки.

Вебхуков тоже нет — платформа сама вас не вызывает, единственный способ узнать о новых заявках и сообщениях — опрос.

Одна заявка с перепиской

GET /tickets/{id}

Требует tickets:read. Возвращает заявку и всю переписку по ней от старых сообщений к новым.

Набор полей заявки почти тот же, что в списке, с двумя отличиями: добавляется comments — внутренний комментарий из карточки, и не отдаётся target_due_at. Если переписки по заявке ещё нет, messages придёт пустым массивом.

curl "https://api.app.rentra.ai/functions/v1/ops-public-api/v1/tickets/aee515cb-d4c4-4c4f-a1cc-be3a218f69fb" \
  -H "Authorization: Bearer rta_ваш_ключ"

{
  "ticket": {
    "id": "aee515cb-d4c4-4c4f-a1cc-be3a218f69fb",
    "department": "housekeeping",
    "status": "in_progress",
    "task_description": "Просьба заменить полотенца (номер 306)",
    "comments": null,
    "origin": "guest",
    "guest_rating": null,
    "created_at": "2026-07-31T08:52:33.462887+00:00",
    "updated_at": "2026-07-31T09:05:10.118204+00:00"
  },
  "messages": [
    {
      "id": "1f0c7a2e-1f4b-4d0c-9a41-0b0f2d9a55c1",
      "author_type": "guest",
      "author_name": "Айдана",
      "body": "Можно ещё одно полотенце?",
      "visible_to_guest": true,
      "created_at": "2026-07-31T08:52:33.907413+00:00"
    }
  ]
}

Поля сообщения:

Поле	Значение
author_type	Кто написал: guest — гость, staff — сотрудник или внешняя система, ai — AI-консьерж, system — платформа
author_name	Отображаемое имя автора
body	Текст сообщения
visible_to_guest	true — гость это сообщение видит, false — внутренняя заметка
created_at	Время отправки

Вложения через этот API не отдаются: если гость приложил к заявке фото, в messages придёт только текст. Фотографии видны в карточке заявки в кабинете.

Сообщение в заявку

POST /tickets/{id}/messages

Требует tickets:write.

Поле	Обязательное	Значение
body	да	Текст сообщения
visible_to_guest	нет	true — показать сообщение гостю. По умолчанию false: сообщение остаётся внутренней заметкой
author_name	нет	Имя автора для ленты заявки. По умолчанию API

curl -X POST "https://api.app.rentra.ai/functions/v1/ops-public-api/v1/tickets/aee515cb-d4c4-4c4f-a1cc-be3a218f69fb/messages" \
  -H "Authorization: Bearer rta_ваш_ключ" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-42-reply-1" \
  -d '{"body": "Полотенца принесём в течение 15 минут", "visible_to_guest": true, "author_name": "Служба поддержки"}'

{ "success": true, "message_id": "ce7e5553-23d2-4b24-9f49-2073c749c32b" }

Сообщение попадает в ленту заявки в кабинете и помечается как пришедшее из внешней системы — сотрудник видит, что ответ ушёл не из кабинета.

Уведомление гостю не отправляется

visible_to_guest: true делает сообщение видимым на странице заявки — гость увидит его, когда откроет заявку. Пуш или сообщение в тот канал, где гость с вами общается, при этом не уходит: их отправляет только ответ из кабинета.

Если гость должен узнать об ответе сразу, отвечайте из кабинета, а через API переносите служебный контекст и статусы. Мы уберём эту разницу — следите за разделом «Что нового».

Внутренние заметки

Если не передать visible_to_guest, сообщение увидят только сотрудники. Удобно, чтобы переносить в заявку контекст из своей системы, не показывая его гостю.

Смена статуса

POST /tickets/{id}/status

Требует tickets:write.

curl -X POST "https://api.app.rentra.ai/functions/v1/ops-public-api/v1/tickets/aee515cb-d4c4-4c4f-a1cc-be3a218f69fb/status" \
  -H "Authorization: Bearer rta_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"status": "done"}'

{ "success": true, "status": "done" }

Допустимые значения: new, assigned, in_progress, done, completed, cancelled. Любое другое вернёт 400 со списком разрешённых. Смена статуса записывается в журнал операций с пометкой, что пришла из внешней системы.

В чтении может встретиться ещё исторический статус confirmed — учитывайте его при разборе ответов, но выставить его через API нельзя.

Ошибки

Ответ	Причина
400 unsupported_version	Версия в пути отличается от v1
400 body_required	В сообщении не передан текст
400 invalid_status	Недопустимый статус; в поле allowed — разрешённые значения
401 unauthorized	Ключ не передан, отозван, просрочен или не существует
403 forbidden	У ключа нет нужного права; в поле need — какое именно
404 not_found	Заявки с таким идентификатором в вашей организации нет
500 internal_error	Ошибка на нашей стороне, запрос можно повторить

Типовой сценарий

Как обычно выглядит связка со сторонней службой поддержки:

1. Раз в минуту забираете GET /tickets?status=new и заводите у себя тикеты по новым заявкам.
2. По каждому — GET /tickets/{id}, чтобы подтянуть переписку.
3. Оператор отвечает у себя → вы шлёте POST /tickets/{id}/messages с visible_to_guest: true и своим Idempotency-Key. Помните, что уведомление гостю при этом не уходит — см. предупреждение выше.
4. Оператор закрывает тикет → POST /tickets/{id}/status со статусом done.

Сообщения гостя, пришедшие после вашего ответа, появятся в GET /tickets/{id} при следующем опросе.

Персональные данные

Через этот API из платформы уходит переписка с гостями: имена, тексты сообщений, иногда номер и детали проживания. Как только данные оказались в вашей CRM, за их хранение и защиту отвечаете вы: платформа не контролирует, где и сколько они там живут.

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