API Документация

Авторизация

Каждый пользователь получает уникальный API-ключ при регистрации. Ключ отображается в боковой панели приложения.

Передавайте ключ в заголовке X-API-Key:

curl -H "X-API-Key: bk_ваш_ключ_здесь" \
     https://bookclaw.ru/wp-json/bk/v1/transactions?month=2025-03

Или как параметр запроса (менее безопасно):

GET /wp-json/bk/v1/transactions?month=2025-03&api_key=bk_ваш_ключ_здесь

Ключ можно обновить в любой момент в боковой панели приложения. Старый ключ сразу перестанет работать.

Базовый URL

https://bookclaw.ru/wp-json/bk/v1/

Типы операций

Тип определяется на уровне подкатегории. Один блок может содержать подкатегории разных типов:

  • expense — Расход (учитывается в балансе)
  • income — Доход (учитывается в балансе)
  • transfer — Перевод (НЕ учитывается в балансе, внутренние переводы между счетами)

Баланс = Сумма доходов − Сумма расходов. Переводы видны в журнале, но не влияют на итог.

Транзакции

GET /bk/v1/transactions?month=2025-03

Получить все транзакции за указанный месяц. Формат месяца: YYYY-MM.

POST /bk/v1/transactions

Создать одну транзакцию.

Body (JSON)

{
  "date": "15.03.2025",
  "description": "Пятёрочка",
  "amount": 1523,
  "block": "Бытовые",
  "subcategory": "Еда",
  "type": "expense",
  "account_id": 1,
  "comment": ""
}

account_id — необязательное поле, ID счёта из справочника /bk/v1/accounts.

PUT /bk/v1/transactions/{id}

Обновить транзакцию. Передайте только изменяемые поля.

DELETE /bk/v1/transactions/{id}

Удалить транзакцию по ID.

CSV Импорт / Экспорт

POST /bk/v1/transactions/csv

Массовый импорт транзакций из CSV. Разделитель: |

Body (JSON)

{
  "csv": "Дата|Описание|Сумма|Блок|Подкатегория|Тип|Комментарий|Счёт\n15.03.2025|Пятёрочка|1523|Бытовые|Еда|Расход||Тинькофф •4532\n15.03.2025|Выручка|50000|Бизнес|Выручка|Доход|проект X|\n15.03.2025|Перевод на Тинькофф|10000|Переводы|Между картами|Перевод||"
}

Также можно отправить raw CSV с заголовком Content-Type: text/csv

Ответ

{
  "imported": 3,
  "errors": []
}
GET /bk/v1/transactions/csv?month=2025-03

Экспорт транзакций за месяц в формате CSV (text/csv).

Категории

GET /bk/v1/categories

Получить все категории (блоки + подкатегории с типами).

POST /bk/v1/categories

Создать новую категорию.

{
  "block": "Бытовые",
  "subcategory": "Подписки",
  "description": "Netflix, Spotify",
  "type": "expense"
}
DELETE /bk/v1/categories/{id}

Удалить категорию по ID.

Счета (Accounts)

GET /bk/v1/accounts

Получить все счета/карты.

POST /bk/v1/accounts

Создать новый счёт.

{
  "name": "Тинькофф •4532",
  "description": "Дебетовая карта"
}
PUT /bk/v1/accounts/{id}

Обновить счёт. Передайте только изменяемые поля.

DELETE /bk/v1/accounts/{id}

Удалить счёт. Привязка к транзакциям будет снята.

Сводка

GET /bk/v1/summary?month=2025-03

P&L по каждому блоку: доходы, расходы, переводы, баланс. Переводы не влияют на баланс.

Справочник блоков и подкатегорий

Каждый блок — это направление (бизнес, быт и т.д.). Тип (Расход/Доход/Перевод) определяется на уровне подкатегории. Получить актуальный список:

GET /wp-json/bk/v1/categories

[Д] = доход, [П] = перевод, остальные = расход

Промпт для ИИ-агента

Используйте этот промпт при обработке банковских выписок:

Ты помощник по ведению бухгалтерии. Я дам тебе выписку со счёта,
а ты должен вернуть данные в формате CSV для импорта.

ФОРМАТ (разделитель |):
Дата|Описание из выписки|Сумма|Блок|Подкатегория|Тип|Комментарий|Счёт

ПРАВИЛА:
1. Дата — формат ДД.ММ.ГГГГ
2. Описание — точно как в выписке
3. Сумма — только число, без знаков и пробелов
4. Тип — "Расход", "Доход" или "Перевод"
5. Блок и Подкатегория — строго из справочника
6. В одном блоке могут быть и расходные, и доходные подкатегории
7. Переводы между своими счетами — тип "Перевод"
   (они не учитываются в балансе)
8. Счёт — название карты/счёта, если известно (например "Тинькофф •4532")
   Если выписка с конкретной карты, ставь название этой карты

Если не уверен — ставь Подкатегория = "Разное"
и добавь пометку в Комментарий.