Što je računovodstveno API sučelje? Vodič za graditelje platformi bez stručnog žargona
Definicija računovodstvenog API sučelja prilagođena svima, razlike u odnosu na porezna ili platna API sučelja te provjere koje trebate obaviti prije integracije.
Računovodstveno API sučelje (API) je sučelje koje omogućuje jednom programu da vodi poslovne knjige drugog programa. Vaš softver šalje financijski događaj putem protokola HTTP. API pretvara taj događaj u uravnotežena dvojna knjiženja (double-entry journal entries) prema kontnom planu (chart of accounts), sprema ih tako da se ne mogu neprimjetno mijenjati, primjenjuje porezni tretman te vam putem istog sučelja vraća izvještaje, dokumente i izvoze.
Ta definicija obavlja veći dio posla. Sve ostalo u ovom članku posljedica je nje.
Verzija u jednoj rečenici
Računovodstveno API sučelje prihvaća financijske događaje iz vaše aplikacije, pretvara svaki od njih u uravnoteženo knjiženje, sprema ga na nepromjenjiv način (immutably) zajedno s poreznim tretmanom i pratećom dokumentacijom te izlaže nastalu glavnu knjigu (ledger), dokumente i izvještaje kao programabilne krajnje točke (endpoints).
Ako se neki proizvod naziva računovodstvenim API-jem, a ne stvara knjiženja, to je nešto sasvim drugo s privlačnim nazivom. To nije nužno loše, već samo znači da neće obaviti onaj posao koji od njega namjeravate zatražiti.
Što računovodstveno API sučelje nije
Četiri srodne kategorije proizvoda često se miješaju s računovodstvenim API sučeljima, obično u kasnijim fazama projekta.
| Kategorija | Što radi | Što ne radi |
|---|---|---|
| API sučelje za obračun poreza | Vraća ispravnu stopu ili iznos poreza za transakciju | Ne vodi vaše poslovne knjige niti čuva dokaze koji stoje iza odluke tijekom propisanog razdoblja čuvanja |
| API sučelje za plaćanja | Prijenos novca između strana i izvještavanje o tim kretanjima | Ne bilježi zarađenu proviziju, dugovani PDV niti obvezu prema prodavatelju između uplate i isplate |
| Ujedinjeno ili agregacijsko API sučelje | Čita i piše podatke u postojećem računovodstvenom softveru vašeg klijenta | Ne služi kao sustav zapisa (system of record); vaše knjige se nalaze u alatu koji pojedini klijent već koristi |
| Izvještajno ili BI API sučelje | Čita brojke iz postojeće glavne knjige i vizualizira ih | Ne stvara knjiženja iz kojih se te brojke izvode |
Svaka od tih kategorija ima stvarnu primjenu. Platforma koja mora biti sustav zapisa treba računovodstveno API sučelje kao temelj, a ne kao zamjenu.
Pet stvari koje računovodstveno API sučelje mora činiti
1. Bilježiti uravnotežena knjiženja. Svaki se događaj pretvara u dugovne i potražne stavke čiji je zbroj jednak. Kada kupac plati 100 EUR na marketplaceu (marketplace) koji uzima proviziju od 15 EUR, knjiženje zadužuje prijelazni konto za 100 EUR, odobrava obvezu prema dobavljaču za 85 EUR i odobrava prihod od provizije za 15 EUR. To nije administrativni ritual, već strukturalna provjera koja hvata cijele klase pogrešaka u integraciji prije nego što dospiju u izvještaj.
2. Čuvati povijest. Proknjižena stavka se ne uređuje. Pogreška se ispravlja stornom i ispravnim knjiženjem, pri čemu su oba povezana s izvornim zapisom. Zaključeni mjeseci se zaključavaju kako se u njih ne bi mogli unositi novi datumi.
3. Rješavati poreze. U trgovini unutar EU-a to znači utvrđivanje mjesta oporezivanja, prijenos porezne obveze (reverse charge), provjeru PDV ID brojeva (VAT identification numbers) u službenom registru te spremanje dokaza koji opravdavaju odluku uz samu transakciju umjesto njihova brisanja nakon obračuna.
4. Usklađivati s novčanim tokovima. Poslovne knjige koje se nikada ne uspoređuju s bankovnim izvodom puko su nagađanje. API mora preuzimati izvode ili isplate pružatelja usluga i usklađivati ih s evidentiranim podacima.
5. Omogućiti izvoz. Izvještaji, dokumenti i revizijske datoteke u formatima koje prihvaćaju ovlašteni računovođa i porezna uprava.
Proizvod koji obavlja prve tri stavke, ali ne i posljednje dvije, i dalje će primorati neku osobu da svakog mjeseca ručno radi u tablicama.
Kako poziv zapravo izgleda
Mehanika je jednostavnija od samog računovodstva. U Nordletovom API sučelju svaka je operacija zahtjev POST u stilu RPC-a predvidljivog oblika:
POST /v1/{module}/{resource}/{action}
Authorization: Bearer <api key>
Idempotency-Key: <your event id>
Izrađujete izlazni račun, a zatim ga izdajete. Izdavanje je trenutak u kojem se odvija knjiženje: dokument dobiva svoj broj bez preskoka (gapless number), provodi se uravnoteženo knjiženje, a stavke PDV-a bilježe se zajedno s njim. Vaša platforma nikada ručno ne sastavlja dugovanja i potraživanja.
Tri detalja u tom odsječku koda važnija su od samog naziva krajnje točke:
- Dopuštenja (scope) ključa. Ključ nosi dozvole poput
sales:write, tako da integracija dobiva samo onaj pristup koji joj je potreban. - Ključ idempotencije (idempotency key). Ponovite li isti zahtjev s istim podatcima, primit ćete spremljeni odgovor umjesto drugog računa. Pošaljete li isti ključ s drukčijim podatcima, zahtjev će biti odbijen s pogreškom
idempotency_key_reuseumjesto da bude tiho prihvaćen. - Novac kao nizovi znakova (strings). Iznosi su decimalni nizovi, a ne brojevi s pomičnim zarezom (floats), jer brojevi s pomičnim zarezom gube cente na načine koji postaju vidljivi na kraju godine.
Gdje se nalazi u vašoj arhitekturi
Vaša aplikacija ostaje sučelje i izvor poslovnih događaja. Računovodstveno API sučelje postaje financijski sustav zapisa u pozadini. Tijek obično izgleda ovako:
- Nešto se događa u vašem proizvodu: narudžba, povrat sredstava, isplata ili obnova pretplate.
- Vaša pozadina (backend) poziva računovodstveno API sučelje s događajem i ključem idempotencije.
- API knjiži stavku, primjenjuje PDV i vraća identifikatore koje spremate uz vlastite zapise.
- Webhook poput
sale_invoice.paidobavještava vaš sustav o promjeni stanja, pa reagirate na događaje umjesto da stalno provjeravate statuse (polling). - Bankovne transakcije pristižu putem bankovnog izvoda ili uvoza datoteke te se usklađuju s evidentiranim dokumentima.
- Na kraju razdoblja izvještaji i porezni registri generiraju se iz istih podataka, a zaključeni mjesec se zaključava.
Ništa s tog popisa ne zahtijeva da čovjek otvara računovodstvenu aplikaciju. U tome i jest svrha ove kategorije.
Usporedba s alternativama
| Pristup | Napor za početak | Položaj u reviziji | Skaliranje s obujmom transakcija |
|---|---|---|---|
| Tablice i ručni unos | Najniži | Slab; povijest je promjenjiva | Ne |
| Računovodstveni program plus izvoz u CSV | Nizak | Ovisi isključivo o disciplini | Slabo; netko mora uvoziti datoteke |
| Agregacijsko API sučelje u knjigama svakog klijenta | Srednji | Nasljeđuje ono što alat klijenta omogućuje | Da, ali vi nikada ne posjedujete zapis |
| Ugrađeno računovodstveno API sučelje (Embedded accounting API) | Srednji | Snažan ako je glavna knjiga nepromjenjiva i razdoblja se zaključavaju | Da |
| Izgradnja vlastite glavne knjige | Najviši | Snažan samo ako izgradite i kontrole | Da, uz održavanje do kraja vijeka |
Izgradnja vlastitog rješenja opravdan je izbor za neke timove. Više detalja o tome potražite u našem vodiču o odabiru između vlastitog razvoja i kupnje za marketplaceove.
Što provjeriti prije integracije
- Je li saldo izveden ili spremljen? Upitajte je li saldo dobavljača upit nad retcima knjiženja ili stupac koji netko ažurira. Samo jedno od toga preživljava reviziju.
- Što se događa kod ponovljenog zahtjeva (retry)? Pošaljite isti zahtjev dva puta i prebrojite knjiženja.
- Možete li urediti proknjiženu stavku? Odgovor treba biti negativan, uz dokumentirani postupak ispravka.
- Odbija li zaključeno razdoblje unos knjiženja? Isprobajte to u okruženju za testiranje (sandbox). Nordlet vraća kod
409za knjiženja čiji je datum unutar zaključenog razdoblja. - Kako se prikazuje novac? Decimalni nizovi ili cijeli brojevi najmanjih novčanih jedinica. Nikada brojevi s pomičnim zarezom.
- Što sadrži zapis revizije (audit record)? Akter, radnja, entitet i sama promjena, pri čemu je sve dostupno putem upita, a nije zakopano u datotekama dnevnika (log files).
- Koja su ograničenja broja zahtjeva (rate limits)? Nordlet dopušta 300 zahtjeva u minuti po API ključu i izvještava o preostalome budjetu u zaglavljima odgovora. Bez obzira na broj, provjerite ga prije projektiranja sinkronizacije.
- Kako izvući podatke van? Izvještaji, dokumenti i dnevnici u formatima koje možete predati računovođi.
Svaka se od ovih stavki može testirati u jednom popodnevu korištenjem testne tvrtke. Popisi značajki prodavača nisu dokaz; ponovljiv test jest.
FAQ
Je li računovodstveno API sučelje isto što i računovodstveni softver?
To je računovodstveni softver s premještenim sučeljem. Tradicionalni računovodstveni softver stavlja čovjeka pred glavnu knjigu, dok računovodstveno API sučelje ondje stavlja vaš kod. Temeljne obveze, struktura dvojnog knjigovodstva i izvještaji ostaju isti.
Trebam li i dalje računovođu ako koristim API?
Da. API automatizira knjiženje, izračun i izvještavanje. On ne donosi stručne procjene o klasifikaciji, rezerviranjima ili načinu na koji treba tretirati određeni ugovor, a u većini zemalja ne može potpisati ni predati vaša zakonska financijska izvješća.
Mogu li koristiti računovodstveno API sučelje bez poznavanja dvojnog knjigovodstva?
Djelomično. Dobar API automatski sastavlja knjiženja za vas iz poslovnog dokumenta kao što je račun. Ipak, morate razumjeti što ti konti znače kada čitate izvještaj ili objašnjavate saldo revizoru.
Koja je razlika između računovodstvenog API sučelja i API sučelja za glavnu knjigu (ledger API)?
API glavne knjige bilježi uravnotežena kretanja između konta. Računovodstveno API sučelje čini isto, ali dodaje zakonski sloj na vrhu: dokumente sa zakonskim numeriranjem, porezni tretman, porezne registre, dugotrajnu imovinu, zaključivanje razdoblja i izvještaje koje nadležna tijela zahtijevaju. Svako računovodstveno API sučelje sadrži glavnu knjigu, ali svaka glavna knjiga nije i računovodstveni sustav.
Koliko traje integracija?
Za prvi radni tijek – izrada klijenta, izdavanje računa, zaprimanje uplate i pregled knjiženja – uz tipizirani SDK (software development kit) i testno okruženje planirajte dane umjesto tjedana. Produkcijska integracija koja obuhvaća povrate sredstava, ispravke, viševalutnost, usklađivanje i zaključivanje razdoblja složeniji je zadatak, a iskrena procjena ovisi o tome koliko takvih slučajeva vaš proizvod doista generira.