Trigly для разработчика: API, SDK, вебхуки и интеграции

Когда маркетинг просит «подключить ещё один канал» или «передавать события из приложения», всё упирается в разработку. Trigly спроектирован так, чтобы интеграция занимала часы, а не недели. В этой статье — полный обзор технических возможностей платформы: REST API с 290+ эндпоинтами, JavaScript SDK для трекинга, вебхуки для событийной архитектуры и готовые адаптеры каналов.

Архитектура платформы

Trigly построен на современном стеке:

• Backend: Python 3.12, FastAPI, SQLAlchemy 2.0 (async), PostgreSQL 16, ClickHouse, Redis 7, Celery 5
• Frontend: Next.js 16, TypeScript, Tailwind CSS 4
• ML/AI: scikit-learn, OpenAI GPT-4o-mini

Архитектура — мультитенантная. Каждая организация изолирована через organization_id на уровне всех таблиц и запросов. JWT-токены содержат org_id, что обеспечивает безопасность данных без дополнительных проверок на стороне клиента.

Базы данных — каждой задаче свой инструмент

Хранилище	Назначение	Драйвер
PostgreSQL 16	Метаданные, CRUD, связи (33 таблицы)	asyncpg (async), psycopg (Celery)
ClickHouse	События, аналитика, ML-фичи	clickhouse_connect
Redis 7	Кеш, rate limiting, очереди Celery	redis.asyncio

Разделение на PostgreSQL и ClickHouse — не прихоть: события трекинга могут генерировать миллионы записей в день, и ClickHouse обрабатывает их в 50-100 раз быстрее PostgreSQL для аналитических запросов.

REST API: 290+ эндпоинтов

API организовано по модулям, каждый с чётким префиксом:

/api/v1/auth          — аутентификация (10 эндпоинтов)
/api/v1/cdp           — CDP: контакты, сегменты, события (76 эндпоинтов)
/api/v1/campaigns     — кампании, шаблоны, потоки (80 эндпоинтов)
/api/v1/channels      — каналы коммуникации (27 эндпоинтов)
/api/v1/analytics     — аналитика (6 эндпоинтов)
/api/v1/ai            — AI-генерация и прогнозы (26 эндпоинтов)
/api/v1/loyalty        — программы лояльности (14 эндпоинтов)
/api/v1/conversions   — попапы и конверсии (10 эндпоинтов)

Аутентификация

Trigly использует JWT с парой access/refresh токенов. Payload включает sub (user_id), org_id, role и jti для отзыва токенов:

# Регистрация
curl -X POST /api/v1/auth/register \
  -d '{"email": "dev@company.ru", "password": "...", "organization_name": "MyOrg"}'

# Логин
curl -X POST /api/v1/auth/login \
  -d '{"email": "dev@company.ru", "password": "..."}'
# → {"access_token": "eyJ...", "refresh_token": "eyJ..."}

Access-токен передаётся в заголовке Authorization: Bearer <token>. При 401 — обновите через /api/v1/auth/refresh.

Пример: работа с контактами

# Создание контакта
curl -X POST /api/v1/cdp/customers \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "email": "ivan@example.ru",
    "first_name": "Иван",
    "tags": ["vip", "ecommerce"],
    "custom_fields": {"city": "Москва", "plan": "premium"}
  }'

# Список контактов с пагинацией
curl "/api/v1/cdp/customers?page=1&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Каждый контакт содержит 45+ полей: от базовых (email, phone) до ML-вычисляемых (ai_score, rfm_segment, churn_prediction).

SDK для трекинга событий

Для отправки событий из фронтенда или мобильного приложения используйте публичные SDK-эндпоинты. Они не требуют JWT — авторизация через API-ключ.

Создание API-ключа

curl -X POST /api/v1/cdp/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "Production Web"}'
# → {"key": "tk_live_abc123...", "prefix": "tk_live_"}

Трекинг событий

# Единичное событие
curl -X POST /api/v1/sdk/track \
  -H "X-API-Key: tk_live_abc123" \
  -d '{
    "customer_id": "uuid-...",
    "event_type": "page_view",
    "event_name": "product_viewed",
    "properties": {"product_id": "SKU-123", "price": 2990},
    "page_url": "https://shop.ru/product/123"
  }'

# Батч-отправка (до 1000 событий за раз)
curl -X POST /api/v1/sdk/batch \
  -H "X-API-Key: tk_live_abc123" \
  -d '{"events": [...]}'

# Идентификация пользователя
curl -X POST /api/v1/sdk/identify \
  -H "X-API-Key: tk_live_abc123" \
  -d '{"customer_id": "uuid-...", "traits": {"email": "user@mail.ru"}}'

События сохраняются в ClickHouse с партиционированием по месяцам и TTL 365 дней. Rate limit для SDK — 1000 запросов в минуту.

Вебхуки: событийная архитектура

Trigly поддерживает как входящие (от провайдеров), так и исходящие вебхуки.

Исходящие вебхуки

Настройте URL для получения уведомлений о событиях кампаний:

curl -X POST /api/v1/campaigns/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "url": "https://your-app.ru/hooks/trigly",
    "event_types": ["message.sent", "message.delivered", "message.opened"],
    "secret": "your-hmac-secret"
  }'

Каждый вебхук подписывается HMAC-SHA256 — проверяйте подпись на своей стороне. При недоступности URL — 3 автоматические попытки с экспоненциальной задержкой.

Входящие провайдерские вебхуки

Trigly принимает вебхуки от провайдеров каналов на публичных эндпоинтах:

• POST /hooks/email/unisender — статусы доставки Unisender
• POST /hooks/email/bounce — обработка баунсов (hard_bounce → автосупрессия)
• POST /hooks/telegram/{org_id} — обновления Telegram Bot API
• POST /hooks/sms/status — статусы SMS.ru

Каналы: 6 адаптеров с единым интерфейсом

Все каналы реализуют единый BaseChannelAdapter с методами send(), send_batch(), health_check() и send_with_retry():

Канал	Адаптер	Rate limit	Стоимость
Email (SMTP)	EmailAdapter	—	Бесплатно
Email (Unisender)	UnisenderAdapter	50/с	0.1-0.5 руб.
Telegram	TelegramFullAdapter	30/с	Бесплатно
SMS	SMSRuAdapter	100/с	2.5 руб./сегмент
WhatsApp	WhatsAppAdapter	80/с	5-8 руб./шаблон
Push	WebPushAdapter	100/с	Бесплатно

Адаптерная фабрика get_channel_adapter_for_org() автоматически загружает credentials организации из PostgreSQL. Если нет — использует переменные окружения.

Импорт и экспорт данных

CSV-импорт контактов

# 1. Загрузка файла
curl -X POST /api/v1/cdp/imports/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@contacts.csv"

# 2. Предпросмотр маппинга
curl /api/v1/cdp/imports/{import_id}/preview

# 3. Запуск импорта с дедупликацией
curl -X POST /api/v1/cdp/imports/{import_id}/start \
  -d '{"mapping": {"Email": "email", "Имя": "first_name"}}'

Экспорт в CSV/JSON

curl -X POST /api/v1/cdp/exports \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"format": "csv", "segment_id": "uuid-..."}'

Celery-задачи и фоновая обработка

Тяжёлые операции выполняются асинхронно через Celery:

• execute_campaign — отправка кампании пакетами по 50 сообщений
• recalculate_rfm — пересчёт RFM + lifecycle + data quality (ежедневно, 3:00)
• refresh_dynamic_segments — обновление динамических сегментов (каждые 30 минут)
• update_preferred_channels — анализ предпочтительных каналов (ежедневно, 4:00)
• train_all_models — обучение ML-моделей (churn, LTV, next purchase)

Docker Compose: быстрый старт

Для локальной разработки — 9 сервисов в Docker Compose:

docker compose up -d
# PostgreSQL :5432, ClickHouse :8123, Redis :6379
# API :8000, Frontend :3000, Mailpit :8025

Миграции через Alembic:

docker compose exec app uv run alembic upgrade head

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

• Rate limiting на Redis: /auth — 200/мин, /sdk — 1000/мин, остальное — 500/мин
• HMAC-SHA256 для подписи вебхуков
• Jinja2 SandboxedEnvironment для рендеринга шаблонов (без исполнения произвольного кода)
• API-ключи с возможностью отзыва для SDK-интеграций
• Мультитенантная изоляция — невозможно получить данные чужой организации

FAQ

Есть ли GraphQL? На данный момент API — REST. GraphQL в планах на 2026 Q3.

Какой формат ошибок? Стандартный: {"detail": "Not found"} с HTTP-кодами 400/401/403/404/409.

Можно ли использовать API без фронтенда? Да, API полностью самостоятельный. Фронтенд — один из клиентов.

Как тестировать вебхуки локально? Используйте ngrok или аналоги для проксирования на localhost. Mailpit на порту 8025 доступен для тестирования email.

Есть ли SDK для мобильных приложений? JavaScript SDK работает в браузере. Нативные мобильные SDK (iOS/Android) — в разработке.

Заключение

Trigly — платформа, спроектированная разработчиками для разработчиков. 290+ REST API эндпоинтов, событийный SDK, вебхуки с HMAC-подписью, 6 канальных адаптеров с единым интерфейсом и полноценная Docker-инфраструктура. Интеграция с вашим продуктом займёт не недели, а дни.

Итог

Trigly предоставляет разработчику полноценный API-first стек: 290+ REST-эндпоинтов, событийный SDK, вебхуки с HMAC-подписью, 6 канальных адаптеров с единым интерфейсом и Docker Compose для локальной разработки. Интеграция с вашим продуктом занимает 1-3 дня, а не недели. Начните с установки SDK и настройки event tracking — это фундамент для всех остальных возможностей.

---

Попробуйте API — бесплатный тариф включает полный доступ к API и SDK. Ознакомьтесь также с руководством по настройке вебхуков и работе с API-ключами.