Čo je to účtovné API? Sprievodca pre tvorcov platforiem v zrozumiteľnej reči
Definícia účtovného API v zrozumiteľnej reči, rozdiel medzi daňovým alebo platobným API a body, ktoré si treba overiť pred integráciou.
Účtovné API je rozhranie, ktoré umožňuje jednomu programu viesť účtovníctvo iného programu. Váš softvér odošle finančnú udalosť cez HTTP. API túto udalosť premení na vyrovnané podvojné účtovné zápisy (journal entries) voči účtovej osnove, uloží ich tak, aby sa nedali ticho pozmeniť, aplikuje daňový režim a cez to isté rozhranie vám vráti výkazy, dokumenty a exporty.
Táto definícia vyjadruje podstatu veci. Všetko ostatné v tomto článku z nej iba vyplýva.
Verzia v jednej vete
Účtovné API prijíma finančné udalosti z vašej aplikácie, každú z nich konvertuje na vyrovnaný účtovný zápis, nemenne ju ukladá spolu s daňovým zaobchádzaním a sprievodnými dôkazmi a výslednú hlavnú knihu (ledger), dokumenty a výkazy sprístupňuje vo forme programovateľských koncových bodov (endpoints).
Ak sa nejaký produkt označuje ako účtovné API, ale nevytvára účtovné zápisy, ide o niečo iné s pekným názvom. To nemusí byť nutne zlé, len to znamená, že to neurobí prácu, o ktorú sa chystáte požiadať.
Čím účtovné API nie je
Štyri príbuzné kategórie produktov sa s účtovnými API často zamieňajú, zvyčajne v pokročilej fáze projektu.
| Kategória | Čo robí | Čo nerobí |
|---|---|---|
| API na výpočet daní | Vrací správnu sadzbu alebo výšku dane pre transakciu | Nevykonáva účtovníctvo ani neuchováva dôkazy o rozhodnutí počas zákonom stanovenej lebo ukladania |
| Platobné API | Presúva peniaze medzi stranami a vykazuje tieto pohyby | Nezaznamenáva zarobenú províziu, dlhovanú DPH ani záväzok voči predajcovi medzi platbou a vyplatením |
| Zjednocujúce alebo agregátorové API | Číta a zapisuje údaje v existujúcom účtovnom softvéri vášho zákazníka | Neslúži ako zdroj pravdivých dát (system of record); vaše účtovníctvo sídli v nástroji, ktorý už každý zákazník používa |
| Reportovacie alebo BI API | Číta čísla z existujúcej hlavnej knihy a vizualizuje ich | Nevytvára záznamy, z ktorých sú tieto čísla odvozené |
Každé z nich má reálne využitie. Platforma, ktorá potrebuje byť zdrojom pravdivých dát, však potrebuje účtovné API ako základ pod sebou, nie namiesto seba.
Päť úloh, ktoré účtovné API musí zvládnuť
1. Zaznamenávať vyrovnané zápisy. Každá udalosť sa premení na strany má dať a dal, ktorých súčet je rovnaký. Keď kupujúci zaplatí 100 € na trhovisku, ktoré si účtuje províziu 15 €, zápis zaúčtuje sumu 100 € na ťarchu zúčtovacieho účtu, 85 € v prospech záväzku voči predajcovi a 15 € v prospech výnosov z provízií. Nejde o účtovný rituál, ale o štruktúrovanú kontrolu, ktorá zachytí celé spektrum integračných chýb skôr, než sa dostanú do výkazu.
2. Uchovávať históriu. Zaúčtovaný záznam sa neupravuje. Chyba sa opraví stornom a opraveným záznamom, pričom oba sú prepojené s originálom. Uzatvorené mesiace sú zablokované, takže do nich nemožno datovať žiadne nové záznamy.
3. Riešiť dane. Pri obchode v rámci EÚ to znamená určenie miesta dodania, prenesenie daňovej povinnosti (reverse charge), overenie identifikačných čísel pre DPH v oficiálnom registri a uloženie dôkazov, ktoré odôvodňujú dané rozhodnutie, priamo pri transakcii namiesto ich vymazania po výpočte.
4. Vykonávať párovanie s vonkajšími peniazmi. Účtovníctvo, ktoré sa nikdy nestretne s bankovým výpisom, je len odhadom. API musí prijímať výpisy alebo vysporiadania od poskytovateľov a párovať ich so zaúčtovanými údajmi.
5. Poskytovať exporty. Výkazy, dokumenty a audítorské súbory vo formátoch, ktoré akceptuje ľudský účtovník aj daňový úrad.
Produkt, ktorý zvládne prvé tri body, ale nie posledné dva, stále necháva človeka robiť mesačnú prácu v tabuľkových procesoroch.
Ako vyzerá reálne volanie
Mechanika je jednoduchšia než samotné účtovníctvo. V API systému Nordlet je každá operácia požiadavkou typu RPC POST s predvídateľnou štruktúrou:
POST /v1/{module}/{resource}/{action}
Authorization: Bearer <api key>
Idempotency-Key: <your event id>
Vytvoríte predajnú faktúru a následne ju vystavíte. Vystavenie je okamihom, kedy dochádza k zaúčtovaniu: dokument dostane svoje číslo bez medzier v číselnom rade, zaúčtuje sa vyrovnaný účtovný zápis a spolu s ním sa zaznamenajú aj riadky DPH. Vaša platforma nikdy nemusí zostavovať strany má dať a dal manuálne.
V tejto ukážke sú tri detaily dôležitejšie než samotný názov koncového bodu:
- Rozsah oprávnení kľúča (scope). Kľúč nesie oprávnenia ako
sales:write, takže integrácia získava iba prístup, ktorý skutočne potrebuje. - Idempotentný kľúč. Ak odošlete tú istú požiadavku s rovnakým dátovým zaťažením (payload), dostanete uloženú odpoveď namiesto vytvorenia druhej faktúry. Ak odošlete rovnaký kľúč s iným zaťažením, požiadavka sa zamietne s chybou
idempotency_key_reusenamiesto tichého akceptovania. - Peniaze ako reťazce. Sumy sú desatinné reťazce, nie čísla s plávacou rádovou čiarkou (floats), pretože plávajúca rádová čiarka stráca centy spôsobom, ktorý sa prejaví pri uzávierke roka.
Umiestnenie v architektúre
Vaša aplikácia zostáva používateľským rozhraním a zdrojom obchodných udalostí. Účtovné API sa stáva finančným systémom záznamov, ktorý stojí v pozadí. Tok dát obvykle prebieha takto:
- Vo vašom produkte sa niečo stane: objednávka, vrátenie peňazí, výplata prostriedkov alebo obnovenie predplatného.
- Váš backend zavolá účtovné API s danou udalosťou a idempotentným kľúčom.
- API zaúčtuje účtovný zápis, uplatní DPH a vráti identifikátory, ktoré si uložíte k vlastným záznamom.
- Webhook, napríklad
sale_invoice.paid, informuje váš systém o zmene stavu, takže reagujete na udalosti namiesto ich neustáleho dopytovania (polling). - Bankové transakcie prichádzajú prostredníctvom bankového feedu alebo importu výpisu a sú párované so zaúčtovanými dokumentmi.
- Na konci obdobia sa z tých istých údajov vygenerujú výkazy a daňové registratúry a uzatvorený mesiac sa zablokuje.
Nič v tomto zozname nevyžaduje, aby človek otváral účtovný softvér. To je hlavný zmysel tejto kategórie.
Porovnanie s alternatívami
| Prístup | Počiatočná náročnosť | Pozícia pri audite | Mierka s objemom transakcií |
|---|---|---|---|
| Tabuľky a manuálne zadávanie | Najnižšia | Slabá, história je upraviteľná | Nie |
| Účtovná aplikácia plus CSV exporty | Nízka | Závisí výlučne od disciplíny | Slabo, niekto musí súbory importovať |
| Agregátorové API do účtovníctva každého zákazníka | Stredná | Preberá to, čo poskytuje nástroj zákazníka | Áno, ale záznam nevlastníte |
| Vložené (embedded) účtovné API | Stredná | Silná, ak je hlavná kniha nemenná a obdobia sa uzatvárajú | Áno |
| Vlastná vývoj hlavnej knihy | Najvyššia | Silná iba vtedy, ak si vytvoríte aj kontrolné mechanizmy | Áno, a udržiavate ju navždy |
Vlastný vývoj je pre niektoré tímy legitímnou voľbou. Podrobnejšie sa mu venujeme v našom sprievodcovi vývoja verzus nákupu pre trhoviská.
Čo si overiť pred integráciou
- Je zostatok odvodený alebo uložený? Spýtajte sa, či je zostatok predajcu výsledkom dotazu nad účtovnými riadkami, alebo stĺpcom, ktorý niekto aktualizuje. Len jedna z týchto možností obstojí pri audite.
- Čo sa stane pri opakovarej požiadavke (retry)? Odošlite rovnakú požiadavku dvakrát a spočítajte záznamy.
- Dá sa zaúčtovaný záznam upraviť? Odpoveď by mala byť nie, spolu s zdokumentovaným postupom opravy.
- Zablokované obdobie skutočne odmietne zaúčtovanie? Vyskúšajte si to v pieskovisku (sandbox). Nordlet vráti kód
409pre zaúčtovanie s dátumom v uzatvorenom období. - Ako sú reprezentované peniaze? Desatinné reťazce alebo celé centové jednotky. Nikdy nie čísla s plávacou rádovou čiarkou.
- Čo obsahuje záznam auditu (audit record)? Aktér, akcia, entita a samotná zmena, ktoré sú vyhľadateľné, nie skryté v logovacích súboroch.
- Aké sú limity počtu požiadaviek (rate limits)? Nordlet povoľuje 300 požiadaviek za minútu na jeden API kľúč a zvyšný limit hlási v hlavičkách odpovede. Bez ohľadu na konkrétne číslo ho musíte poznať skôr, než navrhnete synchronizáciu.
- Ako dostanete dáta von? Výkazy, dokumenty a denníky vo formátoch, ktoré môžete odovzdať účtovníkovi.
Každý z týchto bodov sa dá otestovať za jedno popoludnie oproti testovacej firme v pieskovisku. Zoznamy funkcií od predajcov nie sú dôkazom, reprodukovateľný test áno.
FAQ
Je účtovné API to isté ako účtovný softvér?
Je to účtovný softvér s presunutým rozhraním. Tradičný účtovný softvér umiestňuje človeka pred hlavnú knihu, zatiaľ čo účtovné API tam umiestňuje váš kód. Základné povinnosti, štruktúra podvojného účtovníctva a výkazy sú rovnaké.
Budem stále potrebovať účtovníka, ak ho budem používať?
Áno. API automatizuje zaznamenávanie, výpočet a vykazovanie. Nevykonáva odborné úsudky o klasifikácii, rezervách ani o tom, ako sa má posudzovať konkrétna zmluva, a vo väčšine krajín nepodpisuje ani nepodáva vaše závierky.
Môžem použiť účtovné API bez toho, aby som rozumel podvojnému účtovníctvu?
Čiastočne. Dobré API vytvorí účtovné zápisy za vás na základe obchodného dokumentu, akým je faktúra. Stále však musíte rozumieť tomu, čo účty znamenajú, keď čítate výkaz alebo vysvetľujete zostatok audítorovi.
Aký je rozdiel medzi účtovným API a API hlavnej knihy (ledger API)?
API hlavnej knihy zaznamenáva vyrovnané pohyby medzi účtami. Účtovné API robí to isté a navyše pridáva zákonnú vrstvu: dokumenty s právnym číslovaním, daňový režim DPH, daňové registratúry, dlhodobý majetok, uzávierku období a výkazy, ktoré daná jurisdikcia vyžaduje. Každé účtovné API obsahuje hlavnú knihu, ale nie každá hlavná kniha je účtovným systémom.
Ako dlho trvá integrácia?
Pri prvom fungujúcom procese, ako je vytvorenie zákazníka, vystavenie faktúry, prijatie platby a zobrazenie účtovného zápisu, počítajte s dňami namiesto týždňov, ak máte k dispozícii typové SDK a pieskovisko. Produkčná integrácia pokrývajúca vrátenie platieb, opravy, viaceré meny, párovanie a uzávierku obdobia je rozsiahlejšia práca a čestný odhad závisí od toho, koľko z týchto prípadov váš produkt reálne generuje.