Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

English | Русский | Українська | Srpski | Српски

Использование

Быстрый старт

Если вы хотите быстро создать конкретную декларацию:

  1. Настройте данные (config) ↗ — один раз при первом запуске
  2. Загрузите последние данные (fetch) ↗
  3. Создайте отчет (report) ↗
  4. Загрузите созданный XML на портал ePorezi (раздел ППДГ-3Р)

Если нужно автоматически получать все декларации и вести учёт их статусов — используйте sync вместо шагов 2–3.

Настройка (config)

ibkr-porez config

Создание или изменение личных данных и настроек доступа к IBKR.

Вам будет предложено ввести:

  • IBKR Flex Token: Получение токена ↗
  • IBKR Query ID: Создание Flex Query ↗
  • Personal ID: JMBG / EBS
  • Full Name: Имя и Фамилия
  • Address: Адрес регистрации
  • City Code: 3-значный код муниципалитета. Пример: 223 (Нови Сад). Код можно найти в справочнике (смотрите колонку “Шифра”). Также код доступен в выпадающем списке на портале ePorezi.
  • Phone: Телефон
  • Email: Email
  • Data Directory: Абсолютный путь к папке с файлами данных (transactions.json, declarations.json, rates.json и т.д.). По умолчанию: ibkr-porez-data в папке приложения.
  • Output Folder: Абсолютный путь к папке для сохранения файлов из команд sync, export, export-flex, report. По умолчанию: папка Downloads вашей системы.

Получение данных (fetch)

ibkr-porez fetch

Загружает последние данные из IBKR и синхронизирует курсы валют с НБС (Национальный банк Сербии).

Сохраняет их в локальное хранилище.

Импорт исторических данных (import)

ibkr-porez import /path/to/activity_statement.csv

Загрузка истории транзакций старше 365 дней, которые невозможно получить через Flex Query (fetch).

Чтобы создать файл с транзакциями на портале Interactive Brokers смотрите Экспорт всей истории ↗

⚠️ Не забудьте после import выполнить fetch чтобы приложение добавило максимум деталей хотя бы за последний год в менее подробные данные загруженные из CSV.

Логика синхронизации (import + fetch)

При загрузке данных из CSV (import) и Flex Query (fetch) система отдает приоритет более полным данным Flex Query:

  • Данные Flex Query (fetch) являются источником правды. Они перезаписывают данные CSV за любые совпадающие даты.
  • Если запись Flex Query совпадает с CSV по смыслу (Дата, Тикер, Цена, Количество), это считается обновлением (заменой на официальный ID).
  • Если структура данных отличается (например, сплит ордеров в Flex Query против “склеенной” записи в CSV), старая запись CSV удаляется, а новые записи Flex Query добавляются.
  • Полностью идентичные записи пропускаются.

Синхронизация данных и создание деклараций (sync)

ibkr-porez sync

Делает все то же, что и fetch:

  • Загружает последние транзакции из IBKR через Flex Query
  • Синхронизирует курсы валют с НБС

После чего создает все необходимые декларации за последние 45 дней (если они уже не были созданы).

💡 Если соединение с IBKR не удалось, sync всё равно создаёт декларации из уже сохранённых локально транзакций и выводит предупреждение; команда завершается успешно, а в GUI повтор за свежими данными продолжается автоматически на следующем цикле.

Далее вы можете Управлять созданными декларациями.

💡 Если вы запустили sync в первый раз и она создала декларации которые вы уже подали до начала использования приложения вы можете быстро пометить их все как оплаченные и убрать из выдачи list:

ibkr-porez list --status submitted -1 | ibkr-porez pay

Синхронизация из скачанного XML файла (sync --file)

Если IBKR API временно недоступен, вы можете вручную скачать XML Flex Query с сайта IBKR и использовать его:

ibkr-porez sync --file /path/to/report.xml

Делает всё то же, что и sync — сохраняет транзакции, создаёт все необходимые декларации — но читает данные из локального файла, не обращаясь к IBKR API.

Смотрите как скачать XML Flex Query ↗.

В GUI та же возможность доступна в меню ☰ как Sync from Flex Query XML….

Просмотр статистики (stat)

ibkr-porez stat --year 2025
ibkr-porez stat --ticker AAPL
ibkr-porez stat --month 2025-01

Показывает:

  • Полученные дивиденды (в RSD)
  • Количество продаж (налогооблагаемых событий)
  • Оценку реализованного P/L (Капитальный доход) (в RSD)
  • Детальную разбивку по тикерам или месяцам (при использовании фильтров)

Генерация налогового отчета (report)

ibkr-porez report

Если не указать тип отчета и период то по умоланию генерируется ППДГ-3Р за последнее полное полугодие

  • Создаст ppdg3r_XXXX_HY.xml в Output Folder
  • Импортируйте этот файл на портал Налоговой администрации Сербии (ePorezi)
  • Вручную загрузите в пункт 8 файл с Документ подтверждения

Как выбрать другой тип декларации или период времени смотрите в документации

ibkr-porez report --help

Управление декларациями

После создания деклараций через команду sync вы можете просматривать их, изменять статус и экспортировать для загрузки на налоговый портал.

Список деклараций (list)

Показывает список всех деклараций с возможностью фильтрации по статусу.

# Показать активные декларации (по умолчанию):
# draft + submitted + pending
ibkr-porez list

# Показать все декларации
ibkr-porez list --all

# Фильтр по статусу
ibkr-porez list --status draft
ibkr-porez list --status submitted
ibkr-porez list --status pending
ibkr-porez list --status finalized

# Только ID деклараций (для использования в пайпах)
ibkr-porez list --ids-only
ibkr-porez list --status draft -1

Пример использования в linux-стиле:

# Отправить все черновики
ibkr-porez list --status draft -1 | ibkr-porez submit

Просмотр деталей декларации (show)

Показывает подробную информацию о конкретной декларации.

ibkr-porez show <declaration_id>

Отображает:

  • Тип декларации (PPDG-3R или PP OPO)
  • Период декларации
  • Статус (черновик, отправлена, ожидает решения, завершена)
  • Детали транзакций и расчетов
  • Для PPDG-3R: признанные налоговой доход/убыток рядом с расчётными, использованный перенос капитальных убытков (открытый/использованный/ скорректированный/закрытый остаток) и из каких “порций” он списан
  • Прикрепленные файлы

Подача декларации (submit)

ibkr-porez submit <id> [<id> ...]

Отмечает декларацию как поданную (импортированную на налоговый портал).

Поведение зависит от типа декларации:

  • PPDG-3R после submit переходит в статус pending (ожидание решения налоговой по сумме налога).
  • PP OPO после submit:
    • переходит в submitted, если есть налог к уплате;
    • сразу переходит в finalized, если налог к уплате 0.

Оплата декларации (pay)

ibkr-porez pay <id> [<id> ...]
ibkr-porez pay <id> --tax 1234.56

Отмечает декларацию как завершенную (finalized) и сохраняет дату оплаты.

Опция --tax позволяет сразу зафиксировать сумму налога при оплате, без отдельного шага assess.

После этого декларация исчезнет из списка показываемого list (без --all)

Фиксация суммы по решению налоговой (assess)

# Записать сумму налога по решению
ibkr-porez assess <declaration_id> --tax 1234.56

# Записать сумму и сразу отметить как уже оплаченную
ibkr-porez assess <declaration_id> --tax 1234.56 --paid

# Записать признанный налоговой убыток (только для PPDG-3R)
ibkr-porez assess <declaration_id> --loss 50000.00 \
    --reference "RES-123/2025" --date 2025-09-01

# Записать признанный налоговой доход (только для PPDG-3R)
ibkr-porez assess <declaration_id> --gain 12000.00

Команда нужна в первую очередь для PPDG-3R, где сумма налога, а также признанный капитальный доход/убыток определяются налоговой после подачи декларации.

Что делает команда:

  • записывает официальную сумму налога в метаданные декларации (--tax);
  • при --paid сразу переводит декларацию в finalized;
  • без --paid:
    • если сумма больше нуля, оставляет декларацию активной (submitted) для последующей оплаты;
    • если сумма равна нулю, переводит декларацию в finalized.

Должна быть указана хотя бы одна из опций: --tax, --gain, --loss.

--gain и --loss доступны только для PPDG-3R и записывают признанные налоговой капитальный доход/убыток — они сохраняются рядом с расчётными значениями приложения и могут от них отличаться (из-за CPI-корректировок или методики налоговой). Одно решение не может одновременно признавать и доход, и убыток.

--reference, --date и --notes — данные о решении (номер, дата, заметки). Они отображаются в show, а для признанного убытка номер и дата решения дополнительно подставляются в часть 7 будущих деклараций ППДГ-3Р (см. перенос капитальных убытков), поэтому их стоит записывать.

Если решение признаёт убыток (--loss больше нуля), создаётся (или обновляется) запись в реестре переноса капитальных убытков. Перенос всегда строится на признанном налоговой убытке, а не на расчётном.

⚠️ После того как перенесённый убыток хотя бы частично использован в одной из последующих деклараций, изменить признанный убыток через assess уже нельзя — команда вернёт ошибку.

Перенос капитальных убытков (carryforward)

ibkr-porez carryforward

Показывает список всех “порций” (vintages) признанных налоговой капитальных убытков, доступных для переноса на будущие периоды:

  • декларация-источник и период, за который убыток признан;
  • признанная и оставшаяся (неиспользованная) сумма;
  • налоговый год, после которого перенос “сгорает” (убыток можно переносить на 5 лет вперёд);
  • статус: Active (можно использовать), Exhausted (использован полностью), Expired (истёк срок).

В GUI тот же список доступен в меню ☰ → Capital loss carryforward….

Каждая декларация ППДГ-3Р, создаваемая через sync, автоматически уменьшает расчётную налоговую базу за счёт доступных переносов (от старых периодов к новым), пока база не обнулится или переносы не закончатся. Предпросмотр report показывает использованную и оставшуюся после этого сумму переноса. Сумма списывается из реестра один раз — при сохранении декларации; повторный sync за тот же период ничего не списывает повторно.

Переносимые убытки также заявляются в самой декларации: в XML ППДГ-3Р заполняется часть 7 («Капитални губици») — по строке на каждый действующий перенос, с номером и датой решения налоговой (7.2/7.3) и оставшейся суммой убытка (7.4). Итоговые Osnovica и PorezZaUplatu в XML тоже учитывают применённый перенос. Заявить убыток в части 7 обязан сам налогоплательщик — без этого налоговая не применит его в решении.

Номер и дата решения берутся из assess (--reference и --date). Если они не записаны, поля 7.2/7.3 в XML останутся пустыми, а report выведет предупреждение — запишите их через assess и сгенерируйте отчёт заново, либо заполните эти поля на портале вручную.

Экспорт декларации (export)

ibkr-porez export <declaration_id>
ibkr-porez export <declaration_id> -o /path/to/output

Копирует XML и все прикрепленные файлы (attach) в Output Folder или в указанный в параметрах каталог.

Откат статуса декларации (revert)

# Откатить к черновику (по умолчанию)
ibkr-porez revert <id> [<id> ...]

# Откатить к отправленной
ibkr-porez revert <id> [<id> ...] --to submitted

Откатывает статус декларации.

Удаление декларации (delete)

# Предпросмотр плана (ничего не меняет)
ibkr-porez delete <id>

# Удалить декларацию
ibkr-porez delete <id> --yes

# Разрешить удаление не-черновой декларации
ibkr-porez delete <id> --yes --force

Удаляет декларацию и откатывает её влияние на леджер переносов: перенос убытков, который она использовала, возвращается исходным «траншам», а её собственный «транш» признанного убытка (созданный через assess) удаляется. Если вы удалили декларацию, чтобы исправить ошибку, затем запустите sync, чтобы пересоздать период из сохранённых транзакций.

Без --yes только выводит, что будет удалено. --force требуется для удаления не-черновой декларации. Удалить можно только самый последний PPDG-3R — удаление более раннего оставило бы «висящим» перенос у более поздних деклараций; декларации PP OPO можно удалять в любое время.

Так же исправляется признанный убыток предыдущей декларации, который уже использовала более поздняя: удалите более позднюю декларацию (освобождая перенос), заново выполните assess на ранней, затем sync для пересоздания.

В GUI то же действие доступно кнопкой Delete в строке декларации: она открывает диалог-подтверждение (вместо --yes) с галочкой Force для не-черновых деклараций.

Прикрепление файла к декларации (attach)

# Прикрепить файл
ibkr-porez attach <declaration_id> /path/to/file.pdf

# Удалить прикрепленный файл
ibkr-porez attach <declaration_id> <file_id> --delete
ibkr-porez attach <declaration_id> --delete --file-id <file_id>

Прикрепляет файл к декларации или удаляет прикрепленный файл из хранилища деклараций.

Для сохранения в хранилище деклараций используется только имя файла (путь отбрасывается), поэтому имена должны быть уникальные - иначе файл с тем же именем перезатрет ранее загруженный с таким же именем пусть и из другого пути

💡 Прикрепленные файлы копируются как и XML декаларации при экспорте (export)

Экспорт Flex Query (export-flex)

ibkr-porez export-flex 2025-01-15
ibkr-porez export-flex 2025-01-15 -o /path/to/output.xml
ibkr-porez export-flex 2025-01-15 -o -  # Вывод в stdout (для пайпов)

Экспортирует XML файл Flex Query полученный при fetch или sync в указанную дату.

Пример использования в linux-стиле:

ibkr-porez export-flex 2025-01-15 | ibkr-porez sync --file -