Що таке бухгалтерський API? Простий посібник для розробників платформ

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

Бухгалтерський API - це інтерфейс, який дозволяє одній програмі вести бухоблік для іншої програми. Ваше програмне забезпечення надсилає фінансову подію через HTTP. API перетворює цю подію на збалансовані проводки подвійного запису за планером рахунків (chart of accounts), зберігає їх у спосіб, що унеможливлює непомітну зміну, застосовує податковий режим і повертає вам звіти, документи та експорти через той самий інтерфейс.

Це визначення виконує більшу частину роботи. Усе інше в цій статті є його наслідком.

Версія в один рядок

Бухгалтерський API приймає фінансові події від вашого додатка, перетворює кожну з них на збалансовану проводку, зберігає її незмінно разом із податковим режимом та підтвердними доказами, а також надає отриману головну книгу (ledger), документи та звіти як програмовані ендпоінти.

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

Чим бухгалтерський API не є

Чотири суміжні категорії продуктів часто плутають із бухгалтерськими API, зазвичай на пізніх етапах проєкту.

Категорія	Що він робить	Чого він не робить
API розрахунку податків (Tax calculation API)	Повертає правильну ставку або суму податку для транзакції	Не веде ваші книги і не зберігає докази, що обґрунтовують рішення протягом строку зберігання
Платіжний API (Payments API)	Переказує кошти між сторонами та звітує про ці рухи	Не відображає зароблену комісію, ПДВ до сплати чи зобов'язання перед продавцем у проміжку між платежем та виплатою
Уніфікований API або агрегатор (Unified or aggregator API)	Зчитує та записує дані в наявному бухгалтерському софті вашого клієнта	Не діє як система обліку (system of record); ваші книги знаходяться в тому інструменті, яким уже користується кожен окремий клієнт
Звітний або BI API (Reporting or BI API)	Витягує цифри з наявної головної книги та візуалізує їх	Не створює проводки, з яких ці цифри походять

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

П'ять завдань, які має виконувати бухгалтерський API

1. Записувати збалансовані проводки. Кожна подія перетворюється на дебети та кредити, суми яких збігаються. Коли покупець сплачує 100 євро на маркетплейсі, який стягує комісію 15 євро, проводка дебетує транзитний рахунок на 100 євро, кредитує рахунок розрахунків із продавцем на 85 євро та кредитує дохід від комісії на 15 євро. Це не бухгалтерський ритуал. Це структурна перевірка, яка виловлює цілі класи інтеграційних помилок ще до того, як вони потраплять у звіт.

2. Зберігати історію. Проведена проводка не редагується. Помилка виправляється сторнуванням плюс правильною проводкою, і обидві пов'язані з оригіналом. Закриті місяці блокуються, щоб ніщо нове не могло бути датоване цим періодом.

3. Вирішувати питання з податками. Для торгівлі в ЄС це означає визначення місця постачання (place of supply), зворотне оподаткування (reverse charge), перевірку ідентифікаційних номерів платників ПДВ за офіційним реєстром, а також докази, що обґрунтовують прийняте рішення, - усе це зберігається разом із транзакцією, а не відкидається після розрахунку.

4. Звірятися із зовнішніми коштами. Бухгалтерія, яка ніколи не бачить банківської виписки, є лише здогадом. API має завантажувати виписки або виплати від провайдерів і зіставляти їх із тим, що було записано.

5. Експортувати дані. Звіти, документи та аудиторські файли у форматах, які приймають професійний бухгалтер та податковий орган.

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

Як насправді виглядає запис

Механіка простіша за бухоблік. В API Nordlet кожна операція є POST-запросом в стилі RPC із передбачуваною структурою:

POST /v1/{module}/{resource}/{action}
Authorization: Bearer <api key>
Idempotency-Key: <your event id>

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

Три деталі в цьому фрагменті важливіші за назву ендпоінта:

Область дії ключа (scope). Ключ має такі дозволи, як sales:write, тому інтеграція отримує лише необхідний доступ.
Ключ ідемпотентності (idempotency key). Повторіть той самий запис із тим самим корисним навантаженням, і ви отримаєте збережену відповідь замість другого рахунку. Надішліть той самий ключ із іншими даними, і запис буде відхилено з помилкою idempotency_key_reuse, а не тихо прийнято.
Гроші як рядки. Суми передаються як рядки з десятковою крапкою, а не як числа з плаваючою комою (floating-point), оскільки останні втрачають центи в такий спосіб, що спливає наприкінці року.

Де він розташовується у вашій архітектурі

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

У вашому продукті щось відбувається: замовлення, повернення коштів, виплата, поновлення підписки.
Ваш бекенд викликає бухгалтерський API з подією та ключем ідемпотентності.
API проводить бухгалтерську проводку, застосовує ПДВ і повертає ідентифікатори, які ви зберігаєте у власних записах.
Вебхук на кшталт sale_invoice.paid сповіщає вашу систему про зміну стану, тож ви реагуєте на події замість того, щоб опитувати сервер (polling).
Банківські транзакції надходять через банківський фід або імпорт виписки та зіставляються із записаними документами.
Наприкінці періоду на основі цих самих даних генеруються звіти та податкові регістри, а закритий місяць блокується.

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

Порівняння з альтернативами

Підхід	Зусилля для старту	Статус для аудиту	Масштабування за обсягом транзакцій
Електронні таблиці та введення вручну	Найнижчі	Слабкий; історія редагується	Ні
Бухгалтерський додаток плюс експорт у CSV	Низькі	Повністю залежить від дисципліни	Погано; хтось має імпортувати файли
Агрегатор API до книг кожного клієнта	Середні	Успадковує можливості софту клієнта	Так, але ви ніколи не володієте записом
Вбудований бухгалтерський API (Embedded accounting)	Середні	Високий, якщо головна книга незмінна, а періоди блокуються	Так
Побудова власної головної книги	Найвищі	Високий лише за умови самостійної побудови контролів	Так, і ви підтримуєте її вічно

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

Що перевірити перед інтеграцією

Баланс вираховується чи зберігається? Запитайте, чи є баланс продавця результатом запиту до рядків проводки, чи стовпчиком, який хтось оновлює. Лише один із цих варіантів видержить аудит.
Що відбувається при повторному запиті (retry)? Надішліть той самий запис двічі та підрахуйте проводки.
Чи можна відредагувати проведену проводку? Відповідь має бути "ні", з наявністю задокументованого шляху виправлення.
Чи дійсно заблокований період відхиляє нові проводки? Перевірте це в пісочниці. Nordlet повертає 409 для проводок, датованих усередині заблокованого періоду.
Як представлені гроші? Десяткові рядки або цілі мінорні одиниці. Жодних чисел із плаваючою комою.
Що міститься в аудиторському лозі? Суб'єкт (actor), дія, об'єкт і сама зміна, доступні для запитів, а не закопані у файлах логів.
Які ліміти запитів (rate limits)? Nordlet дозволяє 300 запитів на хвилину для одного API-ключа та повідомляє про залишок ліміту в заголовках відповіді. Хоч яким буде це число, дізнайтеся його до того, як проєктуватимете синхронізацію.
Як витягти дані назад? Звіти, документи та журнали у форматах, які можна передати бухгалтеру.

Кожен із цих пунктів можна перевірити за пів дня роботи з компанією в пісочниці. Списки функцій від постачальників не є доказами; доказом є лише відтворюваний тест.

FAQ

Чи є бухгалтерський API тим самим, що й бухгалтерське програмне забезпечення?

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

Чи потрібен мені бухгалтер, якщо я його використовую?

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

Чи можна користуватися бухгалтерським API без розуміння подвійного запису?

Частково. Хороший API формує проводки за вас на основі бізнес-документа, наприклад рахунка-фактури. Водночас вам усе одно потрібно розуміти значення рахунків під час читання звіту чи пояснення балансу аудитору.

У чому різниця між бухгалтерським API та API головної книги (ledger API)?

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

Скільки часу займає інтеграція?

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