Посібник з міграції з QuickBooks до Beancount
Етап 1: Експорт даних із QuickBooks
Міграція даних за п'ять років починається з вивантаження всіх записів із QuickBooks у придатному для використання форматі. QuickBooks Desktop та QuickBooks Online мають різні опції експорту:
1.1 QuickBooks Desktop – Опції експорту
IIF (Intuit Interchange Format): QuickBooks Desktop може експортувати списки (як-от план рахунків, клієнти, постачальники) у текстові файли .IIF
. У QuickBooks Desktop перейдіть до Файл → Утиліти → Експорт → Списки до IIF, а потім виберіть потрібні списки (наприклад, План рахунків, Клієнти, Постачальники). Це створить текстовий файл, що містить назви рахунків, їхні типи та дані списків. IIF — це пропрієтарний, але текстовий формат, який відносно легко аналізувати. Використовуйте його для отримання вашого Плану рахунків та списків контактів для подальшого використання в Beancount.
Головна книга/Журнал через CSV: Для експорту транзакцій QuickBooks Desktop не надає повного експорту в один клік, але можна використовувати звіти. Рекомендований метод — експортувати Головний журнал (усі транзакції) за потрібний період. У QuickBooks Desktop відкрийте Звіти → Бухгалтер та податки → Журнал, встановіть Дати від найранішої транзакції до сьогодні, та натисніть Експорт → Excel. Збережіть результат як CSV, видаливши заголовки/нижні колонтитули звіту та порожні стовпці. Переконайтеся, що числові дані чисті: вони мають містити центи (наприклад, 3.00
, а не 3
), не мати зайвих лапок, символів валют або подвійних мінусів у CSV. CSV-файл повинен мати стовпці, такі як Дата, № транзакції, Назва, Рахунок, Примітка, Дебет, Кредит, Залишок (або єдиний стовпець "Сума" залежно від формату звіту).
Порада: QuickBooks Desktop 2015+ також може експортувати транзакції через діалогове вікно Знайти. Використовуйте Редагувати → Знайти → Розширений пошук, встановіть діапазон дат на п'ять років, а потім експортуйте результати у CSV. Увага: Деякі версії обмежують експорт 32,768 рядками. Якщо у вас дуже великий обсяг даних, експортуйте їх по роках (або меншими частинами), щоб уникнути обрізання, а потім об'єднайте їх. Переконайтеся, що діапазони дат не перетинаються, щоб уникнути дублікатів.
Інші фо рмати (QBO/QFX/QIF): QuickBooks Desktop може імпортувати банківські транзакції через файли .QBO
(Web Connect) або .QFX/.OFX
, але для експорту з QuickBooks вони зазвичай не використовуються. Якщо ваша мета — витягти лише банківські транзакції, ви, можливо, вже маєте їх у форматі QBO/OFX від вашого банку. Однак для повного експорту книги дотримуйтесь IIF та CSV. QuickBooks Desktop не може безпосередньо експортувати у QIF (Quicken Interchange Format) без сторонніх інструментів. Якщо ви все ж знайдете спосіб отримати QIF, зауважте, що деякі інструменти для ведення обліку (старі версії Ledger 2.x) могли читати QIF, але для нашого процесу краще працювати з CSV.
1.2 QuickBooks Online – Опції експорту
Вбудований експорт в Excel/CSV: QuickBooks Online (QBO) надає інструмент Експортувати дані. Перейдіть до Налаштування ⚙ → Інструменти → Експортувати дані. У діалоговому вікні експорту на вкладці Звіти виберіть дані (наприклад, Головна книга або Список транзакцій), а на вкладці Списки — списки (план рахунків тощо), оберіть Усі дати та експортуйте в Excel. QuickBooks Online завантажить ZIP-архів, що містить кілька файлів Excel для вибраних звітів та списків (наприклад, Звіт про прибутки та збитки, Балансовий звіт, Головна книга, Клієнти, Постачальники, План рахунків тощо). Потім ви можете конвертувати ці файли Excel у CSV для обробки.
Звіт про деталізацію транзакцій: Якщо стандартний експорт QBO не містить єдиного файлу Головної книги, ви можете вручну створити детальний звіт:
- Перейдіть до Звіти та знайдіть Деталізація транзакцій за рахунком (або Головна книга в деяких версіях QBO).
- Встановіть Період звіту на повний п'ятирічний діапазон.
- В опціях звіту встановіть Групувати за = Немає (щоб перелічити окремі транзакції без проміжних підсумків).
- Налаштуйте стовпці, щоб включити принаймні: Дата, Тип транзакції, Номер, Назва (Одержувач/Клієнт), Примітка/Опис, Рахунок, Дебет, Кредит (або єдиний стовпець Сума), та Залишок. Включіть будь-який клас або місцезнаходження, якщо вони використовуються.
- Запустіть звіт, а потім Експортуйте в Excel.
Це дасть детальну книгу всіх транзакцій. Збережіть її як CSV. Кожен рядок представлятиме одне проведення (запис) транзакції. Пізніше вам потрібно буде згрупувати рядки за транзакціями для конвертації.
План рахунків та інші списки: QuickBooks Online може експортувати план рахунків через Бухгалтерія → План рахунків → Пакетні дії → Експортувати в Excel. Зробіть це, щоб отримати назви та типи рахунків. Так само експортуйте Клієнтів, Постачальників тощо, якщо хочете перенести імена для метаданих.
API QuickBooks Online (Необов'язково): Для програмного підходу Intuit надає REST API для даних QBO. Досвідчені користувачі можуть створити додаток QuickBooks Online (потрібен акаунт розробника) та використовувати API для отримання даних у форматі JSON. Наприклад, ви можете запитати ендпоінт Account
для плану рахунків та ендпоінти звітів JournalEntry
або GeneralLedger
для транзакцій. Існують Python SDK, як-от python-quickbooks
, що є обгортками для API. Однак використання API включає OAuth-аутентифікацію і є над мірним для одноразової міграції, якщо ви не віддаєте перевагу автоматизації. У більшості випадків ручний експорт у CSV/Excel є простішим та менш схильним до помилок.
Етап 2: Трансформація та очищення даних
Коли ви маєте дані з QuickBooks у форматі CSV (та/або IIF), наступним кроком є їх конвертація у текстовий формат книги Beancount. Це включає аналіз експортованих файлів, зіставлення рахунків QuickBooks із планом рахунків Beancount та форматування транзакцій у синтаксисі Beancount.
2.1 Аналіз експортованих даних QuickBooks за допомогою Python
Використання Python забе зпечить точність та відтворюваність трансформації. Ми окреслимо скрипти для двох ключових завдань: імпорту плану рахунків та конвертації транзакцій.
Імпорт та зіставлення рахунків: Важливо налаштувати ваші рахунки в Beancount перед додаванням транзакцій. Рахунки QuickBooks мають типи (Банк, Дебіторська заборгованість, Витрати тощо), які ми зіставимо з ієрархією Beancount (Активи, Зобов'язання, Доходи, Витрати тощо). Наприклад, ми можемо використовувати таке зіставлення:
# Відповідність типу рахунку QuickBooks до кореневої категорії Beancount
AccountTypeMap = {
'BANK': 'Assets',
'CCARD': 'Liabilities',
'AR': 'Assets', # Дебіторська заборгованість як актив
'AP': 'Liabilities', # Кредиторська заборгованість як зобов'язання
'FIXASSET': 'Assets',
'OASSET': 'Assets', # Інший актив
'OCASSET': 'Assets', # Інший поточний актив
'LTLIAB': 'Liabilities', # Довгострокове зобов'язання
'OCLIAB': 'Liabilities', # Інше поточне зобов'язання
'EQUITY': 'Equity',
'INC': 'Income',
'EXP': 'Expenses',
'EXINC': 'Income', # Інший дохід
'EXEXP': 'Expenses', # Інша витрата
}
Використовуючи експорт IIF з QuickBooks Desktop або CSV-файл списку рахунків з QBO, ми отримуємо назву та тип кожного рахунку. Потім:
-
Створюємо назви рахунків Beancount: QuickBooks іноді використовує двокрапки (
:
) у назвах рахунків для позначення субрахунків (наприклад, “Поточні Активи:Розрахунковий”). Beancount використовує ту саму нотацію для ієрархії. Часто можна використовувати назву безпосередньо. Якщо назви рахунків QuickBooks не починаються з категорії, додайте зі ставлену категорію. Наприклад, рахунок QuickBooks типуBANK
з назвою "Розрахунковий" станеAssets:Розрахунковий
у Beancount. РахунокEXP
(витрати) "Харчування" станеExpenses:Харчування
і т.д. -
Забезпечуємо валідність назв: Видаліть або замініть будь-які символи, які можуть заплутати Beancount. QuickBooks дозволяє символи на кшталт
&
або/
у назвах. Розумно видалити або замінити спеціальні символи (наприклад, замінити&
наand
, видалити слеші або пробіли). Також переконайтеся, що всі назви рахунків унікальні після трансформації — QuickBooks міг дозволяти однакові назви субрахунків під різними батьківськими, що нормально, але в Beancount повна назва (з батьківськими) має бути унікальною. За потреби перейменуйте або додайте кваліфікатор для їх розрізнення. -
Генеруємо відкриття рахунків: У Beancount кожен використаний рахунок повинен бути відкритий за допомогою директиви
open
. Ви можете вибрати дату перед вашою першою транзакцією (наприклад, якщо мігруєте дані за 2019–2023 роки, використовуйте2018-12-31
або ще ранішу дату для всіх відкриттів). Скрипт запише рядки на кшталт:2018-12-31 open Assets:Checking USD
2018-12-31 open Expenses:Meals USD
для кожного рахунку (припускаючи, що USD є основною валютою). Використовуйте відповідну валюту для кожного рахунку (див. нотатки про мультивалютність нижче).
Конвертація транзакцій: Основна складність полягає в конвертації експортованих транзакцій QuickBooks (CSV) у записи Beancount. Кожна транзакція QuickBooks (рахунок-фактура, рахунок, чек, журнальний запис тощо) може мати кілька проведень (рядків), які необхідно зібрати в одну транзакцію Beancount.
Ми використаємо CSV-рідер Python для ітерації по експортованих рядках та накопичення проведень:
import csv
from collections import defaultdict
# Читаємо всі рядки з CSV журналу QuickBooks
rows = []
with open('quickbooks_exported_journal.csv', 'r', encoding='utf-8') as f:
reader = csv.DictReader(f)
for line in reader:
rows.append(line)
# Групуємо рядки за транзакцією (припускаючи, що '№ транзакції' ідентифікує транзакції)
transactions = defaultdict(list)
for line in rows:
trans_id = line.get('Trans #') or line.get('Transaction ID') or line.get('Num')
transactions[trans_id].append(line)
Тепер transactions
— це словник, де кожен ключ — це ID/номер транзакції, а значення — список проведень для цієї транзакції. Далі ми конвертуємо кожну групу в Beancount:
def format_date(qb_date):
# Дати в QuickBooks можуть бути у форматі "12/31/2019"
m, d, y = qb_date.split('/')
return f"{y}-{int(m):02d}-{int(d):02d}"
output_lines = []
for trans_id, splits in transactions.items():
# Сортуємо проведення за порядком, якщо потрібно (зазвичай вони йдуть по порядку)
splits = sorted(splits, key=lambda x: x.get('Line') or 0)
first = splits[0]
date = format_date(first['Date'])
payee = first.get('Name', "").strip()
memo = first.get('Memo', "").strip()
# Заголовок транзакції
output_lines.append(f"{date} * \"{payee}\" \"{memo}\"")
if first.get('Num'): # додаємо номер, якщо є
output_lines.append(f" number: \"{first['Num']}\"")
# Проходимо по кожному проведенню/запису
for split in splits:
acct_name = split['Account'].strip()
# Зіставляємо назву рахунку QuickBooks з рахунком Beancount (використовуючи попередню мапу)
beancount_acct = account_map.get(acct_name, acct_name)
# Визначаємо суму зі знаком:
amount = split.get('Amount') or ""
debit = split.get('Debit') or ""
credit = split.get('Credit') or ""
if amount:
# Деякі експорти мають один стовпець "Сума" (негативний для кредитів)
amt_str = amount
else:
# Якщо окремі стовпці "Дебет"/"Кредит"
amt_str = debit if debit else f"-{credit}"
# Видаляємо коми в числах для безпеки
amt_str = amt_str.replace(",", "")
# Додаємо валюту
currency = split.get('Currency') or "USD"
amt_str = f"{amt_str} {currency}"
# Примітка/опис для проведення
line_memo = split.get('Memo', "").strip()
comment = f" ; {line_memo}" if line_memo else ""
output_lines.append(f" {beancount_acct:<40} {amt_str}{comment}")
# Кінець транзакції – порожній рядок
output_lines.append("")
Ця логіка скрипта виконує наступне:
-
Форматує дату в YYYY-MM-DD для Beancount.
-
Використовує отримувача (Name) та примітку (Memo) для опису транзакції. Наприклад:
2020-05-01 * "ACME Corp" "Оплата рахунку"
(Якщо отримувача немає, можна використати Тип транзакції QuickBooks або залишити лапк и порожніми). -
Додає метадані
number
, якщо є номер (номер чека, рахунку-фактури тощо). -
Ітерує по кожному рядку проведення:
- Зіставляє назву рахунку QuickBooks з рахунком Beancount за допомогою словника
account_map
(заповненого на етапі роботи з планом рахунків). - Визначає суму. Залежно від вашого експорту, у вас може бути один стовпець Сума (з позитивними/негативними значеннями) або окремі стовпці Дебет та Кредит. Наведений вище код обробляє обидва випадки. Він забезпечує, що кредити представлені як негативні суми для Beancount (оскільки в Beancount для кожного проведення використовується одне число зі знаком).
- Додає валюту (припускаючи USD, якщо немає окремого стовпця з валютою).
- Записує рядок проведення Beancount з рахунком, сумою та коментарем з примітки до рядка. Наприклад:
Assets:Checking 500.00 USD ; Депозит
Income:Sales -500.00 USD ; Депозит
Це відображає депозит у $500 (з Доходів на Розрахунковий рахунок).
- Зіставляє назву рахунку QuickBooks з рахунком Beancount за допомогою словника
-
Після переліку всіх проведень, транзакцію відокремлює порожній рядок.
Обробка мультивалютності: Якщо ваші дані QuickBooks включ ають кілька валют, додайте код валюти до кожного проведення (як показано вище). Переконайтеся, що рахунки в іноземних валютах відкриті з цією валютою. Наприклад, якщо у вас є банківський рахунок в EUR, ви б вивели open Assets:Bank:Checking EUR
, і транзакції на цьому рахунку використовуватимуть EUR. Beancount підтримує мультивалютні книги й відстежуватиме неявні конвертації, але вам може знадобитися додати записи про курси, якщо ви хочете бачити конвертацію в базову валюту у звітах. Також рекомендується оголосити вашу основну операційну валюту на початку файлу Beancount (наприклад, option "operating_currency" "USD"
).
Запуск конвертації: Збережіть скрипт Python (наприклад, як qb_to_beancount.py
) і запустіть його на ваших експортованих файлах. Він повинен створити файл .beancount
, що містить усі рахунки та транзакції.