Введение

Эта страница закладывает базовую модель перед началом интеграции. Она не перечисляет все параметры каждой конечной точки (endpoint), а объясняет основные объекты, шаблоны запросов, модель состояния устройства и жизненный цикл команд, используемые в WLTE OpenAPI.

Если вы хотите сразу выполнить первый запрос, перейдите к разделу Быстрый старт.

Что такое WLTE OpenAPI?

WLTE OpenAPI создан для серверных систем. Он позволяет вашей платформе читать данные устройств WLTE, управлять ими и отслеживать их состояние.

Типичные возможности:

• Получение списка устройств, доступных учётной записи
• Чтение состояния одного устройства и данных его периферии
• Загрузка определений типов устройств и поддерживаемых операций
• Отправка команд реле, RS485 и команд конфигурации
• Запрос результатов команд
• Получение событий устройств в реальном времени через WebSocket

Основные понятия

Понятие	Описание
API Client	Идентификатор вызывающей стороны, создаётся в Developer Console для одного приложения
clientId / clientSecret	Учётные данные на стороне сервера, используемые для получения access token
Access token	Короткоживущий токен для вызова защищённых конечных точек
Устройство (Device)	Устройство WLTE, доступное учётной записи
Тип устройства (Device Type)	Определение, описывающее поддерживаемую периферию и операции
Состояние периферии (Peripheral State)	Состояние реле, цифровых входов, датчиков, аналоговых входов и другой периферии
Команда (Command)	Запрос на выполнение одной операции с устройством, например управление реле, передача RS485 или обновление конфигурации
Событие WebSocket	Уведомление в реальном времени об изменениях состояния, подключения, событиях питания и подобном

Модель интеграции

Ваш сервер должен хранить clientSecret и получать access token. Браузеры, мобильные приложения и другие клиенты не должны хранить clientSecret напрямую.

REST API и WebSocket

REST API и WebSocket не заменяют друг друга. Они выполняют разные задачи.

Сценарий	Рекомендуемый способ
Получить access token	REST API
Получить список устройств	REST API
Загрузить определения типов устройств	REST API
Отправить команды устройству	REST API или WebSocket, в зависимости от вашей модели соединения
Запросить результаты команд	REST API
Явно обновить одно устройство	REST API GET /devices/{deviceId} или WebSocket device.state.get
Отслеживать подключение, отключение, питание или изменения состояния	WebSocket

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

См. REST API или WebSocket для более подробного сравнения.

Модель состояния устройства

Состояние устройства следует интерпретировать в зависимости от сценария использования.

Данные	Сценарий использования	Описание
Состояние из списка устройств	Списки, панели мониторинга, фоновая синхронизация	Данные, уже синхронизированные платформой, подходят для массового отображения
Состояние одного устройства в реальном времени	Обновление страницы деталей, проверка до/после операции	Сервер пытается активно обновить это устройство
События WebSocket	Непрерывный мониторинг состояния	Уведомления в реальном времени об изменениях подключения, событиях питания, изменениях периферии и подобном

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

Модель команд

Команды устройств обычно проходят через две фазы:

1. Платформа принимает запрос.
2. Устройство подтверждает окончательный результат, либо истекает время ожидания.

Распространённые статусы:

Статус	Значение
SUCCESS	Устройство подтвердило результат
TIMEOUT	Окончательное подтверждение не поступило в течение окна ожидания
FAILED	Команда завершилась неудачей или была явно отклонена
SENT	Команда отправлена, но ещё не имеет финального статуса; обычно встречается при запросе уже существующей команды

TIMEOUT не доказывает, что устройство не выполнило команду. Оно могло выполнить её, пока подтверждение задержалось или было потеряно. Для команд с побочными эффектами не повторяйте запрос вслепую после тайм-аута. Сначала прочитайте текущее состояние устройства, затем принимайте решение.

Модель прав доступа и безопасности

API Client использует области доступа (scopes) для контроля доступа. Общие правила:

• Запросы только для чтения обычно требуют device:read
• Управление устройством обычно требует device:control
• Настройка устройства обычно требует device:config
• Управление устройствами (администрирование) обычно требует device:manage

Если запрос возвращает AUTH_SCOPE_DENIED, в ответе указывается недостающее право доступа. Обновите права API Client в Developer Console и получите новый access token.

Границы безопасности:

• Храните clientSecret только на своём сервере
• Не записывайте clientSecret, access token или WebSocket-тикеты в код фронтенда, публичные репозитории или логи
• После отключения или удаления API Client существующие токены отклоняются
• После смены секрета обновите его на своём сервере и получите новый токен

Рекомендуемый путь интеграции

1. Создайте API Client в Developer Console.
2. Используйте Bruno для проверки аутентификации, получения списка устройств и запроса состояния одного устройства.
3. Загрузите определения типов устройств, чтобы подтвердить поддерживаемую периферию и операции.
4. Выберите REST API, WebSocket или оба варианта в зависимости от рабочего процесса вашего продукта.
5. Интегрируйтесь со своего сервера, используя SDK или прямые вызовы HTTP/WebSocket.
6. Перед выходом в продакшн проверьте права доступа, лимиты запросов, повторные попытки, идемпотентность и защиту логов от утечек.

Следующий шаг: перейдите к разделу Быстрый старт.