API и интеграции — REST, вебхуки, задачи

Публичный REST API

Полноценный REST API по адресу /api/v1/* с аутентификацией по API-ключу. Управляйте чатом, миссиями, задачами, заметками, интеграциями и расписанием из любого HTTP-клиента.

Создайте API-ключ в дашборде. Ключи имеют префикс asb_ (64 hex символа, хранятся как SHA-256 хеш). Передавайте ключ в заголовке X-API-Key. Опционально: укажите область видимости (full, chat, webhook) и дату истечения.

Основные эндпоинты

POST /api/v1/chat — Чат с AI

GET /api/v1/missions — Список / запуск миссий

GET /api/v1/tasks — Список задач

GET /api/v1/notes — Список заметок

GET /api/v1/events — Журнал событий

POST /api/v1/schedule — Управление задачами по расписанию

POST /api/v1/keys/create — Управление API-ключами

POST /api/v1/webhooks/outgoing/register — Управление вебхуками

Исходящие вебхуки

Подпишитесь на события AI и получайте HTTP POST уведомления на ваш URL. Каждый вебхук подписывается HMAC-SHA256 — проверяйте подлинность на своей стороне.

Типы событий

mission_created — Создана новая миссия
task_completed — Задача завершена
ai_message — Сообщение AI в чате
reminder_triggered — Напоминание сработало
note_created — Создана заметка
scheduled_trigger — Задача по расписанию выполнена
integration_connected — Интеграция подключена

Каждый вебхук содержит заголовок X-ASI-Signature — HMAC-SHA256 от тела запроса, подписанный секретным ключом. Таймаут доставки — 15 секунд; без ответа HTTP 200 доставка считается неудачной. Автоматических повторов нет — эндпоинт должен быть идемпотентным.

Задачи по расписанию (Cron)

Планируйте выполнение AI-промптов по cron-расписанию. Укажите промпт и время — AI выполнит задачу, сохранит результат в заметки и пришлёт отчёт.

Примеры

0 * * * * — Каждый час

0 9 * * 1-5 — По будням в 9:00

0 8 * * 1 — Каждый понедельник в 8:00

Фоновый воркер проверяет задачи каждые 60 секунд. При срабатывании AI выполняет промпт, сохраняет ответ как заметку и генерирует событие scheduled_trigger (перехватывается вебхуками).

Система событий

Система событий — это центральная шина сообщений, соединяющая все компоненты ASI Biont. Построенная на архитектуре asyncio.Queue, она обеспечивает надёжную асинхронную доставку событий по всей платформе.

Архитектура

События помещаются в in-memory asyncio.Queue
Фоновый воркер обрабатывает события одно за другим
Каждое событие логируется в таблицу event_logs для аудита
Обработчики регистрируются через декоратор @EventSystem.on('event_type')

Формат события

{
    "user_id": 42,
    "event_type": "task_completed",
    "payload": {
        "task_id": 123,
        "title": "Analyze sales data",
        "status": "completed"
    }
}

Встроенные обработчики

Outgoing Webhooks — Доставляет события на зарегистрированные URL вебхуков с подписью HMAC-SHA256
Event Logging — Сохраняет каждое событие в БД для аудита и отладки

SSH и COM-порты

AI ASI Biont может подключаться к удалённым серверам через SSH и общаться с оборудованием через последовательные порты. SSH-подключения выполняются в безопасной Python-песочнице; доступ к COM-портам идёт через Hardware Bridge — отдельное приложение (bridge.py), запущенное на ПК пользователя.

SSH (paramiko)

AI использует библиотеку paramiko для подключения к любому SSH-серверу. Credentials хранятся в зашифрованном виде (AES-256) через credential_set и никогда не попадают в код AI.

По умолчанию только read-only команды (логи, мониторинг, диагностика)
Деструктивные команды — только с явного разрешения пользователя
Защита от SSRF — подключения к private IP (10.x, 192.168.x, 127.0.0.1) блокируются
Таймаут 30 секунд — зависшие соединения автоматически обрываются

COM-порты — Hardware Bridge

AI общается с устройствами через последовательные порты с помощью Hardware Bridge — отдельного приложения bridge.py, запущенного на ПК пользователя. Bridge подключается к ASI Biont через WebSocket (единственный канал связи) и обеспечивает доступ к COM-портам локально через pyserial. AI отправляет команды через industrial_command — они уходят на bridge пользователя, который читает/пишет в COM-порт.

Arduino, ESP32, ESP8266 — чтение датчиков, управление пинами
Промышленные контроллеры — Modbus RTU, RS-232/RS-485
GPS-приёмники — чтение NMEA-данных
Любые USB-serial устройства — считыватели штрихкодов, принтеры чеков, терминалы
Атомарная операция serial_write_and_read — запись и чтение за один вызов, без риска таймаута
HELP протокол — отправь serial_write_and_read(data="48454c500a") для получения списка команд устройства
Кроссплатформенность: Windows (CancelIoEx + PurgeComm fallback), Linux, macOS