Заказчик

Только с опытом работы с trade api FINAM
# Техническое задание: Система отчетности по торговым операциям Финам

## 📋 Общее описание

Разработать систему для получения детализированных отчетов по всем торговым операциям брокерского счета Финам через Trade API. Система должна автоматически управлять токенами доступа и предоставлять отчеты по запросу.

---

## 🎯 Основные требования

**История сделок:** `GET /v1/accounts/{account_id}/trades` – дата, инструмент, направление (покупка/продажа), количество, цена, объем, комиссии, НДС

**История транзакций:** `GET /v1/accounts/{account_id}/transactions` – дата, тип (пополнение, вывод, дивиденды, купоны), сумма, валюта

**История поручений:** `GET /v1/accounts/{account_id}/orders` – дата создания/исполнения, статус, инструмент, направление, тип поручения, комиссии

**Расходы и комиссии:** Группировка по инструментам, датам, типам операций, общая сумма

**Операции покупки/продажи:** Разделение операций, группировка по инструментам, расчет средней цены, прибыли/убытка

---

## 🔐 Управление токенами

**Требование:** JWT токен обновляется автоматически каждые 15 минут (за 2 минуты до истечения).

**Механизм:** При запуске проверка валидности токена. Перед каждым запросом проверка времени истечения, обновление за 2 минуты до истечения. При ошибке 401 автоматическое получение нового токена и повтор запроса.

**Детали:** Secret токен в `config.json`. JWT генерируется через `POST /v1/sessions` или gRPC `AuthService.Auth`. Срок действия JWT: 15 минут, обновление на 13-й минуте. Автоматическое сохранение нового токена.

---

## 📊 Формат отчетов

**Структура:** Общая информация (период, счет, баланс), сводка (количество операций, комиссии, прибыль), детализация сделок, комиссии по инструментам/датам, операции покупки/продажи, транзакции, аналитика

**Форматы:** JSON, CSV, HTML, PDF, Excel (XLSX)

---

## 🔧 Технические требования

**API:** Base URL `api.finam.ru`
- Аутентификация: `POST /v1/sessions` (X-Api-Key: {secret_token})
- Сделки: `GET /v1/accounts/{account_id}/trades?interval={from},{to}`
- Транзакции: `GET /v1/accounts/{account_id}/transactions?interval={from},{to}`
- Поручения: `GET /v1/accounts/{account_id}/orders?interval={from},{to}`

**Формат:** `account_id` без "КлФ-", `interval` в Unix epoch (секунды), инструменты `SYMBOL@MIC`

**Ошибки:** 401 – обновление токена, 429 – лимит 200 запросов/минуту, 503 – обслуживание 05:00-06:15 МСК

**Производительность:** Кэширование (5-10 мин), параллельные запросы, пагинация

---

## 📋 Чек-лист

1. Управление токенами с автообновлением
2. Клиент API (сделки, транзакции, поручения)
3. Обработка данных (группировка, комиссии, покупки/продажи)
4. Генерация отчетов (JSON, CSV, HTML, PDF, Excel)
5. Фильтрация, кэширование, обработка ошибок
6. Тестирование и оптимизация

---

## ⚠️ Важные замечания

1. **Безопасность:** Secret токен в безопасном месте, не коммитить, использовать переменные окружения
2. **Лимиты:** 200 запросов/минуту на метод
3. **Обслуживание:** 05:00-06:15 МСК недоступность сервиса
4. **Формат:** Инструменты `SYMBOL@MIC`, `account_id` без "КлФ-", timestamp Unix epoch
5. **Токены:** Secret не истекает, JWT 15 минут, автообновление обязательно

**Документация:** tradeapi.finam.ru/docs/ab... | **Поддержка:** trade_api@corp.finam.ru