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 тимчасово недоступний, ви можете вручну завантажити Flex Query XML із сайту IBKR і використати його:

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

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

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

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

ℹ️ Якщо потрібно лише зберегти транзакції без створення декларацій, використовуйте команду 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

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

Після створення декларацій через команду 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 майбутніх декларацій 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, щоб відтворити період зі збережених транзакцій.

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