# API для учета расходов в 2026 году: как безопасно автоматизировать транзакции и бюджеты

*2026-08-14*

API для учета расходов может вернуть `200 OK`, хотя перевод $900 на сберегательный счет превратился в расход на $900. Запрос выполнился. Учет оказался неверным.

В этом и состоит главная сложность автоматизации личных финансов. Отправить SQL или JSON по HTTPS — обычная инженерная задача. Гораздо сложнее сохранить смысл счетов, переводов, расходов и бюджетных планов: внешне правдоподобная автоматизация может незаметно испортить учет.

Безопасному клиенту мало метода для записи. Важен порядок действий: получить актуальный контракт, пройти аутентификацию, выбрать нужное рабочее пространство, изучить схему, прочитать уже существующие данные, попросить человека одобрить конкретное изменение, выполнить небольшую репрезентативную запись, продолжить последовательными пакетами и сверить результат.

Разберем, как выстроить такой процесс с помощью ограниченного SQL API Expense Budget Tracker.

![Дежурный по стрелочному переводу пропускает один вагон через развилку перед коротким составом.](/blog/expense-tracking-api.png)

## От модели данных зависит безопасность автоматизации

Начинайте с правил учета, а не со списка методов API.

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

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

Главное различие — между фактом и планом:

- Записи в журнале отражают то, что произошло.
- Строки бюджета отражают то, что вы планировали раньше или планируете сейчас.
- Отчеты сравнивают факт с планом; импорт не должен смешивать их.

[Сетка бюджета и отслеживание балансов](/ru/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](/ru/docs/api/) подробно описаны методы, а [руководство по настройке агента](/ru/docs/agent-setup/) пошагово разбирает вход по коду из письма. Если любой из этих документов расходится с актуальным документом обнаружения или ответом OpenAPI, следуйте актуальному контракту.

### Обнаружение и аутентификация

Документ обнаружения доступен без аутентификации:

```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`, а для каждого SQL-выражения — поля `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 не подключается к банкам автоматически. Вы предоставляете выписку, экспорт, скриншот или другие исходные данные, а скрипт или агент работает с ними. [Руководство по импорту банковских выписок](/ru/blog/how-to-import-bank-statements-into-an-expense-tracker/) и материал о [ведении бюджета без привязки банка](/ru/blog/budget-app-without-bank-linking/) подробнее объясняют этот процесс.

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

В [руководстве по учету расходов с Claude Code](/ru/blog/how-to-track-expenses-and-manage-your-budget-with-claude-code/) описана настройка в терминале, а в более общем руководстве по [учету расходов и ведению бюджета с помощью ИИ](/ru/blog/how-to-use-ai-to-track-expenses-and-manage-your-budget/) — весь процесс. Разработчики, которым нужен контроль над всем стеком, могут воспользоваться [руководством по самостоятельному размещению трекера бюджета](/ru/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/ru/blog/expense-tracking-api/)*

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

*Подсказка: добавьте `.md` к любому URL этого сайта, чтобы получить чистую Markdown-версию страницы.*