HTTP

Интеграция HTTP отправляет каждый uplink устройств приложения POST-запросом на заданный вами адрес. В теле — JSON того же вида, что сообщение realtime_data WebSocket API. Внешней системе достаточно HTTP-сервера, который принимает POST-запросы: соединение с WebSocket API для этого не нужно. Интеграция работает в одну сторону — отправить через неё downlink нельзя. Интеграцию настраивают на странице приложения в веб-интерфейсе; у приложения может быть одна интеграция HTTP.

Как подключить

Откройте приложение в разделе «Приложения» веб-интерфейса. Блок «Интеграции» есть только на странице созданного приложения, на странице создания его нет.
В блоке «Интеграции» на карточке HTTP нажмите «Add».
Заполните поля, см. таблицу ниже. Обязательное — «Endpoint».
Включите переключатель «Active». У новой интеграции он выключен, а выключенную интеграцию сервер не запускает.
Нажмите «Сохранить». Неверный адрес форма отмечает, но сохранить не мешает: без «Endpoint» сервер интеграцию не сохранит, а адрес без http:// или https:// или без имени хоста сохранит, но интеграцию не запустит — у уже работающей интеграции останутся прежние настройки.

Сохранённые настройки сервер применяет сразу, без перезапуска сервиса: перезапускает интеграцию с новой конфигурацией. Изменить настройки можно кнопкой «Edit» на карточке, удалить интеграцию — кнопкой «Удалить» с подтверждением. Кнопка «Add» видна, только пока у приложения нет интеграции HTTP.

Поля интеграции

Подписи формы — на английском и в русском интерфейсе. Поля сгруппированы в разделы «Connection Settings», «HTTP Headers», «Basic Authentication» и «Integration Control». При редактировании ниже есть раздел «Status & History», см. Состояние и история запросов.

Поле	Что задаёт
«Endpoint»	Адрес, на который сервер отправляет запросы. Должен начинаться с `http://` или `https://`, иначе форма покажет «Endpoint must start with http or https». Адрес с другой схемой или без имени хоста сервер сохраняет, но интеграцию с ним не запускает. Сервер отправляет запрос на адрес в точности как он записан: ничего не добавляет ни к пути, ни к параметрам
«Verify SSL Certificate»	Проверка сертификата вашего HTTP-сервера при `https`. Включено по умолчанию. Выключенный переключатель отменяет проверку и сертификата, и имени хоста; форма предупреждает «SSL verification disabled - use only for testing», сервер пишет предупреждение в свой журнал
«HTTP Headers»	Свои заголовки запроса. Чтобы добавить заголовок, введите «Header name» и «Header value» и нажмите «Add» — кнопка активна, когда заполнены оба поля. Карандаш меняет только значение; чтобы переименовать заголовок, удалите его и добавьте заново. Строки можно перетаскивать
«Basic Authentication»: «Username», «Password»	Учётные данные для заголовка `Authorization: Basic`. Раздел необязательный (пометка «optional») и раскрывается щелчком по заголовку. Если свернуть раздел, оба поля очищаются. С пустым «Username» сервер заголовок `Authorization` не добавляет
«Active»	Включает интеграцию. У новой интеграции выключено

Значения заголовков, в имени которых есть authorization, api-key, x-api-key, token, secret или password (без учёта регистра), форма скрывает (у значений длиннее 6 символов видны первые и последние два символа); значок «глаз» их показывает.

Endpoint — адрес, на который сервер отправляет запросы; обязательное поле.
Verify SSL Certificate — проверка сертификата вашего HTTP-сервера при https, включено по умолчанию.
HTTP Headers — добавленные заголовки: строку можно перетащить, карандаш меняет значение, корзина удаляет заголовок.
Значок «глаз» — показывает скрытое значение заголовка, здесь X-API-Key.
Header name, Header value и Add — добавить заголовок; кнопка активна, когда заполнены оба поля.
Basic Authentication — необязательный раздел с полями «Username» и «Password», раскрывается щелчком по заголовку.
Active — включает интеграцию; у новой интеграции выключено.
Сохранить — сохраняет интеграцию, сервер сразу применяет настройки.

Запрос: адрес и заголовки

На каждый uplink сервер отправляет один запрос POST на адрес из «Endpoint». Заголовки запроса:

Заголовок	Значение
Заголовки из «HTTP Headers»	Значения — как заданы в форме; регистр букв в имени сервер меняет: `X-API-Key` уйдёт как `X-Api-Key`
`User-Agent`	`OnsHTTPClient`
`Content-Type`	`application/json`, без `charset`
`Authorization`	`Basic <base64 от «username:password» в UTF-8>`. Только если заполнено «Username»

User-Agent, Content-Type и Authorization: Basic сервер ставит после заголовков из формы и заменяет ими заголовки с теми же именами.

Чтобы передать токен, оставьте «Username» пустым и добавьте заголовок в «HTTP Headers», например Authorization: Bearer <токен> или X-API-Key: <ключ>.

Тело запроса

Тело — JSON того же вида, что сообщение realtime_data WebSocket API: cmd со значением realtime_data, devEui, devAddr, data (кадр, параметры приёма, результат JS-кодека, теги), battery_level, margin, join_request_time. Поля execResult и execError есть, только если у приложения настроен JS-кодек. Значения всех полей — в описании сообщения realtime_data.

{
    "cmd": "realtime_data",
    "devEui": "6F1E570FFE14DBFC",
    "devAddr": "78130AE1",
    "data": {
        "datr": 5,
        "rssi": -97,
        "lsnr": 8.5,
        "data": "0A1B2C3D4E5F6071",
        "freq": 868.9,
        "time": "2026-10-08T09:47:18.528002",
        "ack": false,
        "size": 21,
        "gatewayId": "0000B827EBFD64DE",
        "adr": true,
        "fcnt": 1542,
        "mtype": 2,
        "fopts": "",
        "fport": 2,
        "packet_loss_rate": 0,
        "execResult": {
            "errors": [],
            "warnings": [],
            "data": {
                "temperature": 21.5
            }
        },
        "execError": null,
        "tags": {
            "building": "A"
        }
    },
    "battery_level": 100.0,
    "margin": 9,
    "join_request_time": "2026-10-01T06:12:40.114233Z"
}

Символы вне ASCII — например, кириллица в тегах или в результате кодека — приходят экранированными: \u0410 вместо «А».

Сервер отправляет каждый принятый uplink — подтверждаемый и неподтверждаемый — от устройств своего приложения и приложений из поля «Доступные приложения». Других сообщений интеграция не отправляет.

Ответ и повторы

Сервер ждёт заголовков ответа 5 секунд; срок не настраивается.

Ответ	Что делает сервер
Код меньше 400, в том числе 3xx	Считает uplink доставленным и отправляет следующий
Код 400 и больше	Ошибка `HTTP error <код>: <текст статуса>`, повтор того же uplink
Нет ответа за 5 секунд	Ошибка `Request to <адрес> timed out after 5 seconds`, повтор. Сам запрос сервер не отменяет: ваш HTTP-сервер может его обработать, и тогда uplink придёт дважды
Ошибка соединения или TLS	Повтор того же uplink

При повторе сервер перестаёт читать очередь интеграции, выжидает паузу и отправляет тот же uplink снова. Паузы — около 20, 40, 80 и 160 секунд, затем каждый раз 300 секунд (5 минут); к каждой паузе добавляется до 10 %. Предела попыток нет. После успешного ответа отсчёт пауз начинается заново.

Запросы интеграция отправляет по одному: следующий — только после ответа на предыдущий. Поэтому скорость отправки ограничена временем ответа вашего HTTP-сервера: если он отвечает за 0,5 секунды, интеграция отправит не больше двух uplink в секунду.

Тело ответа сервер не использует и в историю запросов не записывает, но читает — требования к нему в разделе «Как принимать запросы».

Как принимать запросы

Отвечайте кодом 2xx на каждый запрос, даже если сообщение не удалось разобрать. Ответ 4xx или 5xx сервер будет повторять без конца. Ошибку разбора запишите у себя.
Отвечайте быстрее 5 секунд: сохраните сообщение, ответьте и только потом обрабатывайте.
Отвечайте 204 No Content или 200 с пустым или коротким телом в UTF-8. Тело не в UTF-8 ломает доставку: запрос считается ошибкой или не завершается вовсе — тогда интеграция перестаёт отправлять uplink без повторов, а на карточке остаётся Connected. Ответ без Content-Length и без chunked-кодирования, конец которого обозначен закрытием соединения, сервер тоже считает ошибкой. Обычные веб-фреймворки передают Content-Length или chunked сами.
Убирайте дубликаты, например по паре devEui и data.fcnt: после тайм-аута тот же uplink придёт повторно.

Состояние и история запросов

Значки в заголовке карточки HTTP показывают, включена ли интеграция (переключатель), и её состояние:

Состояние	Что значит для HTTP
Connected, зелёная галочка	Интеграция включена и готова отправлять запросы. Доступность вашего HTTP-сервера это не подтверждает: Connected появляется сразу после включения, даже если адрес не отвечает
Disconnected, жёлтый крестик	У включённой интеграции — пауза перед повтором после неудачного запроса. Причина — в «Recent Requests»
Error, красный треугольник	На практике не появляется: после неудачного запроса сервер сразу записывает Disconnected

Блок «Интеграции» на странице приложения

Переключатель — интеграция включена (зелёный) или выключена (серый, как у ThingsBoard.io).
Состояние — здесь Disconnected, жёлтый крестик: пауза перед повтором после неудачного запроса. У MQTT — Connected, зелёная галочка.
Edit — открывает форму интеграции и раздел «Status & History».
Удалить — удаляет интеграцию после подтверждения.

Раздел «Status & History» открывается кнопкой «Edit»:

Элемент	Что показывает
Состояние	Connected или Disconnected, как на карточке
Счётчик с галочкой	Число успешных запросов
Счётчик с крестиком	Число ошибок. Считает только до первой успешной доставки, после неё показывает 0
«Last success»	Время последнего успешного запроса
«Recent Requests»	Последние 5 запросов: время, код ответа или `ERR`, длительность в миллисекундах. Щелчок по строке показывает текст ошибки и JSON запроса

Успешный запрос записан с кодом 200, какой бы код меньше 400 ни вернул ваш HTTP-сервер; тела ответа в истории нет.
Неудачный запрос записан как ERR с текстом ошибки: HTTP error 500: Internal Server Error, Request to … timed out after 5 seconds или ошибка соединения.
История хранится 24 часа с последнего запроса: если сутки не было uplink, она пуста. Если нет ни состояния, ни истории, раздел показывает «No data yet. Status and history will appear after device uplinks are processed.»
Данные загружаются при открытии страницы приложения и после сохранения или удаления интеграции. Чтобы увидеть свежие, обновите страницу в браузере.

Пример: HTTP-сервер ответил 503, повтор не дождался ответа за 5 секунд, интеграция ждёт следующей попытки:

Раздел «Status & History» интеграции HTTP

Состояние — Disconnected: пауза перед повтором.
Счётчик с галочкой — число успешных запросов.
Счётчик с крестиком — число ошибок; после первой успешной доставки показывает 0.
Last success — время последнего успешного запроса.
Recent Requests — строка запроса: время, код ответа или ERR, длительность в миллисекундах. Щелчок раскрывает строку.
Error — текст ошибки, здесь Request to … timed out after 5 seconds.
Request — JSON запроса.

Выключение и удаление

Выключенная интеграция не отправляет запросы, но uplink для неё копятся на сервере. После включения сервер отправит всё накопленное — возможно, большой пачкой старых uplink.
Очередь без чтения живёт 14 дней. По умолчанию очередь удаляется вместе с данными, если её не читают 14 дней. Потерянные uplink можно забрать командой get_data_req.
Удаление интеграции HTTP её очередь не удаляет. Uplink продолжают копиться, пока очередь не пролежит 14 дней без чтения. Новая интеграция HTTP того же приложения, созданная в этот срок, первым делом отправит накопленное.
Выключение может сработать не сразу. Если выключить, удалить или пересохранить интеграцию во время паузы перед повтором, то по окончании паузы — через время до 5,5 минуты — сервер может снова начать отправлять запросы с прежними настройками. То же бывает, если в этот момент запрос ждал ответа и затем завершился ошибкой. Проверьте по журналу своего HTTP-сервера, что запросы прекратились.

Отправить данные на устройство

Интеграция HTTP не принимает команд downlink и не присылает статусы кадров. Чтобы поставить кадр в очередь устройству, используйте команду WebSocket API downlink_data_req или интеграцию MQTT: она принимает команды downlink из брокера. У приложения может быть и интеграция HTTP, и интеграция MQTT.

Что важно знать

Ошибка задерживает все uplink этой интеграции. Пока ваш HTTP-сервер отвечает кодом 400 и больше или не отвечает, интеграция повторяет один и тот же uplink, а новые uplink ждут в очереди за ним. WebSocket API и другие интеграции получают данные как обычно.
Ответ 3xx — это доставка. Перенаправления сервер не выполняет: uplink считается доставленным, а по новому адресу запрос не уходит. Укажите в «Endpoint» окончательный адрес.

См. также

Приложения — страница приложения, блок «Интеграции» и поле «Доступные приложения».
Подписаться на данные в реальном времени — поля сообщения realtime_data.
MQTT — интеграция, через которую можно и получать uplink, и ставить в очередь downlink.
downlink_data_req — поставить данные в очередь на отправку устройству.
get_data_req — uplink-пакеты из базы за период.

Как подключить​

Поля интеграции​

Запрос: адрес и заголовки​

Тело запроса​

Ответ и повторы​

Как принимать запросы​

Состояние и история запросов​

Выключение и удаление​

Отправить данные на устройство​

Что важно знать​

См. также​