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

Версия: 1.0.0 Автор: PRAGMA ([email protected]) Репозиторий: 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, get_calls, set_call_lost, get_makecall_data.

Messaging: sendSMS, checkSMS, send_cloud_message.

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: get_calls (date_start: "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 .

Имена команд: snake_case (например, get_calls, set_call_lost).

Параметры: Строки для чисел/булев ("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 для линтинга).

Структура:

src/index.ts: Точка входа.

nodes/LiraX.node.ts: Основная нода.

nodes/LiraXTrigger.node.ts: Триггер.

shared/LiraX.utils.ts: Утилиты (liraxRequest, normalizePhoneDigits и т.д.).

Тестирование: Unit- и integration-тесты с Jest и mocks (npm test).

Сборка: npm run build (tsconfig.json с outDir: dist).

Установка

Метод 1: Через Community Nodes в n8n UI (рекомендуется)

Это самый простой способ для облачной и коробочной версии n8n:

1. Откройте ваш n8n
2. Перейдите в Settings (Настройки) → Community Nodes
3. Нажмите Install
4. В поле Enter npm package name введите: n8n-nodes-lirax
5. Нажмите Install
6. Дождитесь завершения установки
7. Готово! Ноды LiraX появятся в списке нод

Метод 2: Ручная установка (для продвинутых пользователей)

Для self-hosted версии n8n:

1. Клонируйте репозиторий git clone https://github.com/photobrand/n8n-nodes-lirax.git cd n8n-nodes-lirax

2. Установите зависимости npm install

3. Соберите проект npm run build

4. Создайте символическую ссылку (или скопируйте в custom nodes папку) npm link

5. В папке с n8n выполните npm link n8n-nodes-lirax

6. Перезапустите n8n

=====================================================================================================

Настройка региона и эндпойнтов

LiraX работает в двух основных регионах:

Украина (lirax.ua)

• Выберите Ukraine (lirax.ua) в поле Region
• Эндпойнты настраиваются автоматически:
  • Основной: https://lira.voip.com.ua:8482/general
  • Резервный: https://api.lirax.net/general

Беларусь (lirax.by)

• Выберите Belarus (lirax.by) в поле Region
• Эндпойнты настраиваются автоматически:
  • Основной: https://api.lirax.by/general
  • Резервный: https://lira.voip.com.by:8482/general

Собственный эндпойнт

• Выберите Custom URL в поле Region
• Укажите ваш URL в поле Base URL
• Опционально укажите резервный URL в Secondary Base URL

Важно: Нода автоматически попробует резервный эндпойнт если основной недоступен

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

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

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