Швидкий старт

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

Автоматична генерація податкових декларацій ППДГ-3Р (приріст капіталу) та ПП ОПО (доходи від капіталу) для користувачів Interactive Brokers у Сербії.

Програма завантажує ваші угоди з Interactive Brokers і створює готовий XML-файл для ePorezi. Вона відстежує весь ланцюг покупок і продажів по кожному цінному паперу, розраховує прибутки та збитки, і перераховує всі суми в динари за офіційним курсом НБС на дату кожної угоди — саме так, як вимагає декларація.

Встановлення

⚠️ Windows і macOS заблокують завантаження або запуск — програма розповсюджується безкоштовно, і платити ~100 євро на рік за сертифікат розробника немає можливості. В інструкції зі встановлення написано як це обійти — прочитайте її перед завантаженням.

Інструкція зі встановлення ↗

Як користуватися

Відкрийте програму — вона запуститься з графічним інтерфейсом.
Натисніть Config і введіть свої дані Interactive Brokers.
Натисніть Sync now — програма завантажить останні угоди і створить декларації.
Завантажте створений XML-файл на портал ePorezi (розділ ППДГ-3Р).

ППДГ-3Р

💡 Після цього, поки програма відкрита, вона сама перевіряє наявність нових даних — раз на день, у фоновому режимі, повторюючи спроби до успіху. Статус останньої спроби завжди видно у верхній частині вікна.

ℹ️ Якщо у вас більше року історії угод в Interactive Brokers — перед першим Sync потрібно завантажити старі дані вручну. Як це зробити ↗

Детальна документація по командному рядку та іншим можливостям — у розділі Використання ↗.

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

Встановлення

Інсталятор

Завантажте готовий інсталятор зі сторінки релізів:

https://github.com/andgineer/ibkr-porez/releases

macOS

Завантажте останній .pkg файл. Оскільки інсталятор не підписаний сертифікатом Apple, macOS заблокує його під час відкриття.

“IBKR Porez” пошкоджено й не можна відкрити. Слід перемістити його в кошик.

Не переміщуйте в кошик. Замість цього:

Відкрийте Системні налаштування → Конфіденційність і безпека
У нижній частині розділу «Безпека» з’явиться повідомлення про заблокований застосунок — натисніть «Все одно відкрити»
У наступному діалоговому вікні підтвердьте відкриття

Може знадобитися повторити ці кроки двічі:

спочатку під час відкриття завантаженого інсталятора (.dmg)
а потім під час першого запуску встановленого застосунку з /Applications

Після цього застосунок має запускатися без попереджень.

Windows

Завантажте останній .msi файл. Оскільки інсталятор не підписаний цифровим підписом, Windows може показувати попередження безпеки.

Якщо браузер блокує завантаження (наприклад, у Microsoft Edge):

Відкрийте панель завантажень браузера (Ctrl+J)
Знайдіть заблоковане завантаження .msi
Натисніть «Зберегти» → «Показати більше» → «Зберегти все одно»

Під час запуску інсталятора Windows може показати Windows захистив ваш ПК:

Натисніть «Докладніше»
Натисніть «Запустити все одно»

Також може з’явитися вікно контролю облікових записів із написом Невідомий видавець. Якщо файл завантажено з офіційної сторінки релізів, натисніть «Так», щоб продовжити.

Після встановлення IBKR Porez з’явиться в меню Пуск.

Для досвідчених користувачів

Інсталятор також встановлює команду ibkr-porez для терміналу (може знадобитися перезапуск терміналу після встановлення).

Завантажити готовий бінарний файл

Також можна завантажити бінарні файли для вашої платформи зі сторінки релізів:

https://github.com/andgineer/ibkr-porez/releases

Архів містить обидва бінарні файли: ibkr-porez (CLI) та ibkr-porez-gui (GUI). Розпакуйте архів і помістіть файли в директорію, що є в PATH.

Збірка з вихідного коду

Якщо у вас встановлено Rust:

cargo install ibkr-porez

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

Використання

Швидкий старт

Якщо ви хочете швидко створити конкретну декларацію:

Налаштуйте дані (config) ↗ — один раз при першому запуску
Завантажте останні дані (fetch) ↗
Створіть звіт (report) ↗
Завантажте створений 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, поки його дата залишається всередині цих 45 днів. Позначки «синхронізовано до такого-то дня» не існує, тому запізнілі дані не втрачаються.

Старіший дохід застосунок не декларує з власної ініціативи: строк подання за ним уже минув, тож подавати його — ваше рішення. Попросіть про це явно, розширивши вікно:

# задекларувати незадекларований дохід за останні 400 днів
ibkr-porez sync --lookback 400

💡 Якщо з’єднання з IBKR не вдалося, sync усе одно створює декларації з уже локально збережених транзакцій і виводить попередження; команда завершується успішно, а в GUI повторні спроби за свіжими даними тривають автоматично на наступному циклі.

Далі ви можете Керувати створеними деклараціями.

💡 Якщо ви запустили sync уперше і вона створила декларації, які ви вже подали до початку використання застосунку, ви можете швидко позначити їх усі як сплачені й прибрати з виводу list:
ibkr-porez list --status submitted -1 | ibkr-porez pay

Синхронізація з завантаженого XML файлу (`sync --file`)

Якщо IBKR API тимчасово недоступний, ви можете вручну завантажити Flex Query XML із сайту IBKR і використати його:

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

Робить усе те саме, що й sync — зберігає транзакції, створює всі необхідні декларації — але читає дані з локального файлу, не звертаючись до IBKR API.

Дивіться як завантажити Flex Query XML ↗.

У GUI та сама можливість доступна в меню ☰ як Sync from file….

Змінені декларації

Утриманий за кордоном податок не остаточний. Після закриття року американський фонд повідомляє брокеру остаточний податковий характер торішніх виплат, і брокер сторнує утримане — звичайний випадок для казначейського ETF, виплата якого виявилася процентним дивідендом, — а якщо новий характер того вимагає, утримує заново. Це відбувається в строк від кількох тижнів до приблизно п’ятнадцяти місяців після виплати.

Коли суми, на яких побудована вже створена декларація PP OPO, змінюються, наступний sync створює змінену декларацію (измењена пријава). Це звичайна декларація в усьому: вона потрапляє до list, отримує свій XML у теці виводу, подається й оплачується як будь-яка інша. Під рядком про створену декларацію sync друкує дату отримання доходу та номер оригіналу — те, за чим оригінал знаходиться в таблиці ePorezi.

Змінену декларацію потрібно подати: вона замінює первісну. Якщо номер оригіналу записано через submit --number, він уже в документі; інакше впишіть його в ePorezi, знайшовши оригінал за датою отримання доходу.

Порівняння робиться у валюті доходу, тому змінений курс ніколи не призводить до зміненої декларації. Такі зміни sync шукає до 1 січня попереднього року, яким би не було вікно створення нових декларацій.

ℹ️ Якщо потрібно лише зберегти транзакції без створення декларацій, використовуйте команду import.

Перегляд статистики (`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

ПП ОПО за період (`report --type income`)

# дохід поточного місяця по сьогоднішній день
ibkr-porez report --type income

# явно заданий період
ibkr-porez report --type income --start 2025-07-01 --end 2025-12-31

Записує в папку виводу по одному XML ПП ОПО на кожну групу доходу і більше нічого не робить: декларація при цьому не створюється, тому такі файли не потрапляють до list, не звіряються з тим, що вже створив sync, і ніколи не призводять до змінених декларацій. Декларації, які ви збираєтеся вести, створює sync.

Група, за якою ще не надійшов утриманий податок, не записується. Замість файлу команда друкує, з якої дати вона буде задекларована: податок зазвичай проводиться протягом кількох днів після доходу, і документ із зарахуванням, яке брокер ще не дорахував, варто зачекати. Після цієї дати група записується з нульовим зарахуванням і повними 15% до сплати — саме це ви подаєте, якщо податок так і не надійде.

--force це очікування не скорочує. Він означає лише «згенерувати за приблизними даними»: якщо в Народного банку немає курсу на дату, береться найближчий із кешу, а якщо немає даних про свята за рік, строк сплати рахується тільки за робочими днями.

Керування деклараціями

Після створення декларацій через команду 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> ...]

# записати номер, який податковий портал присвоїв декларації
ibkr-porez submit <id> --number 1234567890

Позначає декларацію як подану (імпортовану на податковий портал).

Поведінка залежить від типу декларації:

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

--number записує номер декларації на податковому порталі — від 1 до 19 цифр, для однієї декларації за раз. Якщо декларацію згодом доведеться змінити, змінена декларація несе цей номер, щоб податкова розуміла, яку декларацію вона замінює. Без нього змінена декларація все одно створюється, а номер ви вписуєте в ePorezi.

У GUI кнопка Submit відкриває діалог підтвердження з тим самим необов’язковим полем.

Оплата декларації (`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 майбутніх декларацій PPDG-3R (див. перенесення капітальних збитків), тому їх варто записувати.

Якщо рішення визнає збиток (--loss більший за нуль), створюється (або оновлюється) запис у реєстрі перенесення капітальних збитків. Перенесення завжди ґрунтується на збитку, визнаному податковою, а не на розрахунковому.

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

Перенесення капітальних збитків (`carryforward`)

ibkr-porez carryforward

Показує список усіх “траншів” (vintages) капітальних збитків, визнаних податковою, доступних для перенесення на майбутні періоди:

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

У GUI той самий список доступний у меню ☰ → Capital loss carryforward….

Кожна декларація PPDG-3R, що створюється через sync, автоматично зменшує розрахункову податкову базу за рахунок доступних перенесень (від старих періодів до нових), доки база не обнулиться або перенесення не закінчаться. Попередній перегляд report показує використану і залишкову після цього суму перенесення. Сума списується з реєстру один раз — при збереженні декларації; повторний sync за той самий період нічого не списує повторно.

Перенесені збитки також заявляються в самій декларації: у XML PPDG-3R заповнюється частина 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, щоб відтворити період зі збережених транзакцій — до PP OPO з датою доходу, старшою за 45 днів, дотягнеться sync --lookback N.

Без --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 import

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

Interactive Brokers (IBKR)

Flex Web Service

Performance & Reports > Flex Queries.
Натисніть на значок Налаштувань (шестерня) у “Flex Web Service Configuration”.
Увімкніть Flex Web Service.
Згенеруйте Token (Generate Token).
- Важливо: Скопіюйте цей токен одразу. Ви не зможете побачити його повністю ще раз.
- Встановіть термін дії (рекомендується максимум - 1 рік).

Flex Query

Performance & Reports > Flex Queries.
Натисніть +, щоб створити новий Activity Flex Query.
Name: наприклад, ibkr-porez-data.
Delivery Configuration (внизу сторінки):
- Period: Виберіть Last 365 Calendar Days.
Format: XML.

Розділи для увімкнення (Sections):

Увімкніть такі розділи і позначте Select All (Вибрати все) для колонок.

Якщо ви нікому не довіряєте 8-) замість Select All виберіть щонайменше поля, перелічені в Обов'язкові колонки.

Trades - Угоди

Знаходиться у розділі Trade Confirmations або Activity.

Обов'язкові колонки

Symbol
Description
Currency
Quantity
TradePrice
TradeDate
TradeID
OrigTradeDate
OrigTradePrice
AssetClass
Buy/Sell

Cash Transactions - Грошові транзакції

Обов'язкові колонки

Type
Amount
Currency
DateTime / Date
Symbol
Description
TransactionID

Збережіть і отримайте Query ID

Запишіть Query ID (число, яке зазвичай відображається поруч із назвою запиту у списку).

Вам знадобляться Token і Query ID для налаштування ibkr-porez.

Документ-підтвердження

Для Пункту 8 (Докази уз пријаву) податкової декларації ППДГ-3Р вам знадобиться PDF-звіт від брокера. Його потрібно прикріпити вручну на порталі ePorezi після імпорту XML.

Як завантажити відповідний звіт:

У IBKR перейдіть до Performance & Reports > Statements > Activity Statement.
Period: Виберіть Custom Date Range.
Вкажіть дати, що відповідають вашому податковому періоду (наприклад, 01-01-2024 до 30-06-2024 для першого півріччя).
Натисніть Download PDF.
На порталі ePorezi, у розділі 8. Докази уз пријаву завантажте цей файл.

Завантаження Flex Query XML (для `sync --file`)

Якщо IBKR API (sync / fetch) тимчасово недоступний, ви можете запустити Flex Query вручну через сайт IBKR:

У IBKR перейдіть до Performance & Reports > Statements > Flex Queries.
Знайдіть запит, створений для ibkr-porez (наприклад, ibkr-porez-data).
Натисніть Run (синя стрілка праворуч від назви запиту).
Виберіть формат XML і завантажте файл.
Використайте файл з командою sync --file ↗ або опцією Sync from file… у меню ☰ в GUI.

Експорт повної історії (для команди import)

Якщо вам потрібно завантажити історію транзакцій за період понад 1 рік (що недоступно через Flex Web Service), експортуйте дані в CSV:

У IBKR перейдіть до Performance & Reports > Statements > Activity Statement.
Period: Виберіть Custom Date Range і вкажіть увесь період від моменту відкриття рахунку.
Натисніть Download CSV.
Цей файл можна використати з командою import ↗.

Імпорт CSV постачає історію купівель для розрахунку приросту капіталу і більше нічого. Дивіденди, відсотки та утриманий податок із нього ніколи не породжують декларації про дохід (PP OPO) — вони формуються лише зі звіту Flex Query.

Keyboard shortcuts

ibkr-porez