Интеграция по API (расширенная интеграция)
Скрытая страница: доступ только по прямой ссылке. Не добавлена в меню и навигацию.
Клиент может строить собственный интерфейс на своём сайте и использовать только бэкенд TrackFlow через REST API.
1. Общие сведения
- Базовый URL API:
https://<ваш-домен-бэкенда>/api/v1(в разработке:http://localhost:8000/api/v1) - Аутентификация: JWT (Bearer token). Токен выдаётся при входе партнёра/менеджера.
- Формат: JSON. Заголовок
Content-Type: application/jsonдля запросов с телом. - Документация: Swagger —
/docs, ReDoc —/redoc. - Для кросс-доменных запросов на бэкенде должен быть настроен CORS (домен клиента в
allowed_origins).
2. Получение токена (вход)
POST /api/v1/managers/auth/login
Тело: { "email": "...", "password": "..." }
Ответ: { "access_token": "...", "token_type": "bearer" }
Дальше все запросы: заголовок Authorization: Bearer <access_token>
3. Профиль
GET /api/v1/managers/auth/me — данные текущего менеджера и заявки на доступ (Bearer обязателен).
4. Эндпоинты по разделам
Во всех ниже перечисленных эндпоинтах требуется заголовок Authorization: Bearer <token> (кроме публичных).
4.1. Аутентификация и профиль
| Метод | Путь | Описание |
|---|---|---|
| POST | /managers/auth/login | Вход → access_token |
| GET | /managers/auth/me | Текущий менеджер и заявки |
| POST | /managers/auth/request-access | Заявка на доступ (project_url) |
| POST | /managers/auth/password-reset/request | Запрос сброса пароля |
| POST | /managers/auth/password-reset/confirm | Подтверждение сброса |
4.2. Проекты
| Метод | Путь | Описание |
|---|---|---|
| GET | /projects/ | Список проектов |
| GET | /projects/active/ | Активные проекты |
| GET | /projects/{id} | Проект по ID |
| GET | /projects/stats/overview | Сводка (ADMIN/OWNER) |
| GET | /projects/domain/{domain} | Проект по домену |
| GET | /projects/search/ | Поиск |
4.3. Кампании
| Метод | Путь | Описание |
|---|---|---|
| GET | /campaigns/ | Список (page, size, manager_id, project_id, product_id, is_active, search) |
| GET | /campaigns/stats | Статистика кампаний |
| GET | /campaigns/search | Поиск |
| GET | /campaigns/{id} | Кампания по ID |
| POST | /campaigns/ | Создание |
| PUT | /campaigns/{id} | Обновление |
| PATCH | /campaigns/{id}/activate | Активация |
| PATCH | /campaigns/{id}/deactivate | Деактивация |
| DELETE | /campaigns/{id} | Удаление |
| GET | /campaigns/{id}/link | Ссылка трекинга (query: base_domain) |
| GET | /campaigns/manager/{manager_id} | Кампании менеджера |
| GET | /campaigns/project/{project_id} | Кампании проекта |
4.4. Продукты
| Метод | Путь | Описание |
|---|---|---|
| GET | /products/open/list | Открытый список |
| GET | /products/project/{project_id} | По проекту |
| GET | /products/{id} | По ID |
| GET | /products/manager/{manager_id} | Доступные менеджеру (только свой id) |
4.5. Статистика
| Метод | Путь | Описание |
|---|---|---|
| GET | /stats/managers/{manager_id}/summary | Сводка (date_from, date_to) |
| GET | /stats/managers/{manager_id}/trend | Тренд (group_by: day|week|month) |
| GET | /stats/managers/{manager_id}/campaigns/top | Топ кампаний |
| GET | /stats/projects/{project_id}/summary | Сводка по проекту |
| GET | /stats/projects/{project_id}/trend | Тренд по проекту |
| GET | /stats/campaigns/{campaign_id}/summary | Сводка по кампании |
| GET | /stats/analytics/performance | Метрики |
| GET | /stats/reports/daily | Ежедневный отчёт |
| GET | /stats/reports/weekly | Еженедельный |
| GET | /stats/reports/monthly | Ежемесячный |
| GET | /stats/export/csv | Экспорт CSV |
| GET | /stats/aggregates/ | Агрегаты |
| GET | /stats/comparison | Сравнение периодов |
4.6. Биллинг (партнёр)
| Метод | Путь | Описание |
|---|---|---|
| GET | /billing/manager/balance/ | Баланс (query: manager_id — только свой) |
| GET | /billing/manager/transactions/ | Транзакции (manager_id — только свой) |
| GET | /billing/manager/reward-rules/ | Правила по продукту (product_id) |
| POST | /billing/manager/withdrawal-requests/ | Создать заявку на вывод |
| GET | /billing/manager/withdrawal-requests/ | Список заявок (manager_id — только свой) |
| GET | /billing/manager/withdrawal-requests/{id}/ | Заявка с сообщениями |
| POST | /billing/manager/withdrawal-requests/upload | Загрузка файла |
| POST | /billing/manager/withdrawal-requests/{id}/messages/ | Сообщение в заявке |
4.7. Поддержка (тикеты)
| Метод | Путь | Описание |
|---|---|---|
| POST | /support/tickets/upload | Загрузка файла |
| POST | /support/tickets | Создать тикет (Form: topic, title, message, attachments) |
| GET | /support/tickets | Список (topic, status, limit, offset) |
| GET | /support/tickets/{id} | Тикет по ID |
| POST | /support/tickets/{id}/messages | Добавить сообщение |
| PATCH | /support/tickets/{id}/status | Обновить статус |
4.8. Webhooks
GET /api/v1/webhooks/stats/overview — статистика (ADMIN/OWNER).
4.9. Домены
GET /domains/, /domains/stats, /domains/manager/?manager_id=... — при необходимости см. Swagger.
5. Публичные эндпоинты (без Bearer)
- Трекинг: GET
https://<трекер-домен>/click/{link_token}— редирект по ссылке кампании. - Конверсии (postback): POST
/api/v1/conversions/events, заголовокX-API-Token(токен проекта). Тело: массив событий (event, click_id, value).
6. Требования к клиенту
- Хранить токен безопасно (не в URL, не логировать).
- При 401 — перенаправить на вход и получить новый токен.
- Во всех эндпоинтах с
manager_idиспользовать только свойidизGET /me. - Домен фронта клиента должен быть в CORS на бэкенде.
- В проде — только HTTPS.
- Даты: формат
YYYY-MM-DD.