Interfejsy API księgi podwójnego zapisu w księgowości marketplace'ów

Większość marketplace'ów odkrywa problem z księgowością w ten sam sposób: przychodzi nowa osoba do działu finansów, otwiera arkusz kalkulacyjny z wypłatami i pyta, kto właściwie rejestruje zobowiązanie wobec sprzedawców w okresie między wpłatą kupującego a wyjściem środków z konta platformy. Zespół inżynierów wskazuje na tabelę transactions. Finansista zauważa, że tabela zdarzeń to jeszcze nie księgi rachunkowe. Tę przepaść między danymi o zdarzeniach a prawdziwą księgowością ma za zadanie zlikwidować interfejs API księgi podwójnego zapisu.

To problem o charakterze technicznym, który ma jednak poważne konsekwencje regulacyjne. Marketplace'y przechowują cudze pieniądze, naliczają podatek VAT w różnych jurysdykcjach i wystawiają faktury w imieniu sprzedawców. Robienie tego za pomocą domowej roboty tabeli transakcji działa do momentu, w którym audytor, organ podatkowy lub poważny inwestor poprosi o dowody.

Czym właściwie jest API księgi podwójnego zapisu

API księgi podwójnego zapisu to programowalny silnik księgowy udostępniany przez HTTP. Każde zdarzenie finansowe zarejestrowane na platformie jest zapisywane jako zbilansowany wpis w dzienniku: co najmniej jedno obciążenie (debet) i jedno uznanie (kredyt) o równej sumie, zaksięgowane na odpowiednich kontach w planie kont. Interfejs API wymusza tę równowagę w momencie zapisu i przechowuje wpisy w taki sposób, aby nie można było ich później edytować bez śladu.

Część dotycząca "podwójnego zapisu" to licząca czterysta lat zasada księgowa mówiąca, że każda transakcja dotyczy co najmniej dwóch kont. „API” oznacza, że wywołania wykonuje Twój produkt, a nie człowiek siedzący w księgowości. „Niezmienność” (immutable) oznacza, że korekty wprowadza się za pomocą zapisów odwracających, a nie poprzez edycję historii. Te trzy właściwości łącznie sprawiają, że powstające księgi są gotowe do audytu, a nie tylko uporządkowane.

Przydatna definicja robocza:

API księgi podwójnego zapisu przyjmuje zdarzenia finansowe z Twojej aplikacji, przekształca każde z nich w zbilansowany zapis w dzienniku względem zdefiniowanego planu kont, przechowuje te wpisy w sposób niezmienny oraz udostępnia wynikową księgę, zestawienie obrotów i sald (trial balance) oraz raporty finansowe za pomocą przewidywalnych punktów końcowych.

Nordlet został zbudowany dokładnie wokół tej idei: prawdziwe księgi jako API, w którym księga, logika VAT, fakturowanie i uzgadnianie danych są dostępne z poziomu tego samego zestawu punktów końcowych, z których Twój produkt już korzysta.

Dlaczego marketplace'y potrzebują tego w szczególności

Firma typu SaaS obsługująca jednego sprzedawcę często może pozwolić sobie na synchronizację z zewnętrznym narzędziem księgowym raz dziennie. Marketplace'y nie mogą tego zrobić z trzech powodów.

Po pierwsze, znajdują się w samym środku przepływu pieniędzy. Kupujący płaci platformie, platforma przetrzymuje środki, a następnie wypłaca je sprzedawcom pomniejszone o prowizje. Każdy z tych ruchów to osobne zdarzenie księgowe wpływające na inne konta: środki pieniężne, zobowiązania wobec sprzedawców, przychody platformy, VAT należny, rezerwy na zwroty. Tabela payments z kolumną status tego nie odzwierciedla.

Po drugie, działają w wielu jurysdykcjach podatkowych. Marketplace z UE posiadający sprzedawców na Litwie, w Niemczech i w Polsce oraz kupujących w całym bloku musi zastosować prawidłowe traktowanie podatkowe dla każdej transakcji, zweryfikować numery VAT sprzedawców w systemie VIES i sporządzić deklaracje spełniające wymogi każdego lokalnego urzędu. Poprawne odwzorowanie tego w kodzie aplikacji, a następnie uzgodnienie z osobnym systemem księgowym, to moment, w którym większość marketplace'ów po cichu się potyka.

Po trzecie, wolumen transakcji uniemożliwia ręczną księgowość. Platforma obsługująca dziesięć tysięcy zamówień miesięcznie generuje dziesiątki tysięcy wpisów dziennika. Proces ten musi być w pełni zautomatyzowany, w przeciwnym razie dział finansów stanie się wąskim gardłem wzrostu.

Jak działa API krok po kroku

Mechanika jest mniej skomplikowana, niż się wydaje. Typowy przepłyv dla zamówienia na marketplace wygląda następująco:

1. Twoja platforma generuje zdarzenie finansowe. Kupujący finalizuje zakup. Twój backend wywołuje API księgi, przesyłając m.in.: identyfikator zamówienia, kupującego, sprzedawcę, kwotę brutto, stawkę VAT, prowizję platformy, walutę oraz klucz idempotencji (idempotency key).

2. Księga tworzy wpis w dzienniku. API tłumaczy to zdarzenie na obciążenia i uznania. W przypadku prostej sprzedaży na marketplace może to oznaczać obciążenie konta środków w drodze (cash-in-transit), uznanie konta zobowiązań wobec sprzedawcy na kwotę netto, uznanie konta przychodów platformy na kwotę prowizji oraz uznanie konta VAT należnego na kwotę podatku. Wszystko jest zbilansowane i zaksięgowane atomowo.

3. Wpis jest zapisywany w sposób niezmienny. Po zaksięgowaniu wpis otrzymuje identyfikator oraz znacznik czasu i nie może być edytowany. Jeśli coś jest nie tak, księguje się zapis odwracający oraz zapis skorygowany. Chodzi o zachowanie pełnego ścieżki audytu (audit trail).

4. Raporty podrzędne aktualizują się w czasie rzeczywistym. Zestawienie obrotów i sald, salda zobowiązań wobec sprzedawców, podsumowania VAT oraz rachunek zysków i strat (P&L) odzwierciedlają nowy wpis natychmiast. Nie ma tu zadań uruchamianych w nocy, eksportów ani okienek uzgadniania, w których liczby „się układają”.

5. Webhooki powiadamiają Twój system. Zdarzenia takie jak sale_invoice.paid lub bank_transaction.matched trafiają do Twoich endpointów, dzięki czemu produkt może reagować bez odpytywania (pollingu). W połączeniu z kluczami idempotencji oznacza to, że ponowienia są bezpieczne, a duplikaty nie przedostaną się w przypadku problemów z siecią.

Ważny punkt projektowy: księga jest źródłem prawdy o tym, co wydarzyło się pod względem finansowym. Baza danych Twojej aplikacji jest źródłem prawdy o stanie produktu. Oba systemy są ze sobą zgodne, ponieważ księga jest zasilana ze zdarzeń aplikacji, a nie odwrotnie.

Plan kont to miejsce, gdzie zapadają najważniejsze decyzje projektowe

Większość pracy intelektualnej przy konfiguracji księgi dla marketplace'u dotyczy planu kont. Jest to lista nazwanych kont, na które trafiają debety i kredyty: konta środków pieniężnych w podziale na banki, konta zobowiązań wobec sprzedawców (często jedno na sprzedawcę lub jedno zbiorcze z księgami pomocniczymi), przychody platformy według kategorii, VAT należny w podziale na kraje, rezerwy na zwroty, rezerwy na obciążenia zwrotne (chargebacks) i tak dalej.

Oto kilka powtarzających się wzorców w marketplace'ach:

• Środki sprzedawców to zobowiązanie, a nie przychód. Pieniądze, które przechowujesz w imieniu sprzedawców, są zobowiązaniem. Traktowanie ich jako przychodu i "wrzucanie w koszty" późniejszej wypłaty to klasyczny błąd wykrywany podczas audytów due diligence.
• VAT to osobne zobowiązanie w każdym kraju. Jeśli działasz w wielu jurysdykcjach UE, potrzebujesz osobnych kont VAT należnego dla każdego kraju, aby deklaracje podatkowe pasowały bez problemu.
• Prowizje muszą być ujmowane w momencie ich zarobienia, a nie w momencie wypłaty. Księgowość memoriałowa (accrual accounting) nie jest tutaj opcją do wyboru.
• Zwroty, chargebacki i spory wymagają własnych kont, aby rachunek zysków i strat odzwierciedlał rzeczywistość, a nie fluktuację pozytywnej i negatywnej sprzedaży.

Dobre API księgi pozwala zdefiniować tę strukturę raz, a następnie bez obaw dokonywać na niej wpisów, zamiast wymyślać logikę księgową na nowo w kodzie koszyka zakupowego.

Niezmienność, blokowanie okresów i dlaczego audytorzy zwracają na to uwagę

Niezmienność brzmi jak detal techniczny baz danych. W rzeczywistości to różnica między księgami, pod którymi audytor się podpisze, a takimi, pod którymi tego nie zrobi.

Jeśli marketplace może po cichu edytować zapisy z poprzedniego kwartału, to liczby z poprzedniego kwartału stają się z księgowego punktu widzenia niepoznawalne. Niezmienna księga egzekuje zasadę, że historia jest historią. Korekty są widoczne jako korekty. Blokowanie okresów (period locking) rozszerza tę zasadę: po zamknięciu miesiąca żadne nowe wpisy ani edycje nie mogą trafić do tego okresu bez jawnej akcji ponownego otwarcia, która sama w sobie jest rejestrowana w dzienniku zdarzeń.

Dla platform, które w przyszłości będą pozyskiwać finansowanie, sprzedawać biznes lub mierzyć się z kontrolą skarbową, nie jest to miły dodatek. To element, dzięki któremu księgi stają się obronne. Księga Nordlet została zaprojektowana z myślą o tym domyślnie, z wbudowaną strukturą niezmiennego podwójnego zapisu i blokowaniem okresów, a nie doklejonym z boku.

Unijny VAT: obszar pożerający czas programistów

VAT to obszar, na którym większość projektów księgowych dla marketplace'ów przekracza budżet. Zasady to nie tylko "zastosuj odpowiedni procent". Zależą one od tego, gdzie znajduje się kupujący, gdzie sprzedawca, co jest sprzedawane, czy sprzedawca jest zarejestrowany do VAT, czy platforma uznawana jest za dostawcę (deemed supplier) zgodnie z unijnymi przepisami e-commerce z 2021 roku oraz jaki reżim sprawozdawczy obowiązuje lokalnie.

Poważne API księgi dla UE obsługuje co najmniej:

• Walidację w systemie VIES numerów VAT sprzedawców i kupujących, najlepiej z wynikami buforowanymi i oznaczonymi znacznikiem na transakcji
• Logikę stawek VAT w podziale na kraje, w tym stawki obniżone i zwolnienia
• Generowanie rejestru i.SAF dla litewskich deklaracji oraz równoważne strukturalne pliki tam, gdzie inne państwa członkowskie tego wymagają
• E-fakturowanie Peppol BIS 3.0 dla jurysdykcji przechodzących na obowiązkowe faktury elektroniczne
• Obsługę procedur OSS i IOSS dla transakcji transgranicznych B2C

Robienie tego w kodzie aplikacji dla każdego kraju to praca dla całego zespołu inżynierskiego, która nigdy się nie kończy, ponieważ przepisy stale się zmieniają. Przeniesienie tego do warstwy księgi to pragmatyczny wybór.

Uzgadnianie danych, czyli gdzie widać oszczędność czasu

Kiedy księga staje się źródłem prawdy, uzgadnianie wyciągów bankowych przestaje być comiesięczną drogą przez mękę. Wyciągi bankowe przychodzą, księga już wie, co powinno się w nich znajdować, a dopasowywanie w dużej mierze odbywa się automatycznie.

Realistyczne podejście nie oznacza „zero pracy ręcznej”. Oznacza ono „wykrywanie wyjątków”. Proces uzgadniania za pomocą jednego kliknięcia dla dziewiędziestu procent transakcji pasujących bezbłędnie oraz kolejka dziesięciu procent wymagających decyzji człowieka to mniej więcej to, co zapewnia dobrze zaprojektowane API uzgadniania. Inteligentne dopasowywanie płatności obsługuje płatności częściowe, nadpłaty oraz wpłaty pokrywające wiele faktur bez konieczności pisania reguł przez człowieka dla każdego przypadku.

Eksport SEPA (w formacie pain.001) dla wypłat dla dostawców i sprzedawców domyka pętlę po stronie wychodzącej. Zatwierdzasz wypłaty w swoim produkcie, księga generuje plik SEPA, bank go przetwarza, a wynikowy ruch jest automatycznie uzgadniany wstecz.

Zbudować, kupić czy wbudować

Zespoły tworzące marketplace'y zazwyczaj rozważają trzy ścieżki. Oto jak wypadają w zestawieniu według kluczowych kryteriów.

Podejście	Czas wdrożenia	Gotowość do audytu	Obsługa unijnego VAT	Zintegrowanie z produktem
Zbudowanie własnej księgi	Od 12 do 24+ miesięcy	Zależy całkowicie od zespołu	Budujesz samodzielnie, kraj po kraju	Tak
Synchronizacja z Xero/QuickBooks	Kilka tygodni	Dobra od strony księgowej, słaba dla specyfiki marketplace'ów	Częściowa, wymagane dodatki	Nie, działa w osobnym narzędziu
Wbudowanie API księgi (np. Nordlet)	Kilka tygodni	Wbudowane dzięki niezmiennej księdze i blokowaniu okresów	Wbudowane dla UE, w tym VIES i i.SAF	Tak, przez API i pakiety SDK

Budowanie własnego rozwiązania ma uzasadnienie, jeśli księgowość jest Twoim produktem głównym. Dla wszystkich pozostałych rachunek ekonomiczny rzadko się spina. Synchronizacja z tradycyjnym narzędziem księgowym sprawdza się w biznesach jednoosobowych, ale pęka pod napływem specyfiki marketplace'ów: płatności podzielonych, sub-księg kont sprzedawców, stawek VAT per kraj oraz scenariuszy platformy jako domniemanego dostawcy (deemed supplier).

Wbudowanie księgi opartej na API to kierunek, w którym zmierza większość nowoczesnych platform. Księgi żyją wewnątrz interfejsu Twojego produktu, sprzedawcy widzą własne finanse w Twoim UI, a uciążliwa część związana z compliance jest obsługiwana na poziomie infrastruktury.

Na co zwrócić uwagę przy ocenie API księgi

Krótka lista kontrolna, którą warto mieć pod ręką podczas rozmów z dostawcami:

• Niezmienne magazynowanie podwójnego zapisu z korektami w formie zapisów odwracających, a nie edytowalnych wierszy
• Blokowanie okresów z rejestrowanymi działaniami ponownego otwarcia
• Klucze idempotencji dla każdego punktu końcowego zapisu
• Webhooki dla zdarzeń, na które Twój produkt musi reagować, a nie tylko interfejs API oparty na odpytywaniu
• Wtyczki SDK o silnym typowaniu w językach faktycznie używanych przez Twój zespół
• Logika VAT w podziale na kraje, obejmująca VIES, i.SAF lub ich odpowiedniki oraz OSS i IOSS
• Obsługa wielu podmiotów (multi-company), jeśli prowadzisz lub planujesz prowadzić działalność w ramach wielu spółek
• Kontrola dostępu oparta na rolach (RBAC) na tyle szczegółowa, aby oddzielić programistów, księgowych i osoby z dostępem do podglądu
• Eksport raportów w formatach XLSX, PDF i JSON, wraz z powiadomieniami webhook po przygotowaniu dużych raportów
• Środowisko piaskownicy (sandbox) odzwierciedlające zachowanie produkcji, a nie okrojoną wersję demo

Jeśli dostawca nie potrafi zademonstrować pierwszych trzech punktów podczas rozmowy technicznej, reszta nie ma znaczenia.

Od czego zacząć w pierwszej kolejności

Jeśli marketplace zaczyna te prace od zera, sekwencja kroków oszczędzająca najwięcej problemów wygląda następująco:

1. Zamapuj rzeczywiste przepływy pieniężne na tablicy przed napisaniem jakiegokolwiek kodu. Kto jest komu winien, w jakim momencie, w jakiej walucie i z jakim traktowaniem VAT.
2. Przygotuj plan kont na podstawie tej mapy. Zobowiązania wobec sprzedawców, przychody platformy, VAT należny w podziale na kraje, rezerwy. Poproś księgowego o przegląd przed wdrożeniem na produkcję.
3. Wybierz warstwę księgi: zbuduj, zsynchronizuj lub wbuduj. Bądź szczerze krytyczny wobec tego, co Twój zespół faktycznie zdoła dostarczyć i utrzymać.
4. Zaimplementuj jeden pełny proces od końca do końca: od zamówienia, przez fakturę i wypłatę, aż po uzgodnienie. Udowodnij, że się bilansuje. Następnie skaluj.
5. Włącz blokowanie okresów natychmiast po zamknięciu pierwszego miesiąca bez błędów. Ta dyscyplina procentuje z czasem.

Zespoły, które robią to właściwie, traktują księgę jako infrastrukturę rdzeniową, a nie dodatek sprawozdawczy. To właśnie ta zmiana sprawia, że rozmowa finansowa z audytorem, inwestorem lub organem podatkowym trwa krótko, zamiast ciągnąć się w nieskończoność.

FAQ

Czy API księgi podwójnego zapisu to to samo co integracja księgowa?

Nie. Integracja synchronizuje dane z Twojego produktu do zewnętrznego narzędzia księgowego, zazwyczaj z opóźnieniem. API księgi to sam system księgowy, do którego zapisuje się bezpośrednio i w czasie rzeczywistym. Ta różnica ma znaczenie, ponieważ integracje tracą dokładność na obrzeżach: przy płatnościach częściowych, obsłudze wielu walut czy podziałach na marketplace. API księgi rejestruje je natywnie.

Czy nie możemy po prostu użyć raportów od Stripe lub Adyen?

Raporty procesorów płatności pokazują to, co przeszło przez dany procesor. To nie są księgi podwójnego zapisu. Nie wiedzą nic o Twoich zobowiązaniach wobec sprzedawców, które nie zostały jeszcze wypłacone, o zobowiązaniach z tytułu VAT w poszczególnych krajach ani o wydatkach spoza procesora płatności. Są jednym z wielu dań wejściowych do księgi, a nie jej zamiennikiem.

Jak bardzo niezmienna jest niezmienność w praktyce?

Wpisów nie można edytować. Korekty to nowe wpisy odwołujące się do oryginału. To decyzja projektowa, a nie technologiczna. Każda kompetentna księga to wymusi. Powodem, dla którego warto na to zwracać uwagę, jest to, że podejście „edytowaliśmy to, żeby pasowało do banku” stanowi dokładnie ten wzorzec, który czyni księgi niewiarygodnymi.

A co z marketplace'ami spoza UE?

Mechanika podwójnego zapisu jest uniwersalna, ale logika podatkowa już nie. API księgi dostrojone do unijnego VAT-u poradzi sobie dobrze z operacjami mocno osadzonymi w UE i może obsługiwać transakcje spoza niej, jednak jeśli Twoim głównym rynkiem jest amerykański podatek od sprzedaży (sales tax) lub latynoamerykańskie reżimy e-faktur, zweryfikuj konkretne pokrycie przepisów przed podjęciem decyzji.

Jak długo trwa wdrożenie w praktyce?

W przypadku marketplace'u z czystym modelem zdarzeń wbudowanie API księgi do momentu uruchomienia jednego pełnego przepływu zajmuje zazwyczaj kilka tygodni prac inżynieryjnych. Pełna migracja z przestarzałej konfiguracji, uwzględniająca dane historyczne, trwa dłużej. Zmienną jest tu niemal zawsze stan dotychczasowych danych, a nie samo API.