Частые вопросы

Эта страница систематизирует наиболее распространённые проблемы при интеграции. Начните с симптома, наиболее близкого к тому, что вы видите; схемы конечных точек, параметры и полные списки ошибок остаются в справочной документации.

Поиск по симптому

Что вы видите	Начните отсюда
У вас нет API key и вы не знаете, где его создать	Вызов API пока не работает
Выпуск токена не удаётся, или запросы возвращают 401 / 403	Вызов API пока не работает
Устройство отсутствует, или его состояние выглядит неактуальным	Данные устройства выглядят некорректно
Нужно непрерывно отслеживать периферию, отключения или потерю питания	Данные устройства выглядят некорректно
Команда была принята, но устройство не ответило или истекло время ожидания	Операция с устройством не завершилась как ожидалось
WebSocket не может подключиться, часто разрывается, или есть пробелы в событиях	Соединение в реальном времени нестабильно
Не уверены, использовать REST API или WebSocket	REST API или WebSocket
Запросы возвращают 429, 503 или недоступный шлюз	Запросы ограничены или сервис временно недоступен
Проблема сохраняется после изучения документации	Подготовьте детали для решения проблемы

Вызов API пока не работает

Как создать API Client и получить учётные данные?

Создайте API Client в Developer Console WLTE.

1. Войдите в Developer Console: https://developer.svnwi.com/wlte
2. Откройте приложение и перейдите в раздел управления API Client.
3. Создайте API Client и выберите минимально необходимые для интеграции права доступа.
4. Сохраните сгенерированные clientId и clientSecret.

При создании API Client вы получаете clientId и clientSecret, которые вместе используются для получения access token.

clientSecret отображается только при создании или смене. Немедленно сохраните его в хранилище секретов на стороне сервера. Если он утерян, замените секрет, так как исходное значение повторно увидеть нельзя. См. Получение API Keys.

Не удаётся выпустить access token

Проверьте эти пункты по порядку:

1. API Client существует и активен.
2. clientId и clientSecret принадлежат одному и тому же клиенту.
3. Приложение и учётная запись активны.
4. URL, метод и тело запроса соответствуют Создание access token (на английском).

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

Код ответа AUTH_INVALID

Учётные данные или текущее состояние их владельца недействительны. Частые причины: неверные учётные данные, отключённый или удалённый API Client, отключённое приложение или недопустимое состояние учётной записи.

Если вы недавно сменили секрет, убедитесь, что используете новый. Стройте логику ветвления на code, а не на message.

Код ответа AUTH_SCOPE_DENIED

У API Client нет права доступа, требуемого конечной точкой. data.requiredScope указывает недостающее право.

Добавьте это право в Developer Console, сохраните изменение, получите новый токен и повторите попытку. См. Права доступа (на английском).

Можно ли использовать старый токен после отключения или удаления API Client?

Нет. Защищённые конечные точки проверяют текущее состояние API Client, приложения и учётной записи, а не только истечение срока действия JWT.

После отключения или удаления клиента новые токены выпустить нельзя, а существующие отклоняются.

Можно ли хранить clientSecret на сайте или в мобильном приложении?

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

Храните учётные данные на сервере под вашим контролем. Не записывайте clientSecret, access token или тикеты WebSocket в код фронтенда, публичные репозитории или логи.

Данные устройства выглядят некорректно

Устройство отсутствует в списке

Сначала убедитесь, что устройство принадлежит текущей учётной записи и API Client имеет к нему доступ.

Если устройство отображается в Developer Console, но не в API, проверьте предоставленные доступы к устройству и область доступа device:read. Если причина остаётся неясной, запишите requestId перед обращением в поддержку.

Состояние из списка не соответствует физическому устройству прямо сейчас

Список устройств возвращает состояние, уже синхронизированное платформой. Он не обновляет активно каждое физическое устройство при каждом запросе списка и предназначен для списков, панелей мониторинга и массового чтения.

Для явного обновления пользователем или до/после операции используйте Получение устройства (на английском) или запрос состояния через WebSocket.

Можно ли часто опрашивать HTTP для отслеживания периферии, отключений или питания?

Не рекомендуется. Состояние периферии, состояние отключения и события питания — это данные, ориентированные на реальное время. Частый опрос HTTP значительно увеличивает нагрузку на обновление устройств и повышает вероятность достижения лимитов запросов.

Рекомендуемый подход:

1. Используйте Список устройств (на английском) для списков, панелей мониторинга и фоновой синхронизации.
2. Используйте Получение устройства (на английском) или device.state.get через WebSocket, когда пользователь явно обновляет страницу деталей одного устройства.
3. Используйте события WebSocket для непрерывного мониторинга изменений отключения, питания и периферии; после переподключения повторно подтвердите критичное состояние через HTTP или device.state.get.

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

deviceType имеет значение UNSUPPORTED

Платформа пока не предоставляет пригодное для использования определение типа для этого устройства. Устройство может по-прежнему принадлежать учётной записи, но клиент не должен предполагать, что его схема состояния или возможности управления доступны.

Не выводите возможности из префикса ID устройства.

Как узнать, поддерживает ли устройство операцию?

Прочитайте Список определений типов устройств (на английском) и изучите capabilities.supportedOperations.

Отображать или вызывать следует только перечисленные там операции. Например, не показывайте передачу RS485, если нет device.rs485.transceive.

Операция с устройством не завершилась как ожидалось

Ответ — COMMAND_ACCEPTED, но устройство не отреагировало

COMMAND_ACCEPTED означает, что платформа приняла запрос. Это не означает, что устройство завершило операцию.

Ориентируйтесь на статус команды: SUCCESS означает, что устройство подтвердило операцию; TIMEOUT означает, что окончательное подтверждение не поступило вовремя. Используйте Получение результата команды (на английском) для восстановления состояния предыдущей команды.

Команда в статусе TIMEOUT. Точно ли устройство её не выполнило?

Не обязательно. Возможно, устройство не получило команду, либо выполнило её, пока подтверждение задержалось или было потеряно.

Не повторяйте команду вслепую. Сначала прочитайте текущее состояние устройства, особенно для операций, которые небезопасно дублировать.

Код ответа COMMAND_REJECTED

Сначала проверьте два момента:

1. Определение типа устройства включает запрошенную операцию.
2. Параметры соответствуют возможностям устройства, например, допустимый индекс реле.

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

Нужно ли использовать новый Idempotency-Key при повторной попытке?

Переиспользуйте исходный ключ при повторной попытке той же бизнес-операции после сбоя сети. Разные устройства, разные целевые состояния или разные бизнес-операции требуют разных ключей.

Не используйте один фиксированный ключ для всех запросов. См. Поведение HTTP (на английском).

Соединение в реальном времени нестабильно

WebSocket не может установить соединение

Убедитесь, что access token действителен, затем создайте новый wsTicket. Тикет короткоживущий и одноразовый, его нельзя кэшировать или использовать повторно.

См. Создание WebSocket Ticket, затем Установление соединения (оба на английском).

Как клиенту восстановиться после разрыва соединения?

Переподключайтесь с задержкой (backoff) и создавайте новый тикет для каждого нового соединения. После переподключения перезагружайте нужное состояние, а не предполагайте, что события за период отключения будут полностью воспроизведены.

См. Heartbeat и переподключение (на английском).

Приходят дублирующиеся события, или кажется, что некоторые пропущены

Обработка событий должна быть идемпотентной. WebSocket уведомляет клиента об изменениях и не должен быть единственным постоянным источником состояния.

После перезагрузки страницы, переподключения или обнаружения пробела в состоянии запросите состояние через REST API или запрос состояния через WebSocket, чтобы установить новую базовую точку.

Запросы ограничены или сервис временно недоступен

Ответ — HTTP 429

Остановите немедленные повторные попытки. Прочитайте Retry-After и повторите попытку по истечении разрешённого времени. Согласуйте задержку между экземплярами вашего сервиса, чтобы избежать очередного синхронизированного всплеска.

Обновление в реальном времени и управление устройствами ограничены строже, чем запросы синхронизированного состояния. См. Лимиты запросов и повторные попытки (на английском).

Ответ — 503 или GATEWAY_UNAVAILABLE

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

Если ситуация сохраняется, прекратите повторные попытки и подготовьте детали для обращения в поддержку.

Подготовьте детали для решения проблемы

Если проблема сохраняется, соберите:

Информация	Пример или указание
requestId	ID трассировки запроса из ответа API
ID API Client	Никогда не включайте clientSecret
Метод и путь запроса	GET /wlte/v1/devices
Временная метка UTC	Точное время возникновения проблемы
Статус HTTP и бизнес-code	Например, 403 / AUTH_SCOPE_DENIED
Очищенные параметры	Удалите пароли, токены и персональные данные

Затем отправьте обращение через Связаться с поддержкой.