n8n-nodes-keitaro/README.md

Полноценная интеграция с Keitaro Tracker API для n8n

# n8n-nodes-keitaro

## Описание

Интеграция [Keitaro](https://keitaro.io/) с платформой автоматизации [n8n](https://n8n.io/). Данный модуль предоставляет полный доступ к API Keitaro и позволяет работать со всеми основными ресурсами трекера.

## Установка

### Через NPM

```bash
npm install n8n-nodes-keitaro
```

### Вручную

1. Клонировать репозиторий
2. Установить зависимости: `npm install`
3. Собрать проект: `npm run build`
4. Создать символическую ссылку: `npm link`
5. В директории n8n выполнить: `npm link n8n-nodes-keitaro`

## Авторизация

Для работы с API Keitaro необходимо:

1. В n8n создать учетные данные типа "Keitaro API"
2. Указать домен трекера (например, `tracker.domain.com`)
3. Указать API-ключ (можно получить в настройках Keitaro)

## Поддерживаемые ресурсы

Модуль поддерживает работу со следующими ресурсами Keitaro:

| Ресурс | Описание |
|--------|----------|
| campaign | Кампании |
| stream | Потоки |
| landing | Лендинги |
| offer | Офферы |
| traffic | Трафик |
| user | Пользователи |
| blacklist | Черный список |
| bot | Боты |
| postback | Постбэки |
| source | Источники трафика |
| conversion | Конверсии |
| domain | Домены |
| click | Клики |
| filter | Фильтры |
| settings | Настройки |
| log | Логи |
| stats | Статистика |
| group | Группы |

## Поддерживаемые операции

Для всех ресурсов (кроме stats) доступны следующие операции:

- **get** - получить информацию о конкретной записи
- **getAll** - получить список всех записей
- **create** - создать новую запись
- **update** - обновить существующую запись
- **delete** - удалить запись

> **Примечание**: Для ресурса `stats` доступна только операция `getAll`.

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

### Получение списка кампаний

1. Выберите ресурс: `campaign`
2. Выберите операцию: `getAll`
3. Запустите узел

### Получение детальной статистики

1. Выберите ресурс: `stats`
2. Выберите операцию: `getAll` 
3. Укажите обязательные параметры:
   - `range_from`: начальная дата (YYYY-MM-DD)
   - `range_to`: конечная дата (YYYY-MM-DD)
4. Выберите необходимые группировки (по дням, кампаниям, странам и т.д.)

### Получение логов кликов

1. Выберите ресурс: `click`
2. Выберите операцию: `getAll`
3. Укажите параметры:
   - Диапазон дат (`start_date` и `end_date`) или
   - Лимит (`limit`)
4. Укажите дополнительные фильтры при необходимости

### Создание кампании

1. Выберите ресурс: `campaign`
2. Выберите операцию: `create`
3. В поле "Данные Кампании" укажите JSON с параметрами новой кампании:

```json
{
  "name": "Название кампании",
  "alias": "campaign_alias",
  "type": "position",
  "state": "active",
  "uniqueness_method": "ip+ua"
}
```

## Параметры для работы со статистикой

При запросе статистики (`stats`/`getAll`) доступны следующие параметры:

### Обязательные параметры:
- `range_from` - начальная дата
- `range_to` - конечная дата

### Группировка данных:
- `day` - по дням
- `hour` - по часам
- `campaign_id` - по кампаниям
- `stream_id` - по потокам
- `country` - по странам
- `device_type` - по типам устройств
- `browser_name` - по браузерам
- `os_name` - по операционным системам
- `keyword` - по ключевым словам
- `sub_id_1` - `sub_id_5` - по суб-меткам

### Метрики:
- `roi` - рентабельность инвестиций
- `cr` - коэффициент конверсии
- `epc` - доход на клик
- `cpc` - стоимость клика

## Параметры для работы с кликами

При запросе кликов (`click`/`getAll`) доступны следующие параметры:

### Основные фильтры:
- `campaign_id` - ID кампании
- `stream_id` - ID потока
- `start_date` - начальная дата
- `end_date` - конечная дата

### Дополнительные фильтры:
- `country` - код страны
- `ip` - IP-адрес
- `sub_id_1` - `sub_id_5` - значения суб-меток

### Пагинация и сортировка:
- `limit` - максимальное количество записей
- `offset` - смещение для пагинации
- `sort` - поле и направление сортировки

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

Модуль предоставляет типизированные интерфейсы для всех сущностей Keitaro:

- `KeitaroCampaign` - кампании
- `KeitaroStream` - потоки
- `KeitaroLanding` - лендинги
- `KeitaroOffer` - офферы
- `KeitaroTraffic` - трафик
- `KeitaroUser` - пользователи
- `KeitaroBlacklist` - записи черного списка
- `KeitaroBot` - боты
- `KeitaroPostback` - постбэки
- `KeitaroSource` - источники
- `KeitaroConversion` - конверсии
- `KeitaroDomain` - домены
- `KeitaroClick` - клики
- `KeitaroFilter` - фильтры
- `KeitaroSettings` - настройки
- `KeitaroLog` - логи
- `KeitaroStats` - статистика
- `KeitaroGroup` - группы

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

Модуль обеспечивает подробную информацию об ошибках, включая:
- Код статуса ответа
- Текст ошибки
- Данные ответа от API

При включенной опции "Continue on Fail" в n8n, узел не будет прерывать выполнение рабочего процесса и вернет объект с информацией об ошибке.

## Лицензия

MIT

## Разработка и вклад в проект

1. Клонировать репозиторий
2. Установить зависимости: `npm install`
3. Запустить сборку в режиме разработки: `npm run dev`

Приветствуются пулл-реквесты и сообщения об ошибках!