What Is a Double-Entry Ledger API for Marketplaces?
A double-entry ledger API records marketplace money movement as balanced, immutable journal entries so you always know who is owed what and why.
Маркетплейс може виглядати успішним за даними таблиці orders (замовлення), але мати серйозні помилки в облік грошей. У замовленні зазначено „оплачено“. В кабінеті продавця відображається баланс. Проте жоден рядок у цій таблиці не доводить, скільки готівки фактично тримає платформа, скільки вона винна кожному продавцю, яка частина платежу є доходом від комісії або скільки ПДВ підлягає сплаті. API бухгалтерської книги з подвійним записом (double-entry ledger API) створене саме для того, щоб правильно фіксувати ці фінансові наслідки по одній збалансованій транзакції за раз.
Просто кажучи, API книги з подвійним записом – це програмована бухгалтерська система. Ваша програма надсилає до неї фінансову подію (наприклад, списаний платіж або схвалену виплату), а книга записує цю подію у вигляді журналу з рівними дебетами та кредитами по визначених рахунках. Вона не переказує гроші. Вона фіксує правду про гроші, які перемістилися в іншому місці.
Що означає «книга з подвійним записом» у цьому контексті
Бухгалтерська книга – це історія змін за рахунками, а не таблиця з поточним залишком. Працююча книга базується на трьох взаємопов'язаних поняттях:
- Рахунок (Account): іменована фінансова позиція, наприклад дебіторська заборгованість платіжного шлюзу, кредиторська заборгованість перед продавцем, дохід від комісії або зобов'язання з ПДВ.
- Транзакція (журнал) (Transaction): одна атомарна фінансова подія, що містить кілька збалансованих рядків.
- Проводка (Entry): окремий дебетовий або кредитовий рядок всередині цієї транзакції.
Необхідна умова, на якій тримається вся архітектура, проста: загальна сума дебетів дорівнює загальній сумі кредитів для кожної транзакції та кожної валюти. API книг зазвичай відхиляють незбалансований запис ще до того, як він потрапить до сховища. У документації Modern Treasury транзакція книги визначається як така, що охоплює два або більше рахунків щонайменше з одним дебетом та одним кредитом рівних сум, причому проведена транзакція розглядається як незмінна (immutable).
Подвійний запис не означає рівно два рядки. Одному продажу на маркетплейсі часто потрібен один дебет і кілька кредитів. Саме це люди найчастіше розуміють хибно.
Чому маркетплейсам потрібна книга, а не просто таблиця платежів
Маркетплейс одночасно підтримує кілька фінансових взаємин. Покупець платить. Шлюз здійснює розрахунок. Платформа може тимчасово контролювати кошти. Продавець заробляє свою частку. Платформа утримує комісію. Нараховується податок до сплати. Може утримуватися резерв. Пізніше виплата переказує гроші назовні, а повернення або чарджбеки (chargebacks) частково скасовують ці операції.
Таблиця payments (платежі) може підказати комерційний статус замовлення. Але вона не може надійно відповісти на такі питання:
- яка сума дебіторської заборгованості шлюзу або готівки існує наявна
- скільки грошей винно кожному продавцю
- який обсяг доходу належить платформі
- скільки ПДВ підлягає сплаті та в якій країні
- яка сума зарезервована під повернення чи спори
- чи зменшила виплата коректне зобов'язання перед продавцем
- чи збігаються розрахунки платіжного шлюзу з очікуваннями платформи
Посібник Nordlet з API книг з подвійним записом для обліку на маркетплейсах чітко проводить межу: таблиці додатків описують стан продукту, тоді як книга фіксує фінансові наслідки цього стану. У ньому також висловлено думку, яку варто повторити: звіти платіжних шлюзів є вхідними даними для звірки (reconciliation), а не повноцінними регістрами подвійного запису.
Приклад продажу на маркетплейсі
Припустимо, покупець сплачує €100, продавець має отримати €85, а комісія платформи становить €15. Для наочності проігноруємо ПДВ та комісії шлюзу.
| Рахунок | Дебет | Кредит | Причина |
|---|---|---|---|
| Дебіторська заборгованість платіжного шлюзу | €100 | Шлюз винен платформі списаний платіж | |
| Кредиторська заборгованість перед продавцем | €85 | Платформа винна продавцю | |
| Дохід від комісії | €15 | Платформа заробила свою комісію | |
| Разом | €100 | €100 | Збалансовано |
Важлива класифікація тут полягає в тому, що €85, які винні продавцю, є зобов'язанням (liability), а не доходом платформи. Згідно з концептуальною основою МСФЗ (IFRS), зобов'язання – це поточний обов'язок передати економічний ресурс. Маркетплейс не повинен відображати повну виручку від продажу продавця як власний дохід лише тому, що покупець заплатив через нього. Роль агента, принципала чи податкового агента змінює порядок обліку, але механізм книги залишається незмінним.
Коли продавець отримує право на виплату, новий дохід не визнається. Ви погашаєте зобов'язання:
| Рахунок | Дебет | Кредит |
|---|---|---|
| Кредиторська заборгованість перед продавцем | €85 | |
| Банк або транзитний рахунок виплат | €85 | |
| Разом | €85 | €85 |
Якщо шлюз утримує комісію €3 перед розрахунком, грошовий потік перетворюється на журнал із трьох рядків: €97 надходить на банківську готівку, €3 відносяться на витрати на обробку, а €100 списуються з дебіторської заборгованості шлюзу. Кожна зміна позиції має джерело та призначення.
Як працює API: крок за кроком
1. Ваша програма виявляє бізнес-подію. Платіж списано, замовлення виконано, виплату схвалено, оформлено повернення, відкрито чарджбек, надійшов розрахунок. Ваша база даних продовжує керувати операційним станом. Книга фіксує грошовий ефект.
2. Ви надсилаєте структурований запит. Зазвичай він містить тип події, суму та валюту, ідентифікатор замовлення чи платежу, ідентифікатори покупця і продавця, комісію, податкові дані, задіяні рахунки, дати валютування та проведення, ключ ідемпотентності (idempotency key), а також метадані із посиланнями на шлюз і записи продукту. Приклад публічного API Nordlet демонструє концептуальний запит на продаж із ідентифікатором продавця, типом продажу, сумою, валютою, а також країною та ставкою ПДВ.
3. API виконує валідацію. Він перевіряє, чи збалансовані дебети та кредити, чи існують рахунки і чи дозволено на них проводити записи, чи підтримується валюта, чи використовується точна обробка малих одиниць валюти (minor units), чи не використовується повторно ключ ідемпотентності для іншого результату, чи відкритий звітний період та чи наявні необхідні метадані. У разі невдалої перевірки в системі не залишається часткових записів журналу.
4. Виконання проводки в атомарному режимі. Вся транзакція записується як єдине ціле. Неможливо зафіксувати дебет, якщо відповідний кредит завершився помилкою. Для маркетплейса частковий розділ міг би створити видимість балансу продавця без відповідної готівки або провести комісію без зобов'язань перед продавцем.
5. Баланси та звіти формуються на основі книги. Після проведення ви можете переглядати залишки на рахунках, очікувані та доступні баланси продавця, оборотно-сальдову відомість, операції за головною книгою, зведення ПДВ та історію станом на минулу дату. Баланс продавця має відновлюватися з проводок, а не братися з нестійкого поля, яке можна редагувати.
6. Вебхуки (webhooks) сповіщають ваш продукт. Такі події, як sale_invoice.paid, проведений журнал, доступна виплата або виключення під час звірки, надсилаються до вас. Обробляйте їх ідемпотентно. Вебхук – це сповіщення, а не дозвіл застосовувати фінансову подію вдруге. Угоди щодо API докладно описують області видимості (scopes), ключі ідемпотентності, формати помилок та підписування вебхуків.
Баланси продавців – це не одне число
Більшість маркетплейсів стикаються з проблемами через те, що розглядають баланс продавця як єдине число. Гроші повинні розподілятися за станами:
| Стан | Значення |
|---|---|
| Очікує (Pending) | Продавець може мати право, але умови виплати не виконано |
| Доступно (Available) | Готово до виплати |
| Зарезервовано (Reserved) | Утримано на випадок повернень або спорів |
| Виплачено (Paid out) | Зобов'язання погашено шляхом переказу |
| Від'ємний (Negative) | Повернення, чарджбеки або комісії перевищують доступні кошти |
Моделі платіжних шлюзів відображають це. Розділений потік платежів та переказів у Stripe дозволяє платформі стягувати кошти на власний рахунок, а потім переказувати частини на пов'язані рахунки, причому комісії, повернення та чарджбеки потрапляють на баланс платформи. Модель маркетплейса Adyen розрізняє рахунки балансу користувачів, які зберігають кошти до виплати, та рахунок відповідального балансу, який може покривати від'ємні баланси від повернень або чарджбеків. Це корисні вхідні дані для вашої книги, але вони не замінюють повноцінну модель обліку.
Виплати та доходи продавців відбуваються в різний час
Продавець може заробити кошти в понеділок, а отримати їх у наступний понеділок. Між цими моментами замовлення виконується, утримується резерв, формується пакет виплат, шлюз проводить розрахунок за вирахуванням комісій і надходить банківський переказ. Книга повинна зберігати кожен етап замість перезапису замовлення фінальним статусом „оплачено“. Це дозволяє пояснити тимчасові розбіжності між активністю замовлень, правом продавця на кошти, розрахунком, ініціюванням виплати та надходженням грошей до банку.
Повернення та чарджбеки: сторнування замість перезапису
Повернення та чарджбеки – це нові події, пов'язані з початковим платежем. У незмінній книзі виправлення виконуються через сторнуючу проводку (reversing entry), за якою слідує скоригована, завдяки чому оригінал залишається видимим для аудиту. Modern Treasury розглядає проведені транзакції як незмінні та підтримує ключі ідемпотентності, щоб запобігти створенню дублікатів об'єктів під час повторних спроб.
Повернення зазвичай зменшує готівку або дебіторську заборгованість покупця, сторнує кредиторську заборгованість перед продавцем, може частково скасувати комісію залежно від політики, коригує податок і може задіяти резерв на повернення. Чарджбек зменшує готівку або дебіторську заборгованість шлюзу, може відновити суму, яку винен продавець або платформа, фіксує витрати на спір та комісію шлюзу, а також переказує кошти через резервний рахунок.
Звірка: поєднання книги з реальними грошима
Книга може бути внутрішньо збалансованою, але при цьому містити помилки щодо реального світу. Звірка порівнює внутрішні записи із зовнішніми доказами: звітами про розрахунки шлюзу, виписками з банківських рахунків, файлами виплат, записами про повернення та спори.
Робочий цикл виглядає так:
- Імпорт пакета розрахунків або банківського файлу.
- Зіставлення кожного рядка із замовленням, платежем, поверненням, комісією, виплатою чи спором.
- Порівняння очікуваного валового доходу, утримань, резервів та чистої суми.
- Проведення підтверджених рухів у книзі.
- Направлення незіставлених елементів на спеціальний транзитний рахунок (suspense account).
- Розслідування розбіжностей.
- Закриття періоду.
Матеріали Nordlet зі звірки описують саме цей процес: імпорт пакетів розрахунків, зіставлення рядків списань і повернень, а також направлення незіставлених надходжень на транзитний рахунок замість того, щоб вгадувати призначення рахунка-фактури. Дві перевірки мають значення, і жодна з них не замінює іншу: валідація подвійного запису запитує, чи збалансований кожен журнал, а звірка запитує, чи збігається він зі шлюзом, банком та бізнес-подією.
Проєктування деталей, від яких залежить успіх
Ідемпотентність. Прив'яжіть ключ до стабільної події, наприклад payment_captured:pi_123. Повторна спроба повертає оригінальний результат, а не другий журнал.
Атомарність. Усі рядки однієї події проводяться разом або не проводяться взагалі.
Незмінність та сторнування. Проведена історія не редагується звичайними оновленнями. Виправлення створюють пов'язані записи, які зберігають початкову суму, дату, класифікацію, причину та автора.
Точність грошових сум. Жодних двійкових чисел із плаваючою комою. Використовуйте цілі малі одиниці валюти (minor units) або точні десяткові дроби, явну валюту та детерміноване правило заокруглення для розподілів. Якщо розділити €100 між продавцями та комісіями без цього, випадковий цент порушить баланс.
Дати валютування та проведення. Дата сплати покупцем, дата заробітку продавцем, дата розрахунку банком та дата проведення запису різняться. Їх змішування робить звітність за періоди та податковий облік ненадійними.
Мультивалютність. Дебет і кредит повинні бути збалансованими в межах однієї валюти. Конвертація потребує явної події курсу з рахунками для комісії, заокруглення та будь-яких прибутків чи збитків від курсових різниц. Додавання поля currency не перетворює книгу на валютний конвертор.
Чого API книги не зробить за вас
Вона не визначить ваш план рахунків (chart of accounts). Вам усе одно доведеться з'ясувати, чи ви є принципалом чи агентом, коли заробляється комісія, яка сторона сплачує комісії шлюзу, як повернення впливають на комісію, а також як розраховується та звітується ПДВ. Посібник Nordlet радить спочатку відобразити грошові потоки, скласти проєкт плану рахунків, залучити бухгалтера для його перевірки, а потім реалізувати один повний цикл від замовлення до виплати та звірки перед масштабуванням.
Вона не вирішить податкові питання. ПДВ залежить від місця перебування покупця і продавця, типу продукту, статусу реєстрації та правил щодо податкових агентів; посібник з ПДВ в ЄС окреслює, що саме система розраховує самостійно, а що виділяє для перевірки людиною. Облік ПДВ у Nordlet орієнтований на ЄС та ЄЕЗ, тому він не поширюється на податок з продажів у США (US sales tax) чи електронне виставляння рахунків у Латинській Америці. Крім того, вона не усуває операційну невизначеність: чи закінчився термін повернення, чи варто заблокувати виплату, чи є платіж шахрайським. Це ваші рішення. Книга фіксує їхній фінансовий результат.
Де місце Nordlet
Nordlet – це обліковий API, створений для платформ і маркетплейсів, який містить незмінну книгу з подвійним записом, виплати, обробку ПДВ в ЄС, REST ендпоїнти, типізовані SDK та вебхуки, доступні через єдиний інтерфейс. Її відмінною рисою є вбудована бухгалтерія всередині вашого власного продукту, а не сторонній чекаут. На момент написання цієї статті продукт перебуває на стадії раннього доступу із пісочницею для партнерів з розробки, тому сприймайте його як яскравий приклад категорії та ретельно оцінюйте виробничу готовність, час безперебійної роботи (uptime) і юрисдикційне покриття для вашого власного кейсу перед прийняттям остаточного рішення.
Для розробників маркетплейсів і платформ корисною ментальною моделлю є поділ між рухом платежів і фінансовою правдою. Ваш платіжний шлюз рухає гроші. API книги з подвійним записом фіксує, хто і кому винен, скільки ви заробили, які податки та резерви ви утримуєте, і чи збігається зовнішній світ із вашими книгами.
FAQ
Чи є API книги з подвійним записом тим самим, що й платіжний шлюз?
Ні. Шлюз авторизує, списує, проводить розрахунки, а іноді й здійснює виплати кошти. API книги фіксує бухгалтерські наслідки цих подій. Більшість маркетплейсів використовують обидва рішення: шлюз (наприклад, Stripe або Adyen) для руху грошей та книгу для обліку.
Чи можу я просто використовувати кабінет свого шлюзу як головну книгу?
Ви можете спробувати, але зрештою це призведе до провалу аудиту. Звіти платіжних шлюзів показують списання, комісії, перекази та розрахунки, але зазвичай вони не відображають повних зобов'язань перед продавцями, податкових зобов'язань, нешлюзових витрат чи бухгалтерських коригувань. Використовуйте їх як вхідні дані для звірки.
Чи означає збалансованість книги правильність мого обліку?
Лише те, що ваші записи відповідають правилу дебету та кредиту. Ідеально збалансовану транзакцію все одно можна провести на не той рахунок, не тому продавцю або застосувати до неї неправильний податковий режим. Баланс є необхідною умовою, але його недостатньо. Звірка допомагає виявити решту розбіжностей.
Якщо книга є незмінною, як виправити помилки?
Ви проводите сторнуючу проводку, а потім скориговану. Початковий запис залишається видимим, у цьому й полягає його сенс. Незмінність захищає слід аудиту, а не створює пастку для ваших помилок.
Чи робить бухгалтерський API мою діяльність автоматично відповідною нормам законодавства?
Ні. Він забезпечує бухгалтерську структуру та формує придатні для використання записи. Дотримання законодавства (compliance) іноді залежить від вашої юрисдикції, ролі за договором, податкового режиму, правил здійснення платежів, процедур KYC та AML, а також обов'язків зі звітності.