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.

Marketplace może wyglądać na zdrowy w tabeli orders i nadal mijać się z prawdą w kwestii swoich finansów. Zamówienie ma status „opłacone”. Panel sprzedawcy pokazuje saldo. Jednak nic w tej tabeli nie dowodzi, jaką kwotą gotówki dysponuje platforma, ile jest winna każdemu ze sprzedawców, jaka część wpłaty stanowi przychód z prowizji ani jaki podatek VAT należy obecnie odprowadzić. API księgi podwójnego zapisu (double-entry ledger API) powstało po to, aby poprawnie rejestrować te skutki finansowe, transakcja po transakcji, zachowując bilans.

Mówiąc najprościej: API księgi podwójnego zapisu to programowalny system księgowy. Twoja aplikacja przesyła do niego zdarzenie finansowe, takie jak zrealizowana płatność (captured payment) lub zatwierdzone wypłaty, a księga zapisuje to zdarzenie jako dekret zawierający równe kwoty po stronie winien (debit) i ma (credit) na odpowiednich kontach. System ten nie przesuwa pieniędzy. On rejestruje prawdę o środkach, które przemieściły się gdzie indziej.

Co oznacza „księga podwójnego zapisu” w tym kontekście

Księga to rejestr zmian na kontach, a nie tabela przechowująca wyłącznie bieżące saldo. Działająca księga opiera się na trzech powiązanych pojęciach:

Konto (Account): nazwana pozycja finansowa, taka jak należności od operatora płatności (payment processor receivable), zobowiązania wobec sprzedawców (seller payable), przychody z prowizji (commission revenue) lub zobowiązania z tytułu VAT (VAT payable).
Transakcja lub dekret (Transaction / journal): jedno atomowe zdarzenie finansowe zawierające wiele zbilansowanych wierszy.
Wpis lub pozycja (Entry / posting): pojedyncza linia dekretu po stronie winien lub ma w ramach danej transakcji.

Niezmiennik, który spaja cały projekt, jest prosty: suma kwot po stronie winien musi być równa sumie kwot po stronie ma dla każdej transakcji i każdej waluty. API ksiąg z regule odrzucają niezbilansowany zapis, zanim jeszcze trafi on do pamięci masowej. Dokumentacja Modern Treasury definiuje transakcję w księdze jako operację angażującą dwa lub więcej kont z co najmniej jednym zapisem winien i jednym ma o równych sumach, traktując zatwierdzoną transakcję jako niemodyfikowalną (immutable).

Podwójny zapis nie oznacza dokładnie dwóch wierszy. Pojedyncza sprzedaż na marketplace często wymaga jednego wpisu po stronie winien i kilku po stronie ma. To właśnie ten aspekt najczęściej budzi błędne zrozumienie.

Dlaczego marketplace potrzebuje księgi, a nie tylko tabeli płatności

Marketplace utrzymuje kilka relacji finansowych w tym samym czasie. Kupujący płaci. Operator płatności rozlicza transakcję. Platforma może tymczasowo kontrolować środki. Sprzedawca zarabia swoją część. Platforma zatrzymuje prowizję. Powstaje zobowiązanie podatkowe. Część środków może zostać zatrzymana jako rezerwa. Później wypłata transferuje pieniądze na zewnątrz, a zwroty lub obciążenia zwrotne (chargebacks) cofają niektóre z tych operacji.

Tabela payments w bazie danych potrafi określić status handlowy zamówienia, ale nie wskaże w sposób wiarygodny:

ile wynosi należność od operatora płatności lub stan gotówki
ile platforma jest winna każdemu ze sprzedawców
jaki przychód należy do platformy
jak wysoki podatek VAT jest należny i w jakim kraju
jaka kwota została zabezpieczona na poczet zwrotów lub sporów
czy wypłata faktycznie zmniejszyła właściwe zobowiązanie wobec sprzedawcy
czy rozliczenia z operatorem płatności pokrywają się z oczekiwaniami platformy

Przewodnik Nordlet po API ksiąg podwójnego zapisu w księgowości marketplace stawia sprawę jasno: tabele aplikacji opisują stan produktów, podczas gdy księga rejestruje finansowe konsekwencje tego stanu. Warto też powtórzyć inny wniosek z tego tekstu: raporty od operatorów płatności stanowią dane wejściowe do procesu uzgadniania (reconciliation), a nie pełną księgi rachunkową prowadzoną metodą podwójnego zapisu.

Przykład transakcji sprzedaży na marketplace

Załóżmy, że kupujący płaci €100, sprzedawcy należy się €85, a prowizja platformy wynosi €15. Dla zachowania przejrzystości pomijamy podatek VAT oraz opłaty operatora płatności.

Konto	Winien (Debit)	Ma (Credit)	Uzasadnienie
Należności od operatora płatności	€100		Operator jest winien platformie zrealizowaną płatność
Zobowiązania wobec sprzedawcy		€85	Platforma jest winna sprzedawcy
Przychody z prowizji		€15	Platforma zarobiła na prowizji
Suma	€100	€100	Zbilansowane

Istotna klasyfikacja polega tu na tym, że kwota €85 należna sprzedawcy jest zobowiązaniem, a nie przychodem platformy. Zgodnie z założeń koncepcyjnych MSSF (IFRS), zobowiązanie to obecny obowiązek transferu zasobu gospodarczego. Marketplace nie powinien wykazywać pełnej kwoty ze sprzedaży sprzedawcy jako własnego dochodu tylko dlatego, że kupujący zapłacił za pośrednictwem platformy. Rola platformy jako agenta, mocodawcy (principal) lub podatnika uważanego za dostawcę (deemed supplier) wpływa na podejście księgowe, ale mechanizm samej księgi pozostaje bez zmian.

Kiedy sprzedawca staje się uprawniony do wypłaty, nie dochodzi do rozpoznania nowego przychodu. Następuje rozliczenie zobowiązania:

Konto	Winien (Debit)	Ma (Credit)
Zobowiązania wobec sprzedawcy	€85
Rachunek bankowy lub rozliczeniowy wypłat		€85
Suma	€85	€85

Jeśli operator płatności pobiera prowizję w wysokości €3 przed przekazaniem środków, przepływ gotówki zamienia się w trzyliniowy dekret: €97 trafia na gotówkę bankową, €3 na koszty operacji płatniczych, a €100 schodzi z należności od operatora. Każda zmiana pozycji ma swoje źródło i miejsce docelowe.

Jak działa API – krok po kroku

1. Twoja aplikacja wykrywa zdarzenie gospodarcze. Następuje zrealizowanie płatności, realizacja zamówienia, zatwierdzenie wypłaty, wydanie zwrotu, otwarcie sporu (chargeback) lub rozliczenie okresu. Twoja baza danych nadal odpowiada za stan operacyjny, a księga rejestruje skutek finansowy.

2. Wysyłasz ustrukturyzowane żądanie. Zazwyczaj zawiera ono typ zdarzenia, kwotę i walutę, identyfikator zamówienia lub płatności, identyfikatory kupującego i sprzedawcy, prowizję, dane podatkowe, powiązane konta, daty operacji i dekretu, klucz idempotencji oraz metadane łączące wpis z zapisami u operatora płatności i w systemie produktów. Publiczny przykład API Nordlet prezentuje przykładowe zapytanie o sprzedaż zawierające identyfikator sprzedawcy, typ sprzedaży, kwotę, walutę oraz kraj i stawkę VAT.

3. API weryfikuje dane. System sprawdza, czy strony winien i ma się bilansują, czy konta istnieją i można na nich księgować, czy waluta jest obsługiwana, czy kwota wykorzystuje precyzyjną obsługę najmniejszych jednostek walutowych (minor-unit handling), czy klucz idempotencji nie został użyty ponowne dla innego wyniku, czy okres księgowy jest otwarty oraz czy dostarczono wymagane metadane. Nieudana weryfikacja nie pozostawia w systemie żadnego częściowego dekretu.

4. Księgowanie odbywa się w sposób atomowy. Cała transakcja zapisuje się jako jedna spójna całości. System nie dopuszcza sytuacji, w której zapis po stronie winien przejdzie pomyślnie, a pasujące do niego ma zakończy się błędem. W przypadku marketplace częściowy podział mógłby prowadzić do powstania pozornego salda sprzedawcy bez pokrycia w gotówce lub do zaksięgowania prowizji bez jednoczesnego ujęcia zobowiązania wobec sprzedawcy.

5. Salda i raporty wynikają bezpośrednio z księgi. Po zaksięgowaniu można odczytać salda kont, salda oczekiwane i dostępne sprzedawców, zestawienie obrotów i sald (trial balance), historię księgi głównej, podsumowania VAT oraz historię na określoną datę wsteczną. Saldo sprzedawcy powinno dać się w pełni odtworzyć z dekretów, zamiast polegać na modyfikowalnym polu w bazie.

6. Webhooki powiadamiają Twój produkt. Zdarzenia takie jak sale_invoice.paid, zaksiegowany dekret, dostępność środków do wypłaty czy wyjątek uzgodnieniowy są przesyłane do Twojego systemu. Przetwarzaj je w sposób idempotentny. Webhook to powiadomienie, a nie pozwolenie na ponowne zastosowanie tego samego zdarzenia finansowego. Konwencje API szczegółowo opisują zakresy (scopes), klucze idempotencji, strukturę błędów oraz podpisywanie webhooków.

Salda sprzedawców to nie jest pojedyncza liczba

Większość platform marketplace popada w kłopoty, traktując saldo sprzedawcy jako jedną wartość. Pieniądze powinny znajdować się w odpowiednich stanach:

Stan	Znaczenie
Oczekujące (Pending)	Sprzedawca może być uprawniony do środków, ale warunki ich zwolnienia nie zostały jeszcze spełnione
Dostępne (Available)	Środki kwalifikujące się do wypłaty
Zabezpieczone / Rezerwa (Reserved)	Wstrzymane na poczet zwrotów, reklamacji lub sporów
Wypłacone (Paid out)	Zobowiązanie uregulowane w drodze transferu
Ujemne (Negative)	Zwroty, chargebacki lub opłaty przewyższają dostępne środki

Modele operatorów płatności odzwierciedlają to podejście. Przepływ osobnych obciążeń i transferów w Stripe pozwala platformie obciążyć własne konto, a następnie przelać odpowiednie części na konta powiązane, podczas gdy opłaty, zwroty i spory trafiają na saldo platformy. Model marketplace w Adyen rozróżnia konta salda użytkowników, które przetrzymują środki do momentu wypłaty, od konta salda obciążonego odpowiedzialnością (liable balance account), mogącego przejąć ujemne salda wynikające ze zwrotów lub sporów. Stanowią one przydatne dane wejściowe do Twojej księgi, choć nie zastępują kompletnego modelu księgowego.

Wypłaty i zarobki sprzedawców nastęują w różnych momentach

Sprzedawca może zarobić pieniądze w poniedziałek, a otrzymać wypłatę w kolejny poniedziałek. W międzyczasie zamówienie jest realizowane, tworzona jest rezerwa, budowana jest paczka wypłat (payout batch), operator rozlicza transakcję pomniejszoną o opłaty, a na konto bankowe wpływa przelew. Księga musi zachować każdy z tych etapów zamiast nadpisywać zamówienie ostatecznym statusem „opłacone”. To właśnie pozwala wyjaśnić różnice czasowe między aktywnością zamówień, uprawnieniami sprzedawcy, rozliczeniem, zainicjowaniem wypłaty a wpływem środków do banku.

Zwroty i spory: koryguj poprzez zapisy przeciwstawne, nie nadpisuj

Zwroty i reklamacje to nowe zdarzenia powiązane z oryginalną płatnością. W niezmienneks (niemodyfikowalnej) księdze korekty dokonuje się za pomocą wpisu odwracającego (reversing entry), po którym następuje wpis prawidłowy, dzięki czemu pierwotna operacja pozostaje widoczna dla celów audytu. Modern Treasury traktuje zaksiegowane transakcje jako niemodyfikowalne i obsługuje klucze idempotencji, aby zapobiec powstawaniu duplikatów obiektów w przypadku ponowienia prób.

Zwrot zazwyczaj zmniejsza gotówkę lub należności od kupującego, odwraca zobowiązanie wobec sprzedawcy, może – w zależności od regulaminu – korygować część prowizji, dostosowuje podatek oraz może pomniejszyć rezerwę na zwroty. Sporek (chargeback) zmniejsza gotówkę lub należności od operatora, może ponownie otworzyć kwotę należną od sprzedawcy lub platformy, rejestruje koszty sporne oraz opłatę operatora, a także przemieszcza środki przez konto rezerwowe.

Uzgadnianie (reconciliation): łączenie księgi z prawdziwymi pieniędzmi

Księga może być wewnętrznie zbilansowana, a mimo to mijać się z rzeczywistością świata zewnętrznego. Uzgadnianie polega na porównywaniu zapisów wewnętrznych z dowodami zewnętrznymi: raportami rozliczeniowymi operatorów, wyciągami bankowymi, plikami wypłat oraz dokumentacją zwrotów i sporów.

Praktyczny cykl wygląda następująco:

Zaimportuj paczkę rozliczeniową lub wyciąg bankowy.
Dopasuj każdą pozycję do zamówienia, płatności, zwrotu, opłaty, wypłaty lub sporu.
Porównaj oczekiwaną kwotę brutto, potrącenia, rezerwy oraz kwotę netto.
Zaksięguj potwierdzone ruchy w księdze.
Przekieruj niedopasowane pozycje na nazwane konto przejściowe (suspense account).
Przeprowadź dochodzenie wyjaśniające wyjątki.
Zamknij okres księgowy.

Materiały Nordlet dotyczące uzgadniania opisują dokładnie ten proces: importowanie paczek rozliczeniowych, dopasowywanie linii opłat i zwrotów oraz kierowanie niedopasowanych wpływów na konto przejściowe zamiast zgadywania faktury. Dwa rodzaje kontroli mają kluczowe znaczenie i żaden z nich nie zastępuje drugiego: walidacja podwójnego zapisu sprawdza, czy każdy dekret się bilansuje, natomiast uzgadnianie weryfikuje, czy dane zgadzają się z operatorem płatności, bankiem i faktycznym zdarzeniem gospodarczym.

Detale projektowe decydujące o sukcesie

Idempotencja. Powiąż klucz ze stabilnym zdarzeniem, na przykład payment_captured:pi_123. Ponowna próba zwraca pierwotny wynik, zamiast generować drugi dekret.

Atomowość. Wszystkie linie pojedynczego zdarzenia zapisują się razem albo żadna z nich nie trafia do systemu.

Niezmiennik i zapisy korygujące. Zaksiegowana historia nie podlega edycji poprzez zwykłe aktualizacje. Korekty tworzą powiązane wpisy, które zachowują pierwotną kwotę, datę, klasyfikację, powód oraz autora.

Precyzyjna reprezentacja pieniądza. Żadnych binarnych liczb zmiennoprzecinkowych. Używaj integerów w najmniejszych jednostkach walutowych lub dokładnych wartości dziesiętnych, jawnej waluty oraz deterministycznej reguły zaokrąglania dla podziałów. Jeśli podzielisz €100 między sprzedawców i opłaty bez takiej zasady, zagubiony cent zepsuje Ci bilans.

Daty operacji a daty dekretu. Momenty, w których zapłacił kupujący, w których sprzedawca zarobił, w których bank rozliczył transakcję oraz w których wpis został zaksiegowany, to różne daty. Ich utożsamianie czyni sprawozdawczość okresową oraz rozliczenia podatkowe niewiarygodnymi.

Obsługa wielu walut. Strona winien i ma powinny się bilansować w ramach tej samej waluty. Konwersja wymaga jawnego zdarzenia kursowego z kontami dla prowizji, zaokrągleń oraz wszelkich zysków lub strat kursowych. Przyjmowanie pola currency nie czyni z księgi silnika walutowego.

Czego API księgi dla Ciebie nie zrobi

Nie podejmie decyzji o kształcie Twojego planu kont. Nadal musisz określić, czy działasz jako mocodawca czy agent, kiedy prowizja jest zarobiona, która strona ponosi opłaty operatora, jak zwroty wpływają na prowizję oraz jak kalkulowany i raportowany jest podatek VAT. Wytyczne Nordlet sugerują, aby najpierw zamapować przepływy pieniężne, przygotować projekt planu kont, skonsultować go z księgowym, a następnie zaimplementować jeden pełny obieg od zamówienia, przez wypłatę, aż po uzgodnienie, zanim przystąpisz do skalowania.

System nie rozwiąże też kwestii podatkowych. Podatek VAT zależy od lokalizacji kupującego i sprzedawcy, rodzaju produktu, statusu rejestracji oraz zasad dotyczących podatnika uwzględnianego jako dostawca (deemed supplier). Przewodnik po unijnym VAT wskazuje, co silnik wylicza automatycznie, a co wymaga flagowania dla człowieka. Zakres podatkowy Nordlet koncentruje się na UE i EOG, więc nie obejmuje amerykańskiego podatku obrotowego (sales tax) ani fakturowania elektronicznego w Ameryce Łacińskiej. Narzędzie nie rozstrzyga również niejasności operacyjnych: czy okres zwrotu minął, czy wypłata powinna zostać zablokowana lub czy płatność jest oszukańcza. To Twoje decyzje. Księga rejestruje jedynie ich wynik finansowy.

Gdzie w tym wszystkim pojawia się Nordlet

Nordlet to API księgowe stworzone dla platform i marketplace'ów, oferujące niemodyfikowalną księgę podwójnego zapisu, system wypłat, obsługę unijnego VAT-u, endpointy REST, otypowane pakiety SDK oraz webhooki dostępne z poziomu jednego interfejsu. Jego wyróżnikiem jest osadzenie księgowości bezpośrednio w Twoim produkcie zamiast polegania na zewnętrznym systemie płatności. W momencie pisania tego tekstu produkt znajduje się w fazie wczesnego dostępu (early access) wraz z piaskownicą (sandbox) dla partnerów projektowych, należy więc traktować go jako mocnego reprezentanta tej kategorii i przed wdrożeniem produkcyjnym ocenić dojrzałość, czas bezawaryjnej pracy (uptime) oraz pokrycie jurysdykcyjne pod kątem własnych potrzeb.

Dla deweloperów marketplace'ów i platform użytecznym modelem myślowym jest podział na ruch środków pieniężnych oraz finansową prawdę. Twój operator płatności przemieszcza pieniądze. API księgi podwójnego zapisu rejestruje, kto komu jest co winien, ile zarobiłeś, jakie podatki i rezerwy posiadasz oraz czy świat zewnętrzny zgadza się z Twoimi księgami.

FAQ

Czy API księgi podwójnego zapisu to to samo co operator płatności?

Nie. Operator autoryzuje, realizuje, rozlicza, a czasami także wypłaca środki. API księgi rejestruje skutki księgowe tych zdarzeń. Większość marketplace'ów korzysta z obu rozwiązań: operatora takiego jak Stripe lub Adyen do przepływu środków oraz księgi do prowadzenia ewidencji.

Czy mogę używać panelu operatora płatności jako księgi głównej?

Możesz spróbować, ale prędzej czy później taka konfiguracja obleje audyt. Raporty od operatorów pokazują obciążenia, opłaty, transfery i rozliczenia, ale zazwyczaj nie odzwierciedlają pełnych zobowiązań wobec sprzedawców, zobowiązań podatkowych, kosztów spoza systemu operatora czy korekt księgowych. Traktuj je jako dane wejściowe do uzgadniania.

Czy zbilansowana księga oznacza, że moje zapisy są poprawne?

Oznacza jedynie tyle, że Twoje wpisy spełniają regułę winien-ma. Perfekcyjnie zbilansowana transakcja nadal może zostać zaksięgowana na niewłaściwym koncie, przypisana do złego sprzedawcy lub objęta błędnym traktowaniem podatkowym. Bilans jest konieczny, ale niewystarczający. To uzgadnianie wyłapuje pozostałe błędy.

Skoro księga jest niemodyfikowalna, jak naprawić pomyłki?

Księgujesz wpis odwracający, a następnie wpis skorygowany. Oryginalny wpis pozostaje widoczny i o to właśnie chodzi. Niemodyfikowalność chroni ścieżkę audytu, a nie więzi Twoje błędy.

Czy API księgowe zapewnia automatyczną zgodność z przepisami?

Nie. Narzędzie wymusza strukturę księgową i generuje użyteczne zapisy. Zgodność z prawem nadal zależy od Twojej jurysdykcji, roli umownej, traktowania podatkowego, przepisów płatniczych, procedur KYC i AML oraz obowiązków sprawozdawczych.