npm package: @rrabochiy/n8n-nodes-planerka
Description: n8n community node для Планёрки - системы онлайн-бронирования
Author: Planerka
Latest version: 0.1.0

# n8n-nodes-planerka

Кастомная нода для n8n, позволяющая получать webhook события от системы онлайн-бронирования [Планёрка](https://planerka.io).

![Planerka Logo](https://planerka.io/images/logo.svg)

## Описание

Эта community node для n8n позволяет автоматизировать обработку событий бронирования из Планёрки. Нода работает как webhook trigger и запускает workflow при следующих событиях:

- 📅 **Создание встречи** (`BOOKING_CREATED`)
- ❌ **Отмена встречи** (`BOOKING_CANCELLED`)
- 🔄 **Перенос встречи** (`BOOKING_RESCHEDULED`)

## Установка

### Вариант 1: Установка через npm (рекомендуется)

```bash
npm install n8n-nodes-planerka
```

После установки перезапустите n8n:

```bash
n8n start
```

### Вариант 2: Локальная установка

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

2. Установите зависимости и соберите проект:
```bash
npm install
npm run build
```

3. Скопируйте папку в `~/.n8n/custom/`:
```bash
mkdir -p ~/.n8n/custom
cp -r . ~/.n8n/custom/n8n-nodes-planerka
```

4. Перезапустите n8n:
```bash
n8n start
```

## Быстрый старт

### 1. Настройка Credentials в n8n

1. Откройте n8n
2. Перейдите в **Credentials** → **New**
3. Найдите **Planerka API**
4. Введите **Webhook Secret** (любую строку, которую вы будете использовать для проверки подлинности webhook'ов)
5. Сохраните credentials

### 2. Создание workflow в n8n

1. Создайте новый workflow
2. Добавьте ноду **Planerka Trigger**
3. Выберите созданные credentials
4. Выберите интересующие вас события (например, "Создание встречи")
5. Активируйте workflow
6. Скопируйте **Webhook URL** (он появится после активации)

### 3. Настройка webhook в Планёрке

1. Откройте [Планёрку](https://planerka.io)
2. Перейдите в `/webhooks`
3. Нажмите **"Создать webhook"**
4. Заполните поля:
   - **Название**: Любое название (например, "n8n Integration")
   - **URL**: Вставьте webhook URL из n8n (без `https://`, например: `n8n.example.com/webhook/abc123...`)
   - **Secret**: Тот же секретный ключ, что и в credentials n8n
   - **События**: Выберите `BOOKING_CREATED`, `BOOKING_CANCELLED`, `BOOKING_RESCHEDULED`
5. Сохраните webhook

### 4. Тестирование

1. Создайте тестовое бронирование в Планёрке
2. Проверьте, что workflow в n8n запустился
3. Изучите полученные данные

## Структура данных webhook

При получении события, нода передаёт следующие данные:

```json
{
  "event": "BOOKING_CREATED",
  "uid": "booking_unique_id",
  "title": "Встреча с клиентом",
  "description": "Обсуждение проекта",
  "startTime": "2024-12-15T14:00:00.000Z",
  "endTime": "2024-12-15T15:00:00.000Z",
  "organizer": {
    "name": "Иван Иванов",
    "email": "ivan@example.com",
    "timeZone": "Europe/Moscow"
  },
  "attendees": [
    {
      "name": "Пётр Петров",
      "email": "petr@example.com",
      "timeZone": "Europe/Moscow"
    }
  ],
  "location": {
    "name": "Zoom",
    "url": "https://zoom.us/j/123456789",
    "id": "123456789",
    "password": "password"
  },
  "customInputs": [
    {
      "label": "Телефон",
      "value": "+7 999 123-45-67"
    }
  ],
  "eventType": "individual"
}
```

### Дополнительные поля

**Для события `BOOKING_CANCELLED`:**
- `cancellationReason` - причина отмены

**Для события `BOOKING_CREATED`:**
- `utm` - UTM метки (если переданы)

## Примеры использования

### Пример 1: Уведомления в Slack

```
Planerka Trigger (BOOKING_CREATED)
  → Slack: Send Message
    Message: "Новая встреча: {{$json.title}} в {{$json.startTime}}"
```

### Пример 2: Синхронизация с Google Calendar

```
Planerka Trigger (BOOKING_CREATED)
  → Google Calendar: Create Event
    Summary: {{$json.title}}
    Start: {{$json.startTime}}
    End: {{$json.endTime}}
```

### Пример 3: Добавление в CRM

```
Planerka Trigger (BOOKING_CREATED)
  → HTTP Request: POST to CRM API
    Body: {
      "contact": "{{$json.attendees[0].email}}",
      "meeting_date": "{{$json.startTime}}"
    }
```

### Пример 4: Сохранение в базу данных

```
Planerka Trigger (BOOKING_CREATED, BOOKING_CANCELLED)
  → MySQL: Insert
    Table: bookings
    Data: {{$json}}
```

## Безопасность

Нода использует **Bearer token** для валидации webhook запросов от Планёрки:

- Webhook secret проверяется в заголовке `Authorization: Bearer {secret}`
- Если секрет не совпадает, запрос отклоняется с кодом 401
- Рекомендуется использовать длинный случайный секрет (минимум 32 символа)

### Генерация безопасного секрета

```bash
# Linux/macOS
openssl rand -base64 32

# Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
```

## Troubleshooting

### Webhook не срабатывает

1. **Проверьте активацию workflow** - workflow должен быть активирован
2. **Проверьте credentials** - секрет в n8n должен совпадать с секретом в Планёрке
3. **Проверьте URL** - URL должен быть без `https://` в Планёрке
4. **Проверьте события** - в webhook Планёрки должны быть выбраны нужные события
5. **Проверьте логи n8n** - посмотрите в Executions на ошибки

### Ошибка 401 Unauthorized

- Секрет в credentials n8n не совпадает с секретом в webhook Планёрки
- Обновите секрет в одном из мест

### События не фильтруются

- Убедитесь, что в параметрах ноды выбраны нужные события
- Проверьте, что в webhook Планёрки включены соответствующие события

## Разработка

### Сборка

```bash
npm run build
```

### Разработка с hot-reload

```bash
npm run dev
```

### Линтинг

```bash
npm run lint
npm run lintfix
```

## Поддержка

- 📧 Email: support@planerka.io
- 🌐 Сайт: [planerka.io](https://planerka.app)
- 📚 Документация: [planerka.io/docs](https://help.planerka.app)
- 💬 Telegram: [@planerka_support](https://t.me/planerka_support_bot)

## Лицензия

MIT

## Авторы

Разработано командой [Планёрка](https://planerka.app)

---

🚀 Автоматизируйте работу с бронированиями вместе с Планёркой и n8n!