Czym jest API księgowe? Przewodnik językiem nietechnicznym dla twórców platform

Przystępna definicja API księgowego, różnice między API podatkowym a płatniczym oraz kwestie, które warto sprawdzić przed rozpoczęciem integracji.

API księgowe to interfejs, który pozwala jednemu programowi prowadzić księgi innego programu. Twoje oprogramowanie wysyła zdarzenie finansowe przez protokół HTTP. API przekształca to zdarzenie w zbilansowane zapisy podwójnego księgowania na kontach z planu kont, zapisuje je w sposób uniemożliwiający cichą modyfikację, uwzględnia odpowiednie stawki podatkowe, a następnie udostępnia raporty, dokumenty i eksporty przez ten sam interfejs.

Ta definicja wyjaśnia większość kwestii. Wszystko inne w tym artykule jest jej bezpośrednią konsekwencją.

Wersja w jednym zdaniu

API księgowe przyjmuje zdarzenia finansowe z Twojej aplikacji, przekształca każde z nich w zbilansowany zapis księgowy, przechowuje je w sposób niezmienny wraz z rozliczeniem podatkowym i dokumentacją źródłową oraz udostępnia powstałą księgę, dokumenty i raporty w postaci programowalnych punktów końcowych (endpoints).

Jeśli jakiś produkt nazywa się API księgowym, ale nie generuje zapisów księgowych, to znaczy, że jest czymś innym o chwytliwej nazwie. Nie musi to być zła wiadomość, ale oznacza, że produkt ten nie wykona zadania, przed którym go postawisz.

Czym API księgowe nie jest

Cztery pokrewne kategorie produktów bywają mylone z API księgowymi, co zwykle wychodzi na jaw na późniejszym etapie projektu.

Kategoria	Co robi	Czego nie robi
API do obliczania podatków	Zwraca odpowiednią stawkę lub kwotę podatku dla transakcji	Nie prowadzi ksiąg ani nie przechowuje dokumentacji źródłowej przez wymagany okres archiwizacji
API płatnicze	Przelewa środki między stronami i raportuje te przepływy	Nie rejestruje prowizji, należnego podatku VAT ani zobowiązania wobec sprzedawcy w okresie między płatnością a wypłatą
Zunifikowane API lub agregator	Odczytuje i zapisuje dane w istniejącym oprogramowaniu księgowym klienta	Nie pełni roli systemu źródłowego (system of record); Twoje księgi znajdują się w narzędziu, z którego już korzysta dany klient
API raportowe lub BI	Odczytuje dane z istniejącej księgi i wizualizuje je	Nie tworzy wpisów, na podstawie których wyliczono te dane

Każde z tych rozwiązań ma swoje zastosowanie. Jednak platforma, która musi pełnić funkcję systemu źródłowego, potrzebuje API księgowego jako fundamentu, a nie jako zamiennika.

Pięć zadań, które API księgowe musi realizować

1. Rejestrować zbilansowane zapisy. Każde zdarzenie przekłada się na strony Winien (debit) i Ma (credit), których sumy muszą być sobie równe. Kiedy kupujący płaci 100 EUR na marketplace pobierającym 15 EUR prowizji, wpis obciąża konto rozrachunkowe kwotą 100 EUR, uznaje konto zobowiązań wobec sprzedawcy na kwotę 85 EUR oraz uznaje przychody z prowizji na kwotę 15 EUR. To nie jest czysta biurokracja księgowa, lecz strukturalny mechanizm kontrolny, który wychwytuje całe kategorie błędów integracji, zanim zdążą wpłynąć na raporty.

2. Zachowywać historię. Zatwierdzony wpis nie podlega edycji. Pomyłkę naprawia się za pomocą wpisu korygującego (reversing entry) oraz nowego, poprawnego wpisu, przy czym oba są powiązane z oryginałem. Zamknięte miesiące są blokowane, aby nie można było przypisać do nich żadnych nowych datowanych operacji.

3. Rozliczać podatki. W handlu wewnątrz UE oznacza to ustalenie miejsca świadczenia (place of supply), procedury odwrotnego obciążenia (reverse charge), weryfikację numerów VAT w systemie VIES oraz przechowywanie dowodów uzasadniających daną decyzję bezpośrednio przy transakcji, zamiast usuwania ich po zakończeniu obliczeń.

4. Uzgadniać dane z zewnętrznymi przepływami pieniężnymi. Księgi, które nigdy nie spotykają się z wyciągiem bankowym, są jedynie domysłem. API musi pobierać wyciągi lub rozliczenia od operatorów płatności i dopasowywać je do zarejestrowanych dokumentów.

5. Generować eksporty. Raporty, dokumenty i pliki kontrolne w formatach akceptowanych przez księgowych oraz organy podatkowe.

Produkt, który realizuje pierwsze trzy punkty, ale pomija dwa ostatnie, sprawi, że ktoś nadal będzie musiał co miesiąc ręcznie pracować w arkuszach kalkulacyjnych.

Jak wygląda wywołanie w praktyce

Mechanika jest prostsza niż sama księgowość. W API Nordlet każda operacja to żądanie POST w stylu RPC o przewidywalnej strukturze:

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

Tworzysz fakturę sprzedaży, a następnie ją wystawiasz. Wystawienie to moment, w którym zachodzi proces księgowania: dokument otrzymuje numer z zachowaniem ciągłości (gapless number), powstaje zbilansowany zapis księgowy, a wraz z nim rejestrowane są pozycje podatku VAT. Twoja platforma nigdy nie musi ręcznie dopasowywać stron Winien i Ma.

Trzy szczegóły w tym fragmencie kodu są ważniejsze niż nazwa samego punktu końcowego:

Zakres uprawnień klucza (scope). Klucz posiada uprawnienia takie jak sales:write, dzięki czemu integracja uzyskuje wyłącznie niezbędny dostęp.
Klucz idempotencji (idempotency key). Ponowienie tego samego żądania z tym samym ładunkiem danych zwraca zapisaną odpowiedź zamiast tworzyć drugą fakturę. Wysłanie tego samego klucza z innym ładunkiem skutkuje odrzuceniem żądania z błędem idempotency_key_reuse zamiast jego cichej akceptacji.
Pieniądze jako ciągi tekstowe (strings). Kwoty są reprezentowane jako dziesiętne łańcuchy znaków, a nie liczby zmiennoprzecinkowe, ponieważ zmiennoprzecinkowość prowadzi do gubienia groszy, co ujawnia się przy rozliczeniu rocznym.

Miejsce w architekturze systemu

Twoja aplikacja pozostaje interfejsem użytkownika oraz źródłem zdarzeń biznesowych. API księgowe staje się stojącym za nią finansowym systemem źródłowym. Typowy przepływ wygląda następująco:

W produkcie dochodzi do zdarzenia: zamówienia, zwrotu, wypłaty lub odnowienia subskrypcji.
Twój backend wywołuje API księgowe, przesyłając zdarzenie oraz klucz idempotencji.
API tworzy zapis księgowy, nalicza podatek VAT i zwraca identyfikator, który zapisujesz we własnej bazie danych.
Webhook, taki jak sale_invoice.paid, informuje Twój system o zmianie stanu, dzięki czemu reagujesz na zdarzenia zamiast odpytywać system (polling).
Transakcje bankowe trafiają do systemu poprzez integrację bankową (bank feed) lub import wyciągów i są dopasowywane do zarejestrowanych dokumentów.
Na koniec okresu rozliczeniowego z tych samych danych generowane są raporty i rejestry podatkowe, a zamknięty miesiąc zostaje zablokowany.

Żaden z tych kroków nie wymaga, aby człowiek otwierał program księgowy. Na tym polega sens tej kategorii produktów.

Porównanie z alternatywnymi rozwiązaniami

Podejście	Nakład pracy na start	Wiarygodność audytowa	Skalowalność wraz z wolumenem transakcji
Arkusze kalkulacyjne i wprowadzanie ręczne	Najniższa	Niska; historię można edytować	Nie
Program księgowy i eksporty CSV	Niski	Zależy wyłącznie od skrupulatności zespołu	Słaba; ktoś musi importować pliki
Agregator API łączący się z księgami każdego klienta	Średni	Zależny od możliwości narzędzia klienta	Tak, ale nie jesteś właścicielem danych księgowych
Wbudowane API księgowe (embedded accounting)	Średni	Wysoka, jeśli księga jest niezmienna, a okresy blokowane	Tak
Zbudowanie własnej księgi od zera	Najwyższa	Wysoka tylko wtedy, gdy zbudujesz też mechanizmy kontrolne	Tak, ale utrzymujesz ją na własny koszt już zawsze

Samodzielne budowanie systemu to dla niektórych zespołów racjonalny wybór. Szerzej omawiamy to w naszym przewodniku po wyborze strategii budować czy kupować dla marketplace'ów.

Co sprawdzić przed rozpoczęciem integracji z API

Czy saldo jest wyliczane dynamicznie, czy przechowywane na stałe? Dowiedz się, czy saldo sprzedawcy to wynik zapytania SQL do linii księgowych, czy kolumna, którą ktoś aktualizuje. Tylko jedno z tych rozwiązań przetrwa audyt.
Co się dzieje w przypadku ponowienia żądania (retry)? Wyślij to samo żądanie dwukrotnie i policz utworzone wpisy.
Czy można edytować zatwierdzony zapis? Odpowiedź powinna brzmieć „nie”, z opisaną w dokumentacji ścieżką korekty.
Czy zablokowany okres rzeczywiście odrzuca nowe wpisy? Przetestuj to w środowisku piaskownicowym (sandbox). Nordlet zwraca kod 409 dla wpisów datowanych wewnątrz zablokowanego okresu.
W jaki sposób reprezentowane są kwoty pieniężne? Jako łańcuchy dziesiętne lub grosze jako liczby całkowite. Nigdy jako liczby zmiennoprzecinkowe.
Co zawiera rejestr audytu (audit record)? Informacje o użytkowniku lub procesie (actor), wykonanej akcji, obiekcie oraz samej zmianie, z możliwością łatwego przeszukiwania zamiast przekopywania się przez pliki dziennika (logs).
Jakie są limity zapytań (rate limits)? Nordlet pozwala na 300 zapytań na minutę dla jednego klucza API i informuje o pozostałym limicie w nagłówkach odpowiedzi. Niezależnie od dokładnej liczby, poznaj ją przed zaprojektowaniem mechanizmu synchronizacji.
Jak wyeksportować dane? W postaci raportów, dokumentów i dzienników w formacie, który możesz przekazać księgowemu.

Każdy z tych punktów można przetestować w jedno popołudnie w środowisku firmy testowej w sandboxie. Listy funkcji na stronach dostawców nie są dowodem; dowodem jest odtwarzalny test.

FAQ

Czy API księgowe to to samo co oprogramowanie księgowe?

To oprogramowanie księgowe, w którym zmieniono interfejs. Tradycyjne programy stawiają przed księgą człowieka, natomiast API księgowe stawia tam Twój kod. Podstawowe obowiązki, zasada podwójnego zapisu oraz raporty pozostają bez zmian.

Czy korzystając z API, nadal potrzebuję księgowego?

Tak. API automatyzuje rejestrację, obliczenia i raportowanie. Nie podejmuje ono jednak ocen merytorycznych dotyczących klasyfikacji kosztów, rezerw czy traktowania konkretnych umów, a w większości krajów nie podpisuje ani nie składa również deklaracji urzędowych.

Czy mogę korzystać z API księgowego bez znajomości podwójnego zapisu?

Częściowo. Dobre API tworzy zapisy księgowe w Twoim imieniu na podstawie dokumentu biznesowego, takiego jak faktura. Nadal musisz jednak rozumieć znaczenie poszczególnych kont, czytając raport lub wyjaśniając saldo audytorowi.

Jaka jest różnica między API księgowym a API księgi głównej (ledger API)?

API księgi głównej rejestruje zbilansowane przepływy między kontami. API księgowe robi dokładnie to samo, a ponadto dodaje warstwę regulowaną przepisami: dokumenty z numeracją prawnie wymaganą, obsługę podatku VAT, rejestry podatkowe, środki trwałe, zamknięcie okresu oraz raporty wymagane w danej jurysdykcji. Każde API księgowe zawiera w sobie księgę główną, ale nie każda księga główna jest systemem księgowym.

Jak długo trwa integracja?

W przypadku podstawowego scenariusza – utworzenia klienta, wystawienia faktury, przyjęcia płatności i wglądu w zapis księgowy – przy użyciu otypowanego zestawu SDK i środowiska sandbox mówimy o dniach, a nie tygodniach pracy. Pełna integracja produkcyjna uwzględniająca zwroty, korekty, obsługę wielu walut, uzgadnianie i zamknięcie okresu to bardziej złożone zadanie, a rzetelna szacunkowa wycena zależy od tego, ile z tych przypadków faktycznie generuje Twój produkt.