Довідник API v1

Огляд

Manilo API — це JSON REST API для програмного керування тим самим обліком, який ви бачите в застосунку для iOS: рахунками, категоріями, бюджетами, спільними групами та транзакціями. Використовуйте його, щоб створювати імпортери, експортери, мости синхронізації, дашборди чи власні автоматизації.

• Базовий URL: https://api.manilo.app — попередній базовий URL api.ledgy.app продовжує працювати.
• Префікс версії: усі ендпоїнти в цьому документі розміщено під /api/v1/.
• Транспорт: лише HTTPS. HTTP-запити не приймаються.
• Кодування: тіла запитів і відповідей у JSON. UTF-8. Назви властивостей у camelCase.
• Автентифікація: Authorization: Bearer … у кожному запиті.
• Підписка Cloud: потрібна для кожного ендпоїнта v1. Див. Обмеження за підпискою.

Швидкий старт

Три кроки до вашого першого автентифікованого запиту.

1. Створіть Personal Access Token

1. Увійдіть у дашборд Manilo і відкрийте Налаштування → API Access.
2. Натисніть + Новий токен.
3. Дайте токену описову назву (наприклад, «Zapier — щотижневий експорт»), оберіть потрібні скоупи (див. Скоупи) і за бажанням задайте термін дії.
4. Скопіюйте токен. Він показується лише один раз. Токени починаються з префікса lgpat_, за яким ідуть 64 шістнадцяткові символи.

На тій самій сторінці перелічено ваші активні токени з часом останнього використання та кількістю дозволів, показано попередження «Закінчується через 30 днів» і можна миттєво відкликати будь-який токен через іконку кошика. Один акаунт може одночасно мати до 25 активних токенів.

2. Виконайте запит

# Replace lgpat_… with your token
curl "https://api.manilo.app/api/v1/accounts" \
  -H "Authorization: Bearer lgpat_a1b2c3d4e5…"

3. Перевірте відповідь

{
  "items": [
    {
      "id": "acc_01HK8V…",
      "name": "Wise EUR",
      "currencyCode": "EUR",
      "initialBalance": 1240.50,
      "icon": "wallet",
      "color": "#4A90E2",
      "order": 0,
      "createdAt": "2026-04-12T08:13:09Z",
      "updatedAt": "2026-05-01T17:02:31Z"
    }
  ],
  "totalCount": 1
}

Автентифікація

Кожен запит до /api/v1/ має містити заголовок Authorization. Приймаються два типи токенів:

• Personal Access Token (PAT) — довгоживучий bearer-токен, який ви створюєте в дашборді на сторінці Налаштування → API Access. Формат: lgpat_ + 64 шістнадцяткові символи. Обмежений скоупами, відкликається, за бажанням із терміном дії. Рекомендовано для всіх сторонніх інтеграцій.
• Session JWT — короткоживучий токен, що видається власним застосункам (iOS, дашборд). Не має обмежень за скоупами. Його можна використати для разового тестування, якщо вдасться дістати його із сеансу зі входом, але підтримуваний шлях — це PAT.

Формат заголовка

Authorization: Bearer lgpat_a1b2c3d4e5f6…

Обмеження токенів

• До 25 активних PAT на один акаунт Manilo.
• Під час створення можна задати необов’язковий термін дії. Прострочені токени повертають 401 Unauthorized.
• Відкликані токени перестають працювати негайно — Manilo зберігає лише SHA-256-хеш токена, а не саме значення, тож токен, що витік, неможливо відновити: його можна лише відкликати й замінити.

Типові помилки автентифікації

401

Токен відсутній, має неправильний формат, прострочений або відкликаний.

403

Токен дійсний, але запитаний ендпоїнт потребує скоупа, якого немає у вашого PAT, або ваша підписка Cloud неактивна.

Скоупи

PAT працюють за моделлю deny-by-default. Токен може викликати лише ті ендпоїнти, потрібний скоуп яких він має; усе інше повертає 403 Forbidden. Надавайте найвужчий набір скоупів, який справді потрібен вашій інтеграції.

Доступні скоупи:

Кожен наведений нижче ендпоїнт показує потрібний скоуп як невеликий фіолетовий чип. Скоупи :write не передбачають :read — запитуйте обидва, якщо потрібні обидва.

Обмеження за підпискою

Усі ендпоїнти v1 — зокрема й ті, що лише читають дані, — вимагають, щоб користувач, який виконує запит, мав активну підписку Manilo Cloud. Якщо підписку скасовано, її термін минув або її ніколи не було оформлено, API відповідає:

HTTP/1.1 403 Forbidden
X-Subscription-Required: true
Content-Type: application/json

{ "error": "Active cloud subscription required" }

Заголовок X-Subscription-Required дозволяє клієнтам відрізнити блокування через підписку від звичайної відмови в доступі. Щоб відновити доступ, повторно активуйте Cloud у застосунку для iOS або на dashboard.manilo.app/upgrade.

Помилки

Помилки використовують стандартні коди стану HTTP. Тіло відповіді — це JSON-об’єкт з одним полем:

{ "error": "Human-readable message" }

Коди стану, які варто обробляти:

200

OK — повернуто ресурс або список.

201

Created — створено новий ресурс. Заголовок Location вказує на канонічний URL.

204

No Content — успішне видалення; тіла немає.

400

Валідація не пройдена — відсутнє обов’язкове поле, значення поза діапазоном, некоректний JSON.

401

Автентифікація не вдалася — див. Автентифікація.

403

Доступ заборонено — недостатній скоуп або неактивна підписка.

404

Ресурс не знайдено або він прихований авторизацією.

409

Conflict — наприклад, порушення обмеження унікальності.

5xx

Збій на стороні сервера. Ідемпотентні читання безпечно повторювати з експоненційною затримкою.

Пагінація та фільтри

Ендпоїнти списків за замовчуванням повертають усі відповідні елементи. Транзакції — єдиний ресурс, який може сильно зрости, — підтримують курсорну пагінацію.

Курсор транзакцій

curl "https://api.manilo.app/api/v1/transactions?limit=50&type=expense&dateFrom=2026-01-01" \
  -H "Authorization: Bearer lgpat_…"

Відповідь містить nextCursor. Передайте його назад як query-параметр cursor, щоб отримати наступну сторінку; коли nextCursor дорівнює null, ви досягли кінця.

• limit — розмір сторінки, обмежений діапазоном 1..200. За замовчуванням 50.
• cursor — непрозорий токен. Ставтеся до нього як до чорної скриньки.
• type, dateFrom, dateTo, categoryId, accountId, groupId — необов’язкові фільтри; див. ендпоїнт Список транзакцій.

Типи та формати

• Ідентифікатори — непрозорі рядки. Не розбирайте їх; вважайте їх чутливими до регістру ідентифікаторами в UTF-8.
• Часові позначки — ISO-8601 в UTC із завершальним Z, наприклад "2026-05-13T10:30:00Z".
• Дати (наприклад, date транзакції) — той самий формат ISO-8601, але значущою є лише частина з датою.
• Грошові суми — числа JSON в основних одиницях з точністю до 4 знаків після коми (наприклад, 12.50). Ніколи не в мінорних одиницях. Завжди в парі з currencyCode.
• Коди валют — ISO-4217, рівно три великі літери (наприклад, "EUR", "USD", "GBP").
• Видалення — усі операції видалення є м’якими видаленнями. Видалені елементи перестають з’являтися у відповідях списку та отримання; партнери зі спільного доступу й історичні чеки зберігаються.
• Побічні ефекти — видалення рахунку, категорії чи групи залишає залежні транзакції недоторканими; їхні посилання від’єднуються. Ендпоїнт Видалити рахунок приймає явну стратегію.

Рахунки

Рахунки — це контейнери, що зберігають баланси: банківський рахунок, кредитна картка, готівковий гаманець, брокерський рахунок. Кожна транзакція прив’язана до одного рахунку (або до двох — для переказів).

POST /api/v1/accounts
{
  "name": "Cash",
  "currencyCode": "EUR",
  "initialBalance": 50.00,
  "order": 2,
  "icon": "wallet",
  "color": "#22C55E"
}

{
  "id": "acc_01HK8V…",
  "name": "Cash",
  "currencyCode": "EUR",
  "initialBalance": 50.00,
  "order": 2,
  "icon": "wallet",
  "color": "#22C55E",
  "iconColor": null,
  "shareInviteToken": null,
  "createdAt": "2026-05-13T10:30:00Z",
  "updatedAt": "2026-05-13T10:30:00Z"
}

Категорії

Категорії позначають, на що спрямована транзакція (продукти, оренда, дохід від фрилансу). Системні категорії доступні лише для читання і є спільними для всіх користувачів; користувацькими категоріями керуєте ви. Групи категорій об’єднують споріднені категорії.

Користувацькі категорії

Групи категорій

Бюджети

Бюджет обмежує витрати за категорією (або, коли categoryId дорівнює null, за всім обліком) у межах повторюваного вікна. Щоб поділитися бюджетом із групою, задайте groupId.

Групи

Групи — це спільні обліки: домогосподарство, подорож, спільна квартира. Кожен учасник бачить ті самі транзакції; власність залишається особистою. Членством і запрошеннями керують у застосунку для iOS; тут API надає лише сам ресурс.

Транзакції

Транзакції — це дієслова обліку. Вони бувають чотирьох видів: income, expense, transfer (з рахунку на рахунок) і adjustment (разове вирівнювання балансу). Базовий ендпоїнт створює income/expense; для переказів є власний ендпоїнт; для імпортерів великих обсягів існують пакетні варіанти.

{
  "items": [ /* TransactionDto[] */ ],
  "totalCount": 317,
  "nextCursor": "eyJrIjoiMjAyNi0wNS0xM1QxMDoz…"
}

POST /api/v1/transactions
{
  "type": "expense",
  "amount": 8.50,
  "currencyCode": "EUR",
  "date": "2026-05-12T09:14:00Z",
  "accountId": "acc_01HK8V…",
  "categoryId": "cat_food_drinks",
  "payee": "Pret",
  "note": "Flat white"
}

Пакетні операції

Розроблено для імпортерів. Кожен пакет обмежено 100 елементами і виконується за принципом best-effort: один хибний рядок не відкочує решту. Успішні елементи та помилки по кожному рядку повідомляються окремо, тож невдалі можна повторити.

{
  "items": [ /* successful TransactionDto[] */ ],
  "errors": [
    { "index": 3, "error": "Invalid currency code" }
  ]
}

{
  "deleted": 97,
  "notFound": [ "tx_old1", "tx_old2", "tx_old3" ]
}

Об’єкт транзакції

Іконки

Manilo постачається з підібраним набором іконок і палітрою кольорів, які використовуються всюди — для рахунків, категорій, груп. Отримайте каталог один раз, закешуйте його й повторно використовуйте ідентифікатори під час створення ресурсів.

{
  "version": "2026.05.10",
  "library": "font-awesome-6",
  "categories": [
    {
      "id": "finance",
      "name": "Finance",
      "icons": [ "wallet", "credit-card", "piggy-bank" ]
    }
  ],
  "colors": [
    { "name": "Blue", "hex": "#4A90E2" },
    { "name": "Green", "hex": "#22C55E" }
  ]
}

Версіонування

• Жодних ламких змін у межах v1. Ми додаватимемо лише нові ендпоїнти, нові необов’язкові поля та нові значення переліків. Тип поля, його допустимість null чи обов’язковість не змінюватимуться.
• Нові значення переліків не є ламкою зміною. Ставтеся до невідомих значень type, source чи action як до «не відображати», а не завершуйте роботу аварійно — ми додаватимемо їх у міру розвитку продукту.
• Ламкі зміни (якщо колись знадобляться) вийдуть під /api/v2/ із щонайменше 6 місяцями паралельної доступності та заголовком про застарілість у відповідях v1.

Підтримка

Знайшли помилку, потрібен новий ендпоїнт або натрапили на щось недокументоване? Відкрийте центр допомоги або напишіть на support@manilo.app — повідомляючи про проблему, вкажіть, будь ласка, ідентифікатор запиту (він дублюється в заголовку відповіді X-Request-Id).

Щодо повідомлень, чутливих до безпеки (витік токена, обхід дозволів, несанкціоноване читання), пишіть на security@manilo.app.