Транспортный API

Транспортный API — набор HTTP-эндпоинтов, через которые информационные системы отправляют и получают сообщения. Все запросы требуют авторизации — см. Авторизация.

Базовый префикс: /api/exchange

Отправка сообщения

POST /api/exchange/send/{messageClass}
Authorization: Bearer <accessToken>
Content-Type: application/json

<тело сообщения в формате JSON>

messageClass — класс сообщения, зарегистрированный в DataHUB. Тело запроса — JSON-конверт целиком.

Ответы:

Код	Значение
`200 OK`	Сообщение принято и поставлено в очередь
`400 Bad Request`	Некорректный формат тела
`401 Unauthorized`	Токен истёк или недействителен
`404 Not Found`	Класс сообщения не найден

Получение сообщения (short-polling)

GET /api/exchange/receive
Authorization: Bearer <accessToken>

Ответы:

Код	Значение
`200 OK`	Сообщение получено; тело ответа — JSON-конверт
`204 No Content`	Нет сообщений в очереди
`401 Unauthorized`	Токен истёк

Получение сообщения (long-polling)

GET /api/exchange/receive-long-polling
Authorization: Bearer <accessToken>

Сервер удерживает соединение до появления сообщения или истечения таймаута.

Ответы:

Код	Значение
`200 OK`	Сообщение получено
`204 No Content`	Таймаут истёк раньше HTTP-таймаута клиента (нет сообщений)
`408 Request Timeout`	HTTP-таймаут long-polling истёк (нет сообщений); нормальная ситуация, продолжить цикл
`401 Unauthorized`	Токен истёк

408 при long-polling — штатный ответ, означающий, что за период ожидания сообщений не поступило. Адаптер должен обрабатывать его так же, как 204: продолжить цикл получения.

Подтверждение получения (ACK)

POST /api/exchange/ack/{ackId}
Authorization: Bearer <accessToken>

ackId — идентификатор сообщения из поля Id конверта, полученного через /receive.

ACK должен отправляться после фиксации сообщения в локальном хранилище, а не внутри той же транзакции. Это исключает потерю сообщения при сбое базы данных между ACK и коммитом.

Ответы:

Код	Значение
`200 OK`	Подтверждение принято; сообщение удалено из очереди
`404 Not Found`	AckId не найден (сообщение уже подтверждено или истёк TTL)
`401 Unauthorized`	Токен истёк

Служебные эндпоинты

GET /api/exchange/whoami
Authorization: Bearer <accessToken>

Возвращает имя текущей системы в DataHUB. Используется для проверки авторизации.

GET /api/exchange/echo/{message}

Эхо-тест без авторизации. Возвращает переданную строку.

Порядок работы адаптера

Получение:
1. GET /receive или GET /receive-long-polling
2. При 200: сохранить локально (BEGIN TX → INSERT → COMMIT TX)
3. После COMMIT: POST /ack/{Id}
4. Повторить с шага 1

Отправка:
1. Сформировать JSON-конверт
2. POST /send/{messageClass}
3. При 200: записать статус «Отправлено»
4. При ошибке: повторить согласно политике retry