n8n-nodes-bitrix24

Кастомная n8n нода для создания, редактирования и удаления задач в Bitrix24 через REST API.

Установка

Способ 1: Установка из npm (если опубликовано)

cd ~/.n8n/custom  # или $env:USERPROFILE\.n8n\custom на Windows
npm install @myshakin_mikhail/n8n-nodes-bitrix24

Способ 2: Локальная установка для разработки

Windows:

# Создайте папку custom (если её нет)
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.n8n\custom"

# Перейдите в папку custom
cd "$env:USERPROFILE\.n8n\custom"

# Соберите проект в исходной папке
cd "C:\Users\Public\VsCodePrograms\JS_TS\N8N\castom\bitrix24-node"
npm run build

# Установите пакет в папку custom
cd "$env:USERPROFILE\.n8n\custom"
npm install "C:\Users\Public\VsCodePrograms\JS_TS\N8N\castom\bitrix24-node"

Linux/Mac:

# Создайте папку custom (если её нет)
mkdir -p ~/.n8n/custom

# Соберите проект в исходной папке
cd /путь/к/bitrix24-node
npm run build

# Перейдите в папку custom и установите пакет
cd ~/.n8n/custom
npm install /путь/к/bitrix24-node

Проверка установки

1. Запустите n8n (если ещё не запущен):

   n8n start

2. Откройте браузер: http://localhost:5678

3. Создайте новый workflow или откройте существующий

4. Нажмите кнопку "+" для добавления ноды

5. В поиске введите "Bitrix24"

6. Если нода появилась в списке — установка прошла успешно ✅

Настройка Credentials

Шаг 1: Создание Webhook в Bitrix24

Перед использованием ноды необходимо создать входящий вебхук в Bitrix24:

1. Войдите в ваш Bitrix24 портал

2. Перейдите в раздел создания вебхука:

   • Откройте меню "Приложения" (Applications) в левой панели
   • Выберите "Входящий вебхук" (Incoming Webhook) или "Другие" → "Входящий вебхук"
   • Альтернативный путь: настройки портала → "Разработчикам" → "Входящий вебхук"

3. Создайте новый вебхук:

   • Нажмите кнопку "Создать вебхук" (Create webhook) или "Добавить"
   • Укажите название вебхука (например, "n8n Tasks")

4. Настройте права доступа:

   • Найдите раздел с правами доступа
   • Обязательно отметьте галочкой tasks (Задачи)
   • При необходимости выберите дополнительные права (например, user для получения информации о пользователях)
   • Нажмите "Сохранить" или "Save"

5. Скопируйте Webhook URL:

   • После создания вы увидите URL вебхука
   • Формат: https://ваш-домен.bitrix24.ru/rest/1/код-вебхука/ или https://ваш-домен.bitrix24.ru/rest/1/код-вебхука
   • Важно: Скопируйте полный URL, включая /rest/1/...

   Примеры:

   • https://example.bitrix24.ru/rest/1/abc123def456/
   • https://mycompany.bitrix24.com/rest/1/xyz789/

Шаг 2: Добавление Credentials в n8n

1. Откройте раздел Credentials в n8n:

   • В интерфейсе n8n перейдите в раздел "Credentials" (Учётные данные) в левом меню
   • Или используйте меню "Settings" → "Credentials"

2. Создайте новый Credential:

   • Нажмите кнопку "Add Credential" (Добавить) или "Создать"
   • В поиске введите "Bitrix24"
   • Выберите "Bitrix24 API" из списка

3. Заполните поля:

   • Name (Название): введите понятное название, например, "Bitrix24 Production" или "My Bitrix24"
   • Webhook URL: вставьте скопированный ранее Webhook URL от Bitrix24
     • Формат: https://your-domain.bitrix24.ru/rest/1/webhook_code/
     • Не добавляйте лишних слешей в конце

4. Сохраните Credential:

   • Нажмите кнопку "Save" (Сохранить) или "Создать"
   • Credential будет сохранён и доступен для использования в нодах

Использование ноды

Шаг 1: Добавление ноды в workflow

1. Создайте новый workflow или откройте существующий
2. Нажмите кнопку "+" для добавления ноды
3. В поиске введите "Bitrix24" или найдите в списке нод
4. Выберите ноду "Bitrix24" — она появится на canvas

Шаг 2: Настройка ноды

1. Кликните на добавленную ноду "Bitrix24"

2. В правой панели настроек заполните параметры:

   • Credentials (обязательное):

     • Выберите созданный ранее credential "Bitrix24 API" из выпадающего списка
     • Если credential не отображается, проверьте, что он был сохранён

   • Operation (операция):

     • "Create Task" — создание новой задачи
     • "Update Task" — редактирование существующей задачи
     • "Delete Task" — удаление задачи
     • По умолчанию: "Create Task"

   • Title (обязательное):

     • Введите название задачи
     • Можно использовать выражения n8n: {{ $json.title }}
     • Пример: "Создать отчёт за неделю"

   • Description (опциональное):

     • Введите описание задачи
     • Поддерживается многострочный текст
     • Можно использовать выражения: {{ $json.description }}
     • Пример: "Необходимо подготовить отчёт о выполненных задачах"

   • Responsible User ID (обязательное):

     • Введите числовой ID пользователя-исполнителя в Bitrix24
     • По умолчанию: 1 (обычно это администратор)
     • Можно использовать выражения: {{ $json.userId }}
     • См. раздел "Как найти Responsible User ID" ниже

   • API Method (метод API):

     • По умолчанию: task.ctaskitem.add
     • Доступен только для операции "Create Task"

Операция: Update Task

Для редактирования существующей задачи:

• Task ID (обязательное):

  • Введите числовой ID задачи в Bitrix24, которую нужно отредактировать
  • Можно использовать выражения: {{ $json.taskId }}
  • Пример: 123

• Title (опциональное):

  • Введите новое название задачи
  • Оставьте пустым, чтобы не изменять текущее название
  • Можно использовать выражения: {{ $json.title }}

• Description (опциональное):

  • Введите новое описание задачи
  • Оставьте пустым, чтобы не изменять текущее описание
  • Можно использовать выражения: {{ $json.description }}

• Responsible User ID (опциональное):

  • Введите новый ID пользователя-исполнителя
  • Оставьте пустым, чтобы не изменять текущего исполнителя
  • Можно использовать выражения: {{ $json.userId }}

Важно: Для операции обновления необходимо указать хотя бы одно поле (Title, Description или Responsible User ID).

Операция: Delete Task

Для удаления задачи:

• Task ID (обязательное):
  • Введите числовой ID задачи в Bitrix24, которую нужно удалить
  • Можно использовать выражения: {{ $json.taskId }}
  • Пример: 123

Важно: Операция удаления необратима. Убедитесь, что вы удаляете правильную задачу.

Шаг 3: Как найти Task ID

Task ID — это уникальный числовой идентификатор задачи в Bitrix24.

Способ 1: Через интерфейс Bitrix24

1. Через страницу задачи:

   • Откройте задачу в Bitrix24
   • Посмотрите на URL страницы — ID обычно виден в адресной строке
   • Пример URL: https://example.bitrix24.ru/company/personal/user/123/tasks/task/view/456/ где 456 — это ID задачи

2. Через список задач:

   • Перейдите в раздел "Задачи" (Tasks)
   • Откройте нужную задачу
   • ID задачи будет виден в URL или в деталях задачи

Способ 2: Через Bitrix24 REST API

Используйте метод tasks.task.list для получения списка задач:

GET https://ваш-домен.bitrix24.ru/rest/1/ваш-вебхук/tasks.task.list.json

Пример ответа:

{
  "result": {
    "tasks": [
      {
        "id": "123",
        "title": "Название задачи",
        "responsibleId": "1"
      }
    ]
  }
}

Где взять ID:

• Поле id в ответе API — это и есть Task ID

Шаг 4: Как найти Responsible User ID

Responsible User ID — это уникальный числовой идентификатор пользователя в Bitrix24, который будет назначен исполнителем задачи.

Способ 1: Через интерфейс Bitrix24

1. Через профиль пользователя:

   • Откройте профиль пользователя в Bitrix24
   • Посмотрите на URL страницы — ID обычно виден в адресной строке
   • Пример URL: https://example.bitrix24.ru/company/personal/user/123/ где 123 — это ID пользователя

2. Через раздел "Сотрудники":

   • Перейдите в раздел "Компания" → "Сотрудники" (Company → Employees)
   • Откройте карточку нужного сотрудника
   • В URL страницы будет виден ID пользователя

Способ 2: Через Bitrix24 REST API

Используйте метод user.get или user.get для получения информации о текущем пользователе или списка пользователей:

Получить текущего пользователя:

GET https://ваш-домен.bitrix24.ru/rest/1/ваш-вебхук/user.get.json

Получить всех пользователей:

GET https://ваш-домен.bitrix24.ru/rest/1/ваш-вебхук/user.get.json

Пример ответа:

{
  "result": [
    {
      "ID": "1",
      "NAME": "Иван",
      "LAST_NAME": "Иванов",
      "EMAIL": "[email protected]"
    },
    {
      "ID": "2",
      "NAME": "Петр",
      "LAST_NAME": "Петров",
      "EMAIL": "[email protected]"
    }
  ]
}

Где взять ID:

• Поле ID в ответе API — это и есть Responsible User ID
• Обычно ID администратора = 1
• ID других пользователей начинаются с 2, 3 и т.д.

Способ 3: Через браузер (Developer Tools)

1. Откройте профиль пользователя в Bitrix24
2. Откройте Developer Tools (F12)
3. Перейдите на вкладку Network (Сеть)
4. Обновите страницу
5. Найдите запрос, содержащий информацию о пользователе
6. В ответе найдите поле ID или userId

Важные замечания:

• ID всегда числовой (1, 2, 3, и т.д.)
• ID не меняется после создания пользователя
• ID администратора обычно равен 1
• Если указать несуществующий ID, задача может быть создана, но без исполнителя или с ошибкой

Шаг 5: Использование данных из предыдущих нод

Вы можете использовать данные из предыдущих нод workflow через выражения n8n:

Примеры выражений:

• Title:

  • {{ $json.title }}
  • {{ $json.taskName }}
  • {{ $json.subject }}

• Description:

  • {{ $json.description }}
  • {{ $json.taskDescription }}
  • {{ $json.body }}

• Responsible User ID:

  • {{ $json.userId }}
  • {{ $json.responsibleId }}
  • {{ $json.assignee }}

Пример workflow:

[Webhook] → [Function] → [Bitrix24]
                            ↓
                    Title: {{ $json.title }}
                    Description: {{ $json.description }}
                    Responsible User ID: {{ $json.userId }}

Пример данных из Webhook:

{
  "title": "Новая задача",
  "description": "Описание задачи",
  "userId": 5
}

Шаг 6: Запуск workflow

1. Нажмите кнопку "Execute Workflow" (Выполнить workflow) или клавишу Ctrl+Enter
2. Проверьте результат выполнения ноды
3. Если всё настроено правильно, задача будет создана в Bitrix24
4. Откройте Bitrix24 и проверьте, что задача появилась в разделе "Задачи"

Шаг 7: Проверка результата

Нода возвращает данные о созданной задаче в следующем формате:

Успешное создание задачи:

{
  "success": true,
  "taskId": 123,
  "task": {
    "id": 123,
    "title": "Название задачи",
    "description": "Описание задачи",
    "responsibleId": 1,
    ...
  },
  "response": {
    "result": {
      "task": { ... }
    }
  }
}

Успешное обновление задачи:

{
  "success": true,
  "taskId": 123,
  "task": {
    "id": 123,
    "title": "Обновленное название",
    "description": "Обновленное описание",
    ...
  },
  "response": {
    "result": {
      "task": { ... }
    }
  }
}

Успешное удаление задачи:

{
  "success": true,
  "taskId": 123,
  "deleted": true,
  "result": true,
  "response": {
    "result": true
  }
}

Если произошла ошибка (и включен "Continue on Fail"):

{
  "success": false,
  "error": "Описание ошибки"
}

Эти данные можно использовать в следующих нодах workflow через выражения:

• {{ $json.taskId }} — ID задачи (созданной, обновленной или удаленной)
• {{ $json.task.title }} — название задачи
• {{ $json.task.description }} — описание задачи
• {{ $json.deleted }} — флаг успешного удаления (для операции Delete Task)

Параметры ноды

Operation: Create Task

| Параметр | Тип | Обязательное | Описание | По умолчанию | |----------|-----|--------------|----------|--------------| | Title | string | ✅ Да | Название задачи. Можно использовать выражения n8n. | - | | Description | string | ❌ Нет | Описание задачи. Поддерживает многострочный текст. | Пустая строка | | Responsible User ID | number | ✅ Да | ID пользователя-исполнителя в Bitrix24. См. раздел "Как найти Responsible User ID". | 1 | | API Method | options | ❌ Нет | Метод API для создания задачи. | task.ctaskitem.add |

Operation: Update Task

| Параметр | Тип | Обязательное | Описание | По умолчанию | |----------|-----|--------------|----------|--------------| | Task ID | number | ✅ Да | ID задачи в Bitrix24, которую нужно обновить. См. раздел "Как найти Task ID". | - | | Title | string | ❌ Нет | Новое название задачи. Оставьте пустым, чтобы не изменять. | Пустая строка | | Description | string | ❌ Нет | Новое описание задачи. Оставьте пустым, чтобы не изменять. | Пустая строка | | Responsible User ID | number | ❌ Нет | Новый ID пользователя-исполнителя. Оставьте пустым, чтобы не изменять. | Пустая строка |

Примечание: Необходимо указать хотя бы одно поле для обновления (Title, Description или Responsible User ID).

Operation: Delete Task

| Параметр | Тип | Обязательное | Описание | По умолчанию | |----------|-----|--------------|----------|--------------| | Task ID | number | ✅ Да | ID задачи в Bitrix24, которую нужно удалить. См. раздел "Как найти Task ID". | - |

Обработка ошибок

Типичные ошибки и их решения

1. "Webhook URL is required"

   • Причина: Не указан Webhook URL в credentials
   • Решение: Проверьте настройки credentials, убедитесь, что Webhook URL заполнен

2. "Task title is required"

   • Причина: Не указано название задачи
   • Решение: Заполните поле "Title" в настройках ноды

3. "Responsible User ID is required"

   • Причина: Не указан ID пользователя-исполнителя
   • Решение: Укажите числовой ID в поле "Responsible User ID"

4. "Task ID is required"

   • Причина: Не указан ID задачи для операции обновления или удаления
   • Решение: Укажите числовой ID в поле "Task ID"

5. "At least one field (Title, Description, or Responsible User ID) must be provided for update"

   • Причина: При обновлении задачи не указано ни одно поле для изменения
   • Решение: Укажите хотя бы одно поле (Title, Description или Responsible User ID) для обновления

6. "Bitrix24 API HTTP Error (404)"

   • Причина: Неверный Webhook URL или метод API
   • Решение: Проверьте правильность Webhook URL, убедитесь, что вебхук активен в Bitrix24

7. "Bitrix24 API HTTP Error (401)"

   • Причина: Неверный или устаревший Webhook URL
   • Решение: Создайте новый вебхук в Bitrix24 и обновите credentials

8. "Bitrix24 API Error: Access denied"

   • Причина: У вебхука нет прав на создание, редактирование или удаление задач
   • Решение: Проверьте права доступа вебхука в Bitrix24, убедитесь, что включены права на tasks

Режим "Continue on Fail"

Если включен режим "Continue on Fail" (Продолжить при ошибке) в настройках ноды:

• Ошибки не прервут выполнение workflow
• Нода вернёт объект с полем success: false и описанием ошибки
• Следующие ноды в workflow продолжат выполнение

Для включения режима:

1. Откройте настройки ноды
2. Включите переключатель "Continue on Fail" или "Продолжить при ошибке"

API Bitrix24

Нода использует следующие методы Bitrix24 REST API:

Создание задачи

Метод: task.ctaskitem.add

Формат запроса:

POST https://ваш-домен.bitrix24.ru/rest/1/вебхук/task.ctaskitem.add.json
Content-Type: application/json

{
  "fields": {
    "TITLE": "Название задачи",
    "RESPONSIBLE_ID": 1,
    "DESCRIPTION": "Описание задачи"
  }
}

Обновление задачи

Метод: tasks.task.update

Формат запроса:

POST https://ваш-домен.bitrix24.ru/rest/1/вебхук/tasks.task.update.json
Content-Type: application/json

{
  "taskId": 123,
  "fields": {
    "TITLE": "Обновленное название",
    "DESCRIPTION": "Обновленное описание",
    "RESPONSIBLE_ID": 2
  }
}

Удаление задачи

Метод: tasks.task.delete

Формат запроса:

POST https://ваш-домен.bitrix24.ru/rest/1/вебхук/tasks.task.delete.json
Content-Type: application/json

{
  "taskId": 123
}

Документация Bitrix24 REST API

• Основная документация: https://dev.1c-bitrix.ru/rest_help/
• Методы для задач: https://dev.1c-bitrix.ru/rest_help/tasks/tasks/index.php
• Метод user.get: https://dev.1c-bitrix.ru/rest_help/users/user_get.php

Разработка

Требования

• Node.js 18+
• npm или yarn
• TypeScript 5.0+

Сборка проекта

npm install
npm run build

Собранные файлы будут находиться в папке dist/.

Структура проекта

bitrix24-node/
├── package.json              # Конфигурация пакета
├── tsconfig.json            # Настройки TypeScript
├── .npmignore               # Исключения для npm
├── README.md                # Документация
├── index.ts                 # Точка входа
├── credentials/             # Credentials
│   └── Bitrix24Api.credentials.ts
└── nodes/                   # Ноды
    └── Bitrix24/
        └── Bitrix24.node.ts

Локальная разработка

1. Клонируйте репозиторий
2. Установите зависимости: npm install
3. Соберите проект: npm run build
4. Установите в папку custom n8n (см. раздел "Установка")
5. Перезапустите n8n
6. Внесите изменения в исходные файлы
7. Повторите шаги 3-5 для применения изменений

Тестирование

Для тестирования ноды:

1. Запустите n8n в режиме разработки
2. Создайте тестовый workflow
3. Используйте ноду с тестовыми данными
4. Проверьте результат в Bitrix24

Лицензия

MIT

Поддержка

При возникновении проблем:

1. Проверьте раздел "Обработка ошибок"
2. Убедитесь, что все credentials настроены правильно
3. Проверьте права доступа вебхука в Bitrix24
4. Просмотрите логи n8n для детальной информации об ошибках

Версия пакета: 1.0.12