API: Счета

Ресурс accounts позволяет управлять счетами проекта через External API: получать список, один счёт по id, создавать, обновлять и удалять счета.

Scope

• accounts:read — список счетов и получение одного счёта
• accounts:write — создание, обновление, удаление

Базовый путь и заголовки

Все методы: POST {{base_url}}/v1/accounts/<action>.

Обязательные заголовки:

• Content-Type: application/json
• X-Api-Key: <ваш_api_ключ>

Для create/update/delete можно передать Idempotency-Key: <uuid> — при повторном запросе с тем же ключом в течение 24 ч вернётся закэшированный ответ.

1. Список счетов

POST /v1/accounts/list. Требуется scope accounts:read. projectId берётся из API ключа, в теле можно передать только includeArchived.

Запрос

{
  "meta": { "requestId": "опционально" },
  "data": {
    "includeArchived": false
  }
}

Ответ (успех, 200)

{
  "success": true,
  "data": {
    "projectId": "uuid-проекта",
    "accounts": [
      {
        "id": "uuid-счёта",
        "projectId": "uuid-проекта",
        "ownerId": "uuid-владельца",
        "accountKind": "cash",
        "financialRole": "asset",
        "displayName": "Наличные",
        "status": "active",
        "createdAt": "2026-03-07T12:00:00.000Z",
        "updatedAt": "2026-03-07T12:00:00.000Z",
        "currency": {
          "id": "uuid-валюты",
          "code": "RUB",
          "symbol": "₽",
          "decimalPlaces": 2
        }
      }
    ],
    "totalCount": 1
  },
  "meta": {
    "requestId": "...",
    "serverTime": "2026-03-07T12:00:00.000Z",
    "executionTimeMs": 15,
    "project": { "id": "...", "timezone": "Europe/Moscow", "locale": "ru-RU", "currency": "RUB" },
    "rateLimit": { "minute": { "limit": 120, "remaining": 119, "resetAt": "..." }, "hour": { ... }, "day": { ... }, "month": { ... } }
  }
}

Пример cURL

curl -X POST "https://api-external.budgeter.online/v1/accounts/list" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{"data":{"includeArchived":false}}'

Ошибки: 401 (неверный/отозванный ключ), 403 (недостаточно scope или временный бан), 429 (превышен лимит).

2. Получить счёт

POST /v1/accounts/get. Требуется accounts:read. Возвращает один счёт по accountId.

Запрос

{
  "data": {
    "accountId": "uuid-счёта"
  }
}

Ответ (успех, 200)

{
  "success": true,
  "data": {
    "id": "uuid-счёта",
    "projectId": "uuid-проекта",
    "ownerId": "uuid-владельца",
    "accountKind": "bank_account",
    "financialRole": "asset",
    "assetClass": "fiat",
    "displayName": "Основной счёт",
    "defaultCurrencyId": "uuid-валюты",
    "status": "active",
    "createdAt": "2026-03-07T12:00:00.000Z",
    "updatedAt": "2026-03-07T12:00:00.000Z",
    "currency": { "id": "...", "code": "RUB", "symbol": "₽", "decimalPlaces": 2 },
    "settings": {},
    "visibility": {},
    "uiPrefs": {}
  },
  "meta": { "requestId": "...", "serverTime": "...", "executionTimeMs": 8, "project": { ... }, "rateLimit": { ... } }
}

Ошибки: 400 (нет accountId), 404 (счёт не найден или нет доступа), 401/403/429.

3. Создать счёт

POST /v1/accounts/create. Требуется accounts:write. Обязательные поля: accountKind, displayName, defaultCurrencyId.

Запрос

{
  "data": {
    "accountKind": "cash",
    "displayName": "Наличные",
    "defaultCurrencyId": "uuid-валюты"
  }
}

Опционально: financialRole, assetClass, currencyMode, ownershipScope, color, icon, emoji, status, settings, visibility, uiPrefs.

Ответ (успех, 200)

{
  "success": true,
  "data": {
    "id": "uuid-нового-счёта",
    "projectId": "uuid-проекта",
    "ownerId": "uuid-владельца",
    "accountKind": "cash",
    "financialRole": "asset",
    "displayName": "Наличные",
    "defaultCurrencyId": "uuid-валюты",
    "status": "active",
    "createdAt": "2026-03-07T12:00:00.000Z",
    "updatedAt": "2026-03-07T12:00:00.000Z",
    "currency": { "id": "...", "code": "RUB", "symbol": "₽", "decimalPlaces": 2 },
    "settings": {},
    "visibility": {},
    "uiPrefs": {}
  },
  "meta": { "requestId": "...", "serverTime": "...", "executionTimeMs": 45, "project": { ... }, "rateLimit": { ... } }
}

Пример cURL

curl -X POST "https://api-external.budgeter.online/v1/accounts/create" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"data":{"accountKind":"cash","displayName":"Наличные","defaultCurrencyId":"UUID_Валюты"}}'

Ошибки: 400 (валидация), 403 (scope), 401/429.

4. Обновить счёт

POST /v1/accounts/update. Требуется accounts:write. Обязателен только accountId, остальные поля опциональны.

Запрос

{
  "data": {
    "accountId": "uuid-счёта",
    "displayName": "Новое название",
    "status": "archived"
  }
}

Ответ (успех, 200)

{
  "success": true,
  "data": {
    "id": "uuid-счёта",
    "projectId": "uuid-проекта",
    "ownerId": "uuid-владельца",
    "accountKind": "cash",
    "displayName": "Новое название",
    "status": "archived",
    "updatedAt": "2026-03-07T12:05:00.000Z",
    "currency": { ... },
    "settings": {},
    "visibility": {},
    "uiPrefs": {}
  },
  "meta": { "requestId": "...", "serverTime": "...", "executionTimeMs": 22, "project": { ... }, "rateLimit": { ... } }
}

Ошибки: 400 (нет accountId), 404 (счёт не найден), 403/401/429.

5. Удалить счёт

POST /v1/accounts/delete. Требуется accounts:write. По умолчанию мягкое удаление (hardDelete: false). hardDelete: true — только для владельца проекта.

Запрос

{
  "data": {
    "accountId": "uuid-счёта",
    "hardDelete": false
  }
}

Ответ (успех, 200)

{
  "success": true,
  "data": {
    "accountId": "uuid-счёта",
    "deleted": true,
    "deletionType": "soft"
  },
  "meta": { "requestId": "...", "serverTime": "...", "executionTimeMs": 18, "project": { ... }, "rateLimit": { ... } }
}

Ошибки: 400, 404, 403, 401/429.

Лимиты

Действуют общие лимиты API (120/мин, 3000/час и т.д.). Дополнительно: не более 60 изменяющих запросов в минуту (create, update, delete) на один ключ.

См. также

Внешний API: основы — базовый URL, получение ключа, коды ошибок, лимиты.