Description

n8n-nodes-n8n-nodes-lirax

LiraX VOIP Nodes for n8n
n8n Nodes для Интеграции с LiraX
Обзор
Этот проект предоставляет полную интеграцию между платформой автоматизации рабочих процессов n8n и системой телефонии и CRM LiraX. Он включает поддержку голосовых звонков, SMS-сообщений, IVR, контактов, управления звонками и расширенных операций CRM.

Версия: 1.0.0
Автор: PRAGMA (info@pragma.by)
Репозиторий: GitHub (предполагаемый URL на основе анализа проекта)
Лицензия: MIT

Основные возможности
Полная двусторонняя связь с LiraX через API и веб-хуки.

Поддержка телефонии: исходящие/входящие звонки, управление вызовами, записи разговоров и IVR.

Интеграция с CRM: контакты, сделки, задачи, заметки и аналитика.

Отправка/получение SMS, отслеживание статуса доставки.

Расширенный IVR с многоуровневыми меню и захватом ввода пользователя.

Безопасность: валидация токенов веб-хуков, проверка SSL-сертификатов, обработка ошибок.

Высокая доступность: повторные попытки (retry) с экспоненциальной задержкой, circuit breaker, кэширование и идемпотентность.

Автоматическая нормализация номеров телефонов и валидация параметров с использованием Zod-схем.

Кэширование для loadOptions (пользователи, магазины, статусы) с TTL.

Логирование с трассировкой стека ошибок и аналитикой производительности.

Требования
Node.js ≥ 18.17.0

n8n ≥ 1.112.6 (2025-09-26)

Доступ к LiraX API версии 4.45 (или совместимой)

Установка
Через Community Nodes (рекомендуется)
В n8n перейдите в Settings > Community Nodes.

Найдите n8n-nodes-lirax.

Нажмите Install и перезапустите n8n.

Ручная установка
Клонируйте репозиторий:

bash
git clone https://github.com/photobrand/n8n-nodes-lirax.git
cd n8n-nodes-lirax
Установите зависимости и соберите проект:

bash
npm install
npm run build
Перезапустите n8n для загрузки нод.

Конфигурация
Учетные данные (Credentials)
В n8n добавьте новые учетные данные типа LiraX API:

Base URL: URL вашего экземпляра LiraX (например, https://your-lirax-instance.com/api).

API Token: Токен для аутентифицированных запросов (Bearer-токен).

Webhook Token: Секретный токен для валидации входящих веб-хуков.

SSL Verification: Включите для проверки SSL-сертификатов (рекомендуется в продакшене).

Retry Policy: Настройки повторных попыток (количество, задержка).

Timeout: Таймаут запросов (по умолчанию 30 секунд).

Настройка веб-хуков в LiraX
В админ-панели LiraX перейдите в настройки интеграций.

Укажите URL веб-хука из триггер-ноды n8n.

Укажите webhook token для безопасности.

Использование
Триггер-нода (LiraX Trigger)
Используйте для прослушивания событий от LiraX: входящие звонки (event), записи разговоров (record), полученные SMS (smsReceived), завершение вызовов (makecall_finished) и т.д.

Пример: Подключите к ноде для обработки события и запуска workflow.

Основная нода (LiraX Node)
Выберите ресурс (telephony, crm, messaging и т.д.) и операцию из выпадающего списка.

Поддерживаемые операции (соответствуют API LiraX 4.45):

Telephony: makeCall, killCall, make2Calls, getcalls, setcalllost, getmakecall_data.

Messaging: sendSMS, checkSMS, sendcloudmessage.

CRM: createTask, AddTaskResult, createNote, createDeal, checkContact.

Utility: getUsers, getShops, getStages, getUserStatuses, getUserSips.

И другие: blacklist, campaigns, presence.

Параметры вводятся в UI ноды и валидируются Zod-схемами.

Пример workflow: LiraX Node (makeCall) → If (проверка статуса) → LiraX Node (createTask).

Примеры workflow
Исходящий звонок с созданием задачи в CRM:

LiraX Node: makeCall (ani: “101”, dnis: “380501234567”).

If: Проверка успеха.

LiraX Node: createTask (ext_contact: “380501234567”, text: “Follow-up call”).

Обработка входящего SMS:

LiraX Trigger (event: smsReceived).

LiraX Node: createNote (ext_contact: “{{$json.from}}”, text: “{{$json.text}}”).

Получение списка звонков:

LiraX Node: getcalls (datestart: “2025-10-01 00:00:00”, date_finish: “2025-10-02 23:59:59”).

Детали API
Интеграция строго следует спецификации LiraX API v4.45:

Все запросы: POST на /api с application/x-www-form-urlencoded.

Аутентификация: Заголовок Authorization: Bearer .

Имена команд: snakecase (например, getcalls, setcalllost).

Параметры: Строки для чисел/булев (“0” или “1” для булевых).

Даты: Формат YYYY-MM-DD HH:MM:SS.

Ограничения: Для get_calls — не более 48 часов; для SMS — не чаще 1 в 5 секунд на модем.

Нормализация: Телефонные номера преобразуются в цифры без пробелов/символов.

Важные замечания по использованию
Валидация: Не превышайте 48 часов для запросов логов звонков.

Троттлинг: Для sendSMS/checkSMS добавлена задержка 5 секунд.

Безопасность: Используйте timing-safe сравнение токенов для предотвращения атак.

Кэширование: Активировано для loadOptions (TTL: 3600 секунд).

Идемпотентность: Включена для предотвращения дубликатов при ретраях.

Обработка ошибок
Автоматические повторные попытки (до 3) с экспоненциальной задержкой для временных сбоев (5xx, таймауты).

Circuit Breaker: Блокировка запросов при повторяющихся ошибках (привязано к учетным данным).

Логи: Детальные сообщения с трассировкой стека в catch-блоках.

В UI: Пользовательские сообщения об ошибках (например, “Invalid parameters” для 400).

Разработка и тестирование
Язык: TypeScript с строгой типизацией (Zod для схем, ESLint для линтинга).

Внесение вклада
Форкните репозиторий и создайте pull request.

Соблюдайте стиль кода (ESLint) и добавляйте тесты для новых фич/фиксов.

Сообщайте об ошибках в Issues.