docs/domains/income/upcoming-events.md

Будущие события

Будущие события помогают увидеть известные выплаты и даты по текущим позициям счёта. Обзор /accounts/:accountId показывает до пяти ближайших событий, полный список находится на /accounts/:accountId/events. Общий режим сохраняет отдельные строки событий каждого доступного счёта. Ошибка или пустой результат превью не заменяет основной портфель.

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

Смысл события

Событие	Источник и дата	Денежная оценка
Купон	Календарь облигации из MOEX bondization	Известная выплата на бумагу × текущая позиция
Дивиденд	T-Bank GetDividends, дата реестра record_date	dividend_net на бумагу × текущая позиция
Полное погашение	MOEX bondization	Известные условия погашения × текущая позиция
Оферта	MOEX bondization	Сумма не синтезируется, projectedAmount: null

Для дивиденда dateKind: registry явно означает дату закрытия реестра, а не гарантированную дату поступления денег. Отменённые выплаты Cancelled не включаются. Будущие частичные погашения и амортизация не синтезируются без надёжного расписания. Неизвестные или неприменимые денежные условия остаются null, а не заменяются нулём.

Суммы рассчитаны по количеству на calculatedAt. Они не учитывают будущие сделки, право владения на дату реестра и персональный налоговый расчёт. Есть неразрешённое ограничение интерпретации: основная спецификация и текущая подсказка экрана называют прогноз суммой «до налогов», но для дивиденда реализация только умножает dividend_net на количество. Налоговый смысл этого поля не подтверждён локальными материалами; на странице акции он также не трактуется как персональная сумма до или после налога. Расчёт подтверждён, налоговую формулировку требуется согласовать отдельно.

Период и список

Без фильтра период начинается сегодня в UTC и заканчивается через 30 дней после начала, обе даты включены. from и to принимают только строгие даты YYYY-MM-DD; без from используется текущая дата UTC, без to — from + 30 календарных дней. Поля «С» и «По» сохраняют выбранные календарные даты в URL, а «Сбросить» возвращает период по умолчанию.

События упорядочены по календарной дате. У каждой строки видны тип, инструмент, дата и доступная сумма в исходной валюте. Список не имеет пагинации и не конвертирует валюты. Пустой результат означает отсутствие известных поддерживаемых событий в выбранном окне, а не доказательство отсутствия всех будущих выплат. Инструмент без поддерживаемых данных не получает искусственную строку «нет данных».

Сохранённый forecast сохраняет свой calculatedAt и исходное включительное окно. GET для отдельного счёта или all возвращает только пересечение этого окна и запрошенного UTC-периода, не меняя ни calculatedAt, ни исходное окно. Пустое пересечение или отсутствие событий в пересечении — успешный пустой список с теми же metadata; это не отсутствие forecast. Неверный формат или несуществующая дата дают 400; обратный период — 400 INVALID_EVENTS_PERIOD без замены периода и без запуска личной работы. Фильтрация на сервере предшествует сортировке и вычислению incomeTotalsByCurrency, включающего только купоны и дивиденды. Итоги остаются в ответе API; полный экран показывает список без общего итога.

Получение и отказы

Запрос требует сессии, подключения и локально подтверждённого membership. Он читает сохранённый forecast и не запускает личную синхронизацию. Часовой обход строит forecast из полного личного portfolio и общих календарей: T-Bank для дивидендов, MOEX для bond events. Личные оценки сохраняются отдельно от общих календарей.

Последний полный forecast привязан к scope, исходному окну и membership. Если часовой обход не может получить полный новый forecast, прежний полный прогноз, его calculatedAt и исходное окно остаются читаемыми, в том числе после рестарта; meta.lastAttempt отдельно сообщает об ошибке обновления. Без полного forecast data: null и metadata обозначает initial loading либо временную недоступность, а не подтверждённое отсутствие выплат. В режиме all результат complete только при полном вкладе каждого включённого счёта. Другой scope или изменившийся membership не получают старый forecast под новым названием. Успешный ответ MOEX без запрошенного блока означает отсутствие поддерживаемых событий этого источника; это отличается от transport failure и повреждённого формата ответа.

При первом открытии без complete forecast показан каркас заголовка и строк, без интерактивных заглушек. Пустой успешный ответ сохраняет возможность изменить период. При failed HTTP reread уже полученный Client Cached Snapshot остаётся на экране; это отличается от server-side failed hourly attempt. Повторная попытка перечитывает только HTTP-ответ. Без выбранного счёта запрос не выполняется. Смена сессии и подключения следует общим правилам финансовых данных.

Внешние границы объясняют интеграции T-Bank и MOEX ISS, точные транспортные поля — HTTP API. Календарь конкретного выпуска и личные исполненные операции доступны на страницах акций и облигаций, где их смысл также разделён.