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 дней после начала, обе даты включены. Поля «С» и «По» позволяют изменить период: «Применить» сохраняет выбранные календарные даты в URL и запрашивает результат, «Сбросить» возвращает период по умолчанию. Обзор счёта сохраняет прогноз на текущую дату и следующие 30 дней.

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

API принимает необязательные from и to в формате YYYY-MM-DD для отдельного и общего счёта. Без from используется сегодня в UTC, без to — 30 дней после начала. Неверный формат или несуществующая дата дают 400; обратный период — 400 INVALID_EVENTS_PERIOD. Фильтрация на сервере предшествует сортировке и вычислению incomeTotalsByCurrency, включающего только купоны и дивиденды. Итоги остаются в ответе API; полный экран показывает список без общего итога.

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

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

Последний полный forecast привязан к scope, периоду и membership. Если новый portfolio требует ещё недоступного календаря, прежний полный прогноз и его source times остаются, в том числе после рестарта. Новый полный результат заменяет его атомарно. Без fallback показывается missing/partial, а не подтверждённое отсутствие выплат. Другой период или изменившийся membership не получают старый прогноз под новым названием. Source failure сообщается в metadata и не изменяет успешное время. Успешный ответ MOEX без запрошенного блока означает отсутствие поддерживаемых событий этого источника; это отличается от transport failure и повреждённого формата ответа.

При первом открытии показан каркас заголовка и строк, без интерактивных заглушек. Пустой ответ сохраняет возможность изменить период. При обычном фоновом обновлении уже полученные данные остаются на экране, ошибка получает предупреждение и повторную попытку. Без выбранного счёта запрос не выполняется. Смена сессии и подключения следует общим правилам финансовых данных.

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