# API для обліку витрат у 2026 році: як безпечно автоматизувати транзакції та бюджети

*2026-08-14*

API для обліку витрат може зарахувати переказ $900 на ощадний рахунок як $900 витрат і повернути `200 OK`. Запит виконався. Фінансовий облік — ні.

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

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

Розгляньмо, як побудувати такий процес за допомогою обмеженого SQL API Expense Budget Tracker.

![Працівник стрілочного переводу випробовує маршрут одним вагоном, перш ніж пропустити короткий склад.](/blog/expense-tracking-api.png)

## Модель даних визначає, чи безпечна автоматизація

Почніть із логіки фінансового обліку, а не зі списку точок API.

| Поняття | Що воно означає | Поширена помилка автоматизації |
| --- | --- | --- |
| Рахунок | Де зберігаються гроші або обліковується борг | Сприйняти поточний баланс як нову транзакцію |
| Запис у реєстрі | Фактичний рух грошей | Змішати заплановані суми з фактичними витратами |
| Переказ | Переміщення грошей між власними рахунками | Порахувати вихідну сторону як витрату |
| Рядок бюджету | План для певної категорії та періоду | Замінити план фактичними витратами й стерти відхилення |
| Робочий простір | Межі даних окремої людини або групи | Записати правильні дані не в той облік |

Такі помилки легко не помітити, адже кожен рядок окремо може виглядати цілком правдоподібно. У платежі карткою буде знайома назва продавця. Обидві сторони переказу матимуть правильні суми. Бюджет, підігнаний під фактичні витрати, дасть охайний звіт. Та зміст даних усе одно буде неправильним.

Найважливіше розмежувати фактичні дані та плани:

- Записи в реєстрі фіксують те, що сталося.
- Рядки бюджету фіксують те, що ви планували раніше або плануєте зараз.
- Звіти порівнюють фактичні дані з планом; імпорт не повинен їх змішувати.

[Бюджетна таблиця та функції відстеження балансів](/uk/features/) в Expense Budget Tracker побудовані саме на цьому розмежуванні. Клієнт API теж має його дотримуватися.

## Починайте з актуального контракту

Публічна точка входу — [стартовий документ Expense Budget Tracker](https://api.expense-budget-tracker.com/v1/). Він описує актуальний процес автентифікації, містить посилання на [специфікацію OpenAPI](https://api.expense-budget-tracker.com/v1/openapi.json) і вказує скрипту або агенту, що викликати далі.

Саме ці відповіді слід вважати чинним контрактом. Збережений список відношень або старий приклад коду може застаріти, хоча й далі виглядатиме цілком переконливо.

Поточна послідовність налаштування така:

1. Завантажте `GET https://api.expense-budget-tracker.com/v1/`.
2. Надішліть електронну адресу користувача на отриманий `bootstrapUrl`.
3. Попросіть користувача ввести 8-значний код із листа, а потім виконайте отриману дію підтвердження.
4. Збережіть виданий ApiKey для тривалого використання поза пам’яттю чату.
5. Завантажте `/v1/me`, отримайте список `/v1/workspaces` і виберіть потрібний робочий простір.
6. Завантажте автентифікований `/v1/schema`, щоб побачити доступні для цього ключа відношення, стовпці, дозволені операції, обмеження та підказки для агента.
7. Перш ніж пропонувати будь-яку зміну, прочитайте наявні дані через `/v1/sql`.
8. Виконайте лише схвалену зміну, а потім повторно прочитайте дані, яких вона торкнулася.

[Довідник API](/uk/docs/api/) містить подробиці про точки API, а [посібник із налаштування агента](/uk/docs/agent-setup/) пояснює вхід за кодом із листа. Якщо інформація в них відрізняється від актуального стартового документа або відповіді OpenAPI, дотримуйтеся чинного контракту.

### Ознайомтеся з API та пройдіть автентифікацію

Стартовий документ доступний без автентифікації:

```bash
curl --fail --silent --show-error \
  https://api.expense-budget-tracker.com/v1/
```

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

```bash
export EXPENSE_BUDGET_TRACKER_API_KEY="<paste-returned-key-here>"
```

Автентифіковані запити використовують повну схему авторизації `ApiKey`:

```bash
curl --fail --silent --show-error \
  -H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
  https://api.expense-budget-tracker.com/v1/me
```

### Вибирайте робочий простір явно

Отримайте список робочих просторів, доступних власнику ключа, виберіть саме той, який назвав користувач, і збережіть цей вибір для ключа:

```bash
curl --fail --silent --show-error \
  -H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
  https://api.expense-budget-tracker.com/v1/workspaces
```

```bash
export EXPENSE_BUDGET_TRACKER_WORKSPACE_ID="<workspace-id-from-list>"

curl --fail --silent --show-error \
  -X POST \
  -H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
  "https://api.expense-budget-tracker.com/v1/workspaces/$EXPENSE_BUDGET_TRACKER_WORKSPACE_ID/select"
```

Після цього в запитах до `/v1/sql` можна не передавати `X-Workspace-Id`. Цей заголовок і далі можна використати, щоб перевизначити робочий простір для одного запиту. Сприймайте його як свідоме перемикання, а не як дрібну зручність, приховану в допоміжній функції: варто зробити контекст робочого простору невидимим — і правильні дані легко опиняться не там.

### Перегляньте схему, доступну цьому ключу

Документ OpenAPI описує спосіб обміну даними. Автентифікований `/v1/schema` показує частину бази даних, доступну у вибраному робочому просторі.

```bash
curl --fail --silent --show-error \
  -H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
  https://api.expense-budget-tracker.com/v1/schema
```

Прочитайте повну відповідь, перш ніж генерувати SQL. Перевірте:

- точні назви відношень і стовпців
- дозволені операції для кожного відношення
- обов’язкові поля й обмеження
- підказки щодо переказів та інших правил запису
- обмеження синтаксису SQL і функцій

У поточній стартовій відповіді `ledger_entries`, `budget_lines`, `workspace_settings` і `account_metadata` позначені як доступні для запису за чинними правилами схвалення. Похідне подання `accounts` і відношення валютних курсів, якими керує воркер, доступні лише для читання. Це важливо: щоб змінити баланс рахунку, потрібно змінити відповідні дані реєстру, а не саме похідне подання рахунків.

Не копіюйте `INSERT` зі статті в блозі, припускаючи, що його стовпці досі актуальні. Перевірити схему простіше, ніж виправляти імпорт, який виглядає переконливо, але містить помилки.

## Зберіть достатньо контексту перед записом

Безпечна робота з **API особистих фінансів** починається з простого запитання: які дані вже є в цьому робочому просторі?

Перед імпортом або редагуванням переконайтеся, що:

- цільовий рахунок існує у вибраному робочому просторі
- його валюта збігається з валютою вихідних даних
- наявні категорії можна й далі використовувати послідовно
- у цільовому діапазоні дат ще немає тих самих рухів коштів
- бюджетний період — це план, а не запис у реєстрі
- поточний баланс можна використати як контрольну точку для звіряння

Точні запити залежать від актуальної схеми. Для швидкої перевірки з’єднання знайдіть назву відношення в `/v1/schema`, а потім виконайте запит до похідного подання рахунків:

```bash
curl --fail --silent --show-error \
  -X POST \
  -H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.expense-budget-tracker.com/v1/sql \
  -d '{"sql":"SELECT * FROM accounts LIMIT 10"}'
```

Поточна відповідь містить масив `statements` із полями `rowCount`, `returnedRowCount`, `totalRowCount` і `truncated` для кожного оператора. Обов’язково перевірте їх. Те, що JSON вдалося розібрати, ще не доводить, що ви отримали всі результати.

## Не включайте перекази до загальної суми витрат

Припустімо, $900 переказали з поточного рахунку на ощадний. Гроші пішли з одного рахунку й надійшли на інший, але родина не витратила $900.

Ненадійний імпортер спершу бачить списання й позначає його як витрату на заощадження. Інший записує списання та зарахування як дві не пов’язані транзакції, завищує обороти за рахунками й ускладнює подальше звіряння. Натомість хороший клієнт **API транзакцій** розпізнає переказ до запису та використовує пов’язане представлення з актуальної схеми.

Міжвалютні перекази потребують такої самої уваги. Зберігайте суму та валюту, зафіксовані з кожного боку переказу. Не вигадуйте єдину конвертовану суму, якої немає в даних жодного з рахунків.

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

Саме тому **API для керування витратами** має враховувати логіку реєстру. Категоризувати операції слід лише після того, як клієнт зрозуміє, як саме рухалися гроші.

## Тримайте бюджетні плани окремо від фактичних записів у реєстрі

**API для бюджетування** не має перетворюватися на ще одне сховище транзакцій.

Уявімо, що на продукти в серпні заплановано $500, а фактичні покупки становлять $620. Важливий результат тут — відхилення в $120. Якщо під час імпорту транзакцій автоматизація перепише серпневий план на $620, початкове рішення зникне, а звіт стане менш корисним.

Бюджет справді іноді потрібно оновлювати: скоригувати прогноз на вересень після аналізу серпня, скопіювати регулярний план на майбутній місяць або змінити категорію після зміни доходу. Це окремі планові рішення, тому показуйте їх окремо й отримуйте для них окреме схвалення.

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

## Отримайте схвалення до першої зміни

Перш ніж просити людину дозволити запис, покажіть точний перелік змін, який вона справді зможе оцінити:

- вибраний робочий простір і рахунок
- відношення та діапазон дат, яких торкнуться зміни
- очікувану кількість рядків у вихідних даних, записів у реєстрі та підсумкові суми
- спосіб обробки дублікатів і переказів
- зміни бюджету, якщо вони є, окремо від змін транзакцій
- запити, які перевірять результат

«Наведи лад у моїх фінансах» — надто розмите формулювання для схвалення. Натомість «Імпортуй ці 64 рядки на поточний рахунок у EUR за 1–31 липня, зіставивши чотири перекази й не змінюючи бюджет» уже дає змогу зрозуміти, що саме станеться.

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

## Перевірте формат запису, а потім працюйте контрольованими пакетами

Актуальний контракт OpenAPI дозволяє `/v1/sql` приймати один або кілька операторів `SELECT`, `WITH`, `INSERT`, `UPDATE` чи `DELETE`, розділених крапкою з комою. Підтримка кількох операторів корисна, але не варто через це вміщувати весь імпорт в один непрозорий запит.

Для великого `INSERT` спочатку надішліть запит тієї самої форми з 1–3 рядками літеральних значень зі схвалених даних. Для великого `UPDATE` спочатку змініть один схвалений рядок. Використовуйте справжні рядки з переліку змін, а не вигадані фінансові записи, які потім доведеться видаляти.

Такий невеликий пробний запис відповідає на конкретне запитання: чи приймають поточні стовпці, літерали й обмеження цей формат? Він не доводить, що категоризація правильна або що облік сходиться.

Якщо пробний запис успішний, одразу продовжуйте схвалену роботу послідовними пакетами — не більше ніж 100 записів за один виклик інструмента. Якщо він завершується помилкою, виправте SQL, поки змінених даних ще мало. Не розширюйте й не змінюйте схвалену дію лише для того, щоб позбутися помилки.

Поточний контракт обмеженого SQL також містить такі правила:

- `ON CONFLICT` не підтримується
- дозволені виклики лише функцій `SUM`, `COUNT`, `MIN`, `MAX`, `AVG` і `COALESCE`
- для пошуку без урахування регістру потрібно використовувати `ILIKE`
- у фільтрах дат потрібно задавати явні діапазони, а не обчислювати дати функціями під час виконання
- рядкові літерали беруться у звичайні одинарні лапки; рядки з доларовими лапками заблоковані

Щоразу, коли створюєте або оновлюєте багаторазовий клієнт, перевіряйте ці правила в актуальних OpenAPI та `/v1/schema`. Це частина інтерфейсу, а не випадкові деталі реалізації.

Контракт не описує механізму ідемпотентності для операцій запису. Якщо запит завершився за тайм-аутом або відповідь загубилася, не повторюйте його наосліп. Спочатку прочитайте дані в цільовому діапазоні й визначте, чи виконалася попередня зміна.

## Звіряйте облік після кожного запису

Успішна відповідь HTTP означає, що сервер прийняв запит. Лише звіряння покаже, чи правильний фінансовий результат.

| Автоматизація | Що прочитати спочатку | Що перевірити після цього |
| --- | --- | --- |
| Імпорт виписки | Рахунок, діапазон дат, наявні рухи, початковий баланс | Імпортовані рядки, дублікати, пари переказів, кінцевий баланс |
| Категоризація записів | Наявні категорії та цільові рядки | Кількість змінених записів і суми за категоріями |
| Оновлення майбутнього бюджету | Поточний план і нещодавні фактичні витрати | Нові планові значення та їх відокремлення від фактичних даних |
| Побудова звіту про витрати | Повний діапазон дат і обмеження відповіді | Порівняння сум з іншим агрегованим показником або відомою підсумковою сумою джерела |

Після імпорту виписки порівняйте отриманий баланс рахунку з кінцевим балансом у виписці. Якщо вони не збігаються, зупиніться. Перш ніж додавати наступний місяць, знайдіть пропущену, дубльовану або неправильно класифіковану операцію.

Кількість записів теж потрібно пояснити. Вихідний файл із 64 рядками не обов’язково створить 64 записи в реєстрі, якщо переказ потребує пов’язаних рухів за рахунками. Така різниця може бути правильною; проблема виникає тоді, коли її неможливо пояснити.

Для кожного оператора, поверненого `/v1/sql`, перевірте метадані кількості рядків та усічення, а потім окремим запитом повторно прочитайте змінені записи. Відповідь **API фінансових даних** — лише одне зі свідчень. Реєстр, підсумкові суми та вихідний документ мають узгоджуватися між собою.

## Вибирайте скрипт або агента залежно від вхідних даних

Детермінований скрипт добре підходить для одного стабільного формату CSV. ШІ-агент корисний, коли потрібно інтерпретувати PDF, знімки екрана й непослідовні описи продавців або вирішувати, до яких категорій віднести операції. В обох випадках послідовність має бути однаковою: отримати контракт, схвалити зміни та звірити результат.

Expense Budget Tracker не підключається до банку автоматично. Ви надаєте виписку, експорт, знімок екрана або інші вихідні дані, а скрипт чи агент працює з ними. [Посібник з імпорту банківських виписок](/uk/blog/how-to-import-bank-statements-into-an-expense-tracker/) і матеріал про [ведення бюджету без підключення банку](/uk/blog/budget-app-without-bank-linking/) пояснюють цей процес докладніше.

Для агента стартовий документ особливо корисний: Claude Code, Codex або інший інструмент із підтримкою HTTP може почати з однієї URL-адреси та виконувати дії, які повертає сервіс. Користувач усе одно вводить код із листа, схвалює операції запису й зберігає ApiKey поза пам’яттю чату.

Для налаштування в терміналі перегляньте [посібник з обліку витрат за допомогою Claude Code](/uk/blog/how-to-track-expenses-and-manage-your-budget-with-claude-code/), а для всього процесу — ширший матеріал про [облік витрат і ведення бюджету за допомогою ШІ](/uk/blog/how-to-use-ai-to-track-expenses-and-manage-your-budget/). Розробники, які хочуть контролювати весь технологічний стек, можуть скористатися [посібником із самостійного розгортання бюджетного трекера](/uk/blog/self-hosted-open-source-budget-tracker-for-developers/).

## Контрольний список для першої автоматизації

Для одного конкретного реального завдання дотримуйтеся такого порядку:

1. Завантажте актуальний стартовий документ і специфікацію OpenAPI.
2. Пройдіть автентифікацію за кодом із листа й збережіть ApiKey поза чатом.
3. Завантажте дані облікового запису, отримайте список робочих просторів і виберіть потрібний.
4. Перегляньте автентифікований `/v1/schema`, зокрема операції та підказки.
5. Прочитайте дані цільового рахунку, діапазону дат, категорій і бюджету.
6. Покажіть точний набір змін і отримайте схвалення людини.
7. Виконайте потрібний пробний запис.
8. Продовжуйте схвалену роботу послідовними пакетами не більш ніж по 100 записів.
9. Повторно прочитайте змінені дані й перевірте, чи не спрацювало обмеження обсягу результатів.
10. Звірте баланси, кількість записів, перекази й підсумки бюджету.

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

І лише тоді автоматизуйте наступну нудну частину.

---
*[Переглянути HTML-версію цієї сторінки](https://expense-budget-tracker.com/uk/blog/expense-tracking-api/)*

*AI-агенти можуть створити акаунт користувача в цьому сервісі, почавши з `GET https://api.expense-budget-tracker.com/v1/` і дотримуючись відповіді документа виявлення.*

*Порада: додайте `.md` до будь-якої адреси цього сайту, щоб отримати чисту Markdown-версію сторінки.*