API платформа

Проблема

Маркетинговые платформы часто создаются как закрытые системы с ограниченным API. Разработчики вынуждены использовать готовый интерфейс, который не покрывает все бизнес-потребности. Нестандартная интеграция, автоматизация процессов, построение кастомного UI, мобильное приложение -- всё это требует API, которого либо нет, либо он ограничен десятком CRUD-эндпоинтов.

Ещё одна проблема -- безопасность. Многие платформы используют API-ключи без срока действия, без ротации и без ролевого доступа. Один украденный ключ даёт полный доступ ко всей системе. Отсутствие rate limiting позволяет злоумышленнику перегрузить систему или извлечь всю базу контактов через бесконечные запросы.

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

Как работает API платформа Trigly

Trigly построена по принципу API-first: каждая функция платформы доступна через REST API. Веб-интерфейс -- лишь один из клиентов API.

290 REST API эндпоинтов организованы по модулям с единообразной структурой. Auth (10 эндпоинтов): регистрация, логин, refresh, logout, управление пользователями. CDP (76 эндпоинтов): клиенты (14), сегменты (13), события (5), импорт (5), API-ключи (3), RFM (4), объединение (2), bulk-операции (5), экспорт (3), коннекторы (8), lifecycle (2), идентичности (4), определения событий (4), аналитика (3), suppression (5). Campaigns (80 эндпоинтов): кампании (37), шаблоны (11), flows (14), A/B-тесты (5), триггеры (7), трекинг (4), вебхуки (5). Channels (38 эндпоинтов): конфигурация (20), аналитика (7), провайдерские вебхуки (4), SDK push/channels (7). Analytics (6 эндпоинтов). Conversions (10 эндпоинтов). Loyalty (14 эндпоинтов). AI Engine (26 эндпоинтов).

JWT-аутентификация реализована в core/security.py. Access token содержит payload: sub (user_id), org_id (organization_id), role (UserRole), type ("access"), jti (уникальный идентификатор). Срок жизни access token -- короткий, refresh token -- длительный. При refresh происходит ротация: старый refresh token аннулируется (is_revoked = true), выдаётся новая пара access + refresh. Это предотвращает повторное использование украденных токенов.

Ролевая модель: UserRole определяет три уровня доступа -- owner (полный доступ, включая управление организацией), admin (управление пользователями и настройками), member (операционный доступ). Функция require_role в dependencies.py ограничивает доступ к эндпоинтам по роли.

Мультитенантность: каждый запрос проходит через TenantResolverMiddleware, который извлекает user_id и organization_id из JWT и помещает в request.state. Все запросы к базе данных автоматически фильтруются по organization_id. Один клиент не может получить доступ к данным другого -- изоляция гарантирована на уровне архитектуры.

Rate limiting на Redis защищает от злоупотреблений. RateLimitMiddleware применяет три уровня лимитов: /api/v1/auth -- 200 запросов в минуту (защита от brute force), /api/v1/sdk -- 1000 запросов в минуту (высоконагруженный трекинг), все остальные эндпоинты -- 500 запросов в минуту. Счётчики хранятся в Redis с автоматическим TTL 60 секунд.

Публичные SDK-эндпоинты не требуют JWT-токена и предназначены для использования на фронтенде сайта клиента. POST /api/v1/sdk/track -- отправка пользовательских событий в ClickHouse. POST /api/v1/sdk/batch -- пакетная отправка событий. POST /api/v1/sdk/identify -- идентификация посетителя (привязка к профилю клиента). Аутентификация SDK -- через API-ключ организации (модель ApiKey в CDP). Rate limit 1000/мин защищает от злоупотреблений.

Дополнительные публичные эндпоинты: трекинг кампаний (pixel, click, unsubscribe), провайдерские вебхуки (/hooks/), push SDK (vapid-key, subscribe, sw.js), виджеты подписки и SDK каналов. Все перечислены в PUBLIC_PATHS middleware и не требуют JWT.

Асинхронная архитектура: FastAPI + SQLAlchemy async + asyncpg обеспечивают неблокирующую обработку запросов. Один процесс uvicorn обрабатывает тысячи одновременных соединений. ClickHouse-запросы выполняются через run_in_executor, чтобы не блокировать event loop.

Пагинация: PaginationParams (page, per_page) и PaginatedResponse[T] обеспечивают единообразную пагинацию по всему API. Курсорная пагинация через CursorService доступна для высоконагруженных списков.

Преимущества

1. Полное покрытие: 290 эндпоинтов покрывают каждую функцию платформы. Всё, что можно сделать в веб-интерфейсе, можно сделать через API. Это позволяет строить кастомные интерфейсы, мобильные приложения и автоматизации.

2. Безопасность на уровне архитектуры: JWT с ротацией, ролевой доступ, мультитенантная изоляция и Redis rate limiting обеспечивают защиту без компромиссов. HMAC-подписанные вебхуки дополняют картину.

3. Высокая производительность: асинхронный FastAPI обрабатывает тысячи запросов в секунду. ClickHouse для аналитических запросов, PostgreSQL для CRUD, Redis для кэширования и rate limiting -- каждая технология на своём месте.

4. Удобство для разработчиков: единообразные схемы запросов и ответов (Pydantic v2), стандартная пагинация, предсказуемые HTTP-коды ошибок (400, 401, 403, 404, 409). Документация Swagger/OpenAPI генерируется автоматически.

5. SDK для трекинга: публичные эндпоинты track, batch и identify позволяют интегрировать трекинг поведения на сайте за 10 минут. API-ключ обеспечивает безопасность без сложности JWT-аутентификации.

Сравнение с конкурентами

Mailchimp предлагает обширный API, но без real-time аналитики и с ограниченным SDK. SendPulse имеет API для основных функций, но без CDP-эндпоинтов и поведенческого трекинга. Mindbox предоставляет мощный API, но без публичных SDK-эндпоинтов для фронтенда.

Trigly уникальна в сочетании объёма (290 эндпоинтов), безопасности (JWT + rate limiting + мультитенантность) и удобства (публичный SDK + автогенерируемая документация). В отличие от Exponea, где API -- платная опция, в Trigly API -- основа платформы, доступная во всех тарифах. Асинхронная архитектура на FastAPI обеспечивает производительность, недостижимую для платформ на Ruby (Intercom) или PHP (Mailchimp).

Примеры по нишам

SaaS с кастомным UI: Стартап строит маркетинговый модуль внутри своего продукта. Вместо iframe или виджетов используется API Trigly: список кампаний через GET /api/v1/campaigns, создание кампании через POST, запуск через POST /api/v1/campaigns/{id}/launch. Пользователь работает в привычном интерфейсе продукта, а Trigly обеспечивает backend. SDK track/identify интегрирован в JavaScript фронтенда для поведенческого трекинга.

Мобильное приложение: Ритейлер создаёт мобильное приложение лояльности. API Trigly обеспечивает: регистрация через POST /api/v1/auth/register, профиль клиента через GET /api/v1/cdp/customers/{id}, баланс лояльности через GET /api/v1/loyalty/members/{id}, персональные предложения через GET /api/v1/ai/recommendations. JWT-аутентификация защищает данные. Rate limiting предотвращает DDoS.

Аналитическая интеграция: Аналитическое агентство подключает данные Trigly к BI-системе (Power BI, Tableau). API предоставляет: дашборд аналитики через GET /api/v1/analytics/dashboard, time series через GET /api/v1/analytics/time-series, revenue через GET /api/v1/analytics/revenue, campaign stats через GET /api/v1/campaigns/{id}/analytics. Пагинация PaginatedResponse позволяет извлечь все данные батчами.

Интеграции

API Trigly интегрируется с любой системой, поддерживающей HTTP/REST. Frontend Next.js использует api-client.ts для всех запросов с автоматическим refresh JWT. SDK JavaScript встраивается на сайт для трекинга. Celery задачи используют синхронный драйвер psycopg для фоновой обработки. ClickHouse доступен для аналитических запросов через API аналитики. Redis обеспечивает кэширование AI-генераций через AICache. Swagger UI доступен по адресу /docs для интерактивного тестирования.

Частые вопросы

Есть ли лимит на количество API-запросов? Да, Redis rate limiting ограничивает: 200/мин для auth, 1000/мин для SDK, 500/мин для остальных эндпоинтов. Лимиты применяются per-IP. При превышении возвращается HTTP 429 Too Many Requests с заголовком Retry-After.

Как получить API-ключ для SDK? Через эндпоинт POST /api/v1/cdp/api-keys (требует JWT admin/owner). API-ключ используется для SDK-эндпоинтов (track, batch, identify) через заголовок X-API-Key. Ключ можно отозвать через DELETE /api/v1/cdp/api-keys/{id}.

Поддерживается ли GraphQL? Нет, Trigly использует REST API. REST выбран за простоту, кэшируемость и совместимость с максимальным количеством клиентских библиотек. 290 эндпоинтов с Pydantic-схемами обеспечивают типизированный контракт, аналогичный по строгости GraphQL-схеме.

Лучшие практики

Используйте refresh token rotation. Не храните access token вечно. При каждом refresh запрашивайте новую пару access + refresh token. Trigly автоматически аннулирует старый refresh token, предотвращая повторное использование.

Обрабатывайте HTTP 429. При превышении rate limit API возвращает 429 Too Many Requests с заголовком Retry-After. Реализуйте exponential backoff в клиентском коде: подождите указанное время и повторите запрос.

Используйте пагинацию для больших списков. Не запрашивайте все контакты одним запросом. Используйте PaginationParams (page, per_page) для стандартных списков и CursorService для баз 100K+ контактов.

Типичные ошибки

Хранение JWT в localStorage без защиты. Access token в localStorage уязвим к XSS-атакам. Реализуйте автоматический refresh и короткий TTL access token. Trigly api-client.ts делает это автоматически.

Игнорирование ролевой модели. Не используйте owner-токен для операционных задач. Создайте отдельных пользователей с ролью member для API-интеграций и admin — для управления настройками.

Связанные материалы

• Webhook интеграции -- двусторонний обмен данными
• Профиль клиента 360° -- API для управления клиентскими данными
• Конструктор путей клиента -- программное управление flows
• Омниканальные кампании -- API для мультиканальных кампаний
• Качество данных -- API для управления качеством базы