API hub для разработчиков
Полная спецификация OpenAPI 3.1 открыта на hub.projio.ru/docs: все адреса, модели ответов, коды ошибок и вебхуки. Файл спецификации лежит в репозитории hub: docs/openapi.json.
Доступ
| Кому | Заголовок |
|---|---|
| Приложение | Authorization: Bearer hub_… |
| Админка | X-Admin-Key: … |
| Сервер сайта | X-Site-Key: … |
В /docs нажмите Authorize, вставьте ключ — и запросы можно пробовать прямо на странице.
Ошибки
Ответ с ошибкой всегда одного вида:
{"detail": "Диалог не найден.", "code": "not_found"}
detail — что не так словами, его можно показать человеку. code — машинный код, по нему программа решает, что делать.
| HTTP | code | Когда |
|---|---|---|
| 400 | invalid |
Действие сейчас невозможно: канал не работает, сообщение ещё не ушло |
| 401 | unauthorized |
Нет ключа или ключ неверный |
| 404 | not_found |
Нет такого объекта или он чужой |
| 409 | conflict |
Объект в неподходящем состоянии |
| 413 | too_large |
Файл слишком большой |
| 415 | unsupported_type |
Тип файла не принимается |
| 422 | invalid_request |
Запрос не прошёл проверку; в errors — какие поля и почему |
| 500 | internal |
Ошибка hub, повторите позже |
| 503 | unavailable |
Раздел выключен на сервере |
Основные запросы
GET /v1/chats— диалоги, от новых к старым. Следующая страница —before=<lastMessageAt последнего>.GET /v1/chats/{id}/messages— история диалога.POST /v1/messages— отправить. Повтор с тем жеclientMessageIdне создаёт второе сообщение.GET /v1/events?after=<id>— события по курсору.
Вебхуки
hub отправляет события приложению POST-запросом: {"id", "type", "createdAt", "data"}. Типы: message.created, message.updated, channel.updated, channel.imported.
Заголовок X-Hub-Signature: sha256=… — HMAC-SHA256 тела секретом приложения. Проверяйте подпись перед обработкой. Ответ 2xx — событие принято. Иначе hub повторяет с растущей паузой, до 12 попыток. Непринятое остаётся в GET /v1/events.
Изменение API
После изменения API разработчик обновляет файл спецификации командой python -m app openapi > docs/openapi.json. Тест в CI не пропустит сборку, если файл расходится с кодом. Новые поля в ответах добавляются без поломки старых клиентов.