npm package: @myshakin_mikhail/n8n-nodes-bitrix24
Description: Custom n8n node for creating tasks in Bitrix24 via REST API
Author: myshakin_mikhail
Latest version: 1.0.23

# n8n-nodes-bitrix24

Кастомная n8n нода для создания, редактирования и удаления задач в Bitrix24 через REST API.

## Установка

### Способ 1: Установка из npm (если опубликовано)

```bash
cd ~/.n8n/custom  # или $env:USERPROFILE\.n8n\custom на Windows
npm install @myshakin_mikhail/n8n-nodes-bitrix24
```

### Способ 2: Локальная установка для разработки

**Windows:**
```powershell
# Создайте папку 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:**
```bash
# Создайте папку custom (если её нет)
mkdir -p ~/.n8n/custom

# Соберите проект в исходной папке
cd /путь/к/bitrix24-node
npm run build

# Перейдите в папку custom и установите пакет
cd ~/.n8n/custom
npm install /путь/к/bitrix24-node
```

### Проверка установки

1. Запустите n8n (если ещё не запущен):
   ```bash
   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
```

**Пример ответа:**
```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
```

**Пример ответа:**
```json
{
  "result": [
    {
      "ID": "1",
      "NAME": "Иван",
      "LAST_NAME": "Иванов",
      "EMAIL": "ivan@example.com"
    },
    {
      "ID": "2",
      "NAME": "Петр",
      "LAST_NAME": "Петров",
      "EMAIL": "petr@example.com"
    }
  ]
}
```

**Где взять 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:**
```json
{
  "title": "Новая задача",
  "description": "Описание задачи",
  "userId": 5
}
```

### Шаг 6: Запуск workflow

1. Нажмите кнопку **"Execute Workflow"** (Выполнить workflow) или клавишу `Ctrl+Enter`
2. Проверьте результат выполнения ноды
3. Если всё настроено правильно, задача будет создана в Bitrix24
4. Откройте Bitrix24 и проверьте, что задача появилась в разделе "Задачи"

### Шаг 7: Проверка результата

Нода возвращает данные о созданной задаче в следующем формате:

**Успешное создание задачи:**
```json
{
  "success": true,
  "taskId": 123,
  "task": {
    "id": 123,
    "title": "Название задачи",
    "description": "Описание задачи",
    "responsibleId": 1,
    ...
  },
  "response": {
    "result": {
      "task": { ... }
    }
  }
}
```

**Успешное обновление задачи:**
```json
{
  "success": true,
  "taskId": 123,
  "task": {
    "id": 123,
    "title": "Обновленное название",
    "description": "Обновленное описание",
    ...
  },
  "response": {
    "result": {
      "task": { ... }
    }
  }
}
```

**Успешное удаление задачи:**
```json
{
  "success": true,
  "taskId": 123,
  "deleted": true,
  "result": true,
  "response": {
    "result": true
  }
}
```

**Если произошла ошибка (и включен "Continue on Fail"):**
```json
{
  "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+

### Сборка проекта

```bash
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