Co je API podvojné účetní knihy pro tržiště?
API podvojné účetní knihy zaznamenává pohyb peněz na tržištích jako vyrovnané a neměnné účetní zápisy, takže vždy přesně víte, komu a proč co dlužíte.
Tržiště může ve své tabulce orders vypadat zdravě, a přesto mít v penězích zmatek. V objednávce svítí stav „zaplaceno“. Na prodejním panelu prodejce se zobrazuje zůstatek. Nic v této tabulce však neprokazuje, kolik hotovosti platforma drží, kolik dluží jednotlivým prodejcům, jaká část platby představuje provizní výnos nebo jaká DPH je aktuálně splatná. K správnému zaznamenání těchto finančních dopadů slouží API podvojné účetní knihy (double-entry ledger API), a to vždy po jedné vyrovnané transakci.
Zjednodušeně řečeno: API podvojné účetní knihy je programovatelný účetní systém. Vaše aplikace mu odešle finanční událost, například zachycenou platbu nebo schválenou výplatu, a účetní kniha tuto událost zaznamená jako zápis s rovnými má dáti (debit) a dal (credit) na příslušných účtech. Peníze nepřesouvá. Zaznamenává pravdu o penězích, které se pohybovaly jinde.
Co zde znamená „podvojná účetní kniha“
Účetní kniha (ledger) je záznamem o změnách na účtech, nikoliv pouhou tabulkou uchovávající aktuální zůstatek. Fungující účetní kniha stojí na třech propojených pilířích:
- Účet (account): pojmenovaná finanční pozice, například pohledávka za platební bránou, závazek vůči prodejci, výnos z provizí nebo splatná DPH.
- Transakce (journal): jedna atomická finanční událost obsahující více vyrovnaných řádků.
- Položka (posting): jeden řádek s má dáti nebo dal v rámci dané transakce.
Nezměnitelné pravidlo (invariant), které drží celý návrh pohromadě, je jednoduché: celková částka má dáti se rovná celkové částce dal, a to pro každou transakci i každou měnu. API účetních knih obvykle odmítne nevyrovnaný zápis ještě předtím, než se dostane do úložiště. Dokumentace Modern Treasury definuje transakci v účetní knize jako operaci zahrnující dva nebo více účtů s nejméně jednou položkou má dáti a jednou položkou dal o stejné celkové výši a zaúčtovanou transakci považuje za neměnnou (immutable).
Podvojnost neznamená přesně dva řádky. Jediný prodej na tržišti často vyžaduje jednu položku má dáti a několik položek dal. Právě tomu lidé nejčastěji špatně rozumějí.
Proč tržiště potřebují účetní knihu, a ne jen tabulku plateb
Tržiště spravuje hned několik finančních vztahů současně. Kupující platí. Platební brána provádí zúčtování. Platforma může prostředky dočasně kontrolovat. Prodejce si vydělává určitý podíl. Platforma si ponechává provizi. Vzniká daňová povinnost. Může být zadržena rezerva. Později výplata peníze odešle a refundace či chargebacky část z nich vrátí.
Tabulka payments vám dokáže sdělit obchodní stav objednávky. Nedokáže vám však spolehlivě říct:
- kolik činí pohledávka za platební bránou nebo hotovost
- kolik se dluží jednotlivým prodejcům
- jaký výnos náleží platformě
- jaká DPH je splatná a ve které zemi
- co je rezervováno pro případ refundací nebo sporů
- zda výplata snížila správný závazek vůči prodejci
- zda se zúčtování platební brány shoduje s tím, co platforma očekávala
Průvodce Nordlet k API podvojných účetních knih pro účetnictví tržišť staví jasnou hranici: tabulky aplikací popisují stav produktu, zatímco účetní kniha zaznamenává finanční dopady tohoto stavu. Zároveň připomíná myšlenku, kterou stojí za to opakovat, a sice že reporty od platebních brán jsou vstupy pro odsouhlasení, nikoliv úplné podvojné účetnictví.
Ukázka prodeje na tržišti
Předpokládejme, že kupující zaplatí €100, prodejce má nárok na €85 a provize platformy činí €15. Pro přehlednost vynecháme DPH a poplatky brány.
| Účet | Má dáti | Dal | Důvod |
|---|---|---|---|
| Pohledávka za platební bránou | €100 | Brána dluží platformě zachycenou platbu | |
| Závazek vůči prodejci | €85 | Platforma dluží prodejci | |
| Výnos z provizí | €15 | Platforma vydělala na provizi | |
| Celkem | €100 | €100 | Vyrovnáno |
Důležitou klasifikací je zde fakt, že částka €85 dlužená prodejci představuje závazek, nikoliv výnos platformy. Podle koncepčního rámu IFRS je závazek současným dlouhem převést ekonomický zdroj. Tržiště by nemělo vykazovat plnou tržbu prodejce jako svůj vlastní příjem jen proto, že kupující zaplatil prostřednictvím něj. Zda vystupujete jako zprostředkovatel (agent), komisionář (principal) nebo osoba považovaná za dodavatele (deemed supplier), mění způsob zaúčtování, ale mechanismus účetní knihy zůstává stejný.
Když má prodejce nárok na výplatu, nezaúčtuje se žádný nový výnos. Pouze se vyrovná závazek:
| Účet | Má dáti | Dal |
|---|---|---|
| Závazek vůči prodejci | €85 | |
| Banka nebo zúčtovací účet výplat | €85 | |
| Celkem | €85 | €85 |
Pokud si brána před zúčtováním strhne poplatek €3, pohyb hotovosti se promění v třířádkový deník: €97 na bankovní účet, €3 na náklady na zpracování plateb, €100 odepsaných z pohledávky za platební bránou. Každá změna pozice má svůj zdroj a cíl.
Jak API funguje krok za krokem
1. Vaše aplikace detekuje obchodní událost. Dojde k zachycení platby, splnění objednávky, schválení výplaty, vydání refundace, otevření chargebacku nebo přijetí zúčtování. Vaše databáze nadále spravuje provozní stav. Účetní kniha zaznamenává peněžní dopad.
2. Odešlete strukturovaný požadavek. Obvykle obsahuje typ události, částku a měnu, ID objednávky nebo platby, identifikátory kupujícího a prodejce, provizi, daňová data, zapojené účty, datum uskutečnění a zaúčtování, idempotentní klíč a metadata odkazující zpět na záznamy brány a produktu. Příklad veřejného API od Nordlet ukazuje koncepční požadavek na prodej s ID prodejce, typem prodeje, částkou, měnou a zemí a sazbou DPH.
3. API provede ověření. Zkontroluje, zda má dáti a dal jsou v rovnováze, zda účty existují a lze na ně účtovat, zda je měna podporována, zda částka používá přesnou práci s drobnými jednotkami (minor units), zda nebyl idempotentní klíč použit pro jiný výsledek, zda je účetní období otevřeno a zda jsou přítomna požadovaná metadata. Neúspěšná kontrola nezanechá v systému žádný částečný zápis.
4. Zaúčtuje transakci atomicky. Celá transakce se zapíše jako jeden celek. Nikdy se nesmí stát, že by se zaznamenalo má dáti, zatímco odpovídající dal by selhalo. U tržiště by takové částečné rozdělení mohlo vytvořit zdánlivý zůstatek prodejce bez odpovídající hotovosti nebo zaúčtovat provizi bez závazku vůči prodejci.
5. Zůstatky a reporty se odvíjejí z účetní knihy. Po zaúčtování můžete číst zůstatky účtů, čekající a dostupné zůstatky prodejců, obratovou předvahu, aktivitu hlavní účetní knihy, přehledy DPH a historii k minulému datu. Zůstatek prodejce by měl být sestavitelný ze zápisů, nikoliv načítaný z měnitelného pole.
6. Webhooky informují váš produkt. Události jako sale_invoice.paid, zaúčtovaný deník, dostupná výplata nebo výjimka při odsouhlasení jsou odeslány k vám. Zpracovávejte je idempotentně. Webhook je oznámení, nikoliv povolením aplikovat finanční událost podruhé. Konvence API podrobně popisují rozsahy (scopes), idempotentní klíče, formáty chyb a podepisování webhooků.
Zůstatky prodejců nejsou jediné číslo
Většina tržišť se dostane do potíží tím, že zachází se zůstatkem prodejců jako s jedinou číslovkou. Peníze by měly mít své stavy:
| Stav | Význam |
|---|---|
| Čekající (Pending) | Prodejce může mít nárok, ale podmínky pro uvolnění nebyly splněny |
| Dostupné (Available) | Způsobilé k výplatě |
| Rezervované (Reserved) | Zadržené pro případ refundací, vrácení zboží nebo sporů |
| Vyplacené (Paid out) | Závazek uhrazen převodem |
| Záporné (Negative) | Refundace, chargebacky nebo poplatky převyšují dostupné prostředky |
Modely platebních brán tento přístup kopírují. Oddělené toky poplatků a převodů ve Stripe umožňují platformě zatížit vlastní účet a následně převádět části na připojené účty, přičemž poplatky, refundace a chargebacky zatěžují zůstatek platformy. Model tržiště od Adyen rozlišuje zůstatkové účty uživatelů, které drží prostředky do výplaty, a účet odpovědnosti (liable balance account), který může absorbovat záporné zůstatky z refundací nebo chargebacků. Tyto vstupy jsou užitečné pro vaši účetní knihu. Nejsou však vaším kompletním účetním modelem.
Výplaty a výdělky prodejců probíhají v jiný čas
Prodejce může vydělat peníze v pondělí a zaplaceno dostat následující pondělí. Mezi těmito body dochází k splnění objednávky, zadržení rezervy, sestavení dávky výplat, zúčtování ze strany brány po odečtení poplatků a připsání peněz na bankovní účet. Účetní kniha musí zachovat každou fázi namísto toho, aby přepsala objednávku konečným stavem „zaplaceno“. Právě to vám umožňuje vysvětlit časové rozdíly mezi aktivitou objednávek, nárokem prodejce, zúčtováním, zadáním výplaty a příjmem v bance.
Refundace a chargebacky: vracet, nepřepisovat
Refundace a chargebacky jsou nové události propojené s původní platbou. V neměnné účetní knize provádíte opravu pomocí stornujícího zápisu následovaného opraveným zápisem, takže původní transakce zůstává pro účely auditu viditelná. Modern Treasury považuje zaúčtované transakce za neměnné a podporuje idempotentní klíče, které při opakovaném pokusu zabraňují vzniku duplicitních objektů.
Refundace obvykle snižuje hotovost nebo pohledávku za kupujícím, stornuje závazek vůči prodejci, může v závislosti na pravidlech vrátit část provize, upravuje daň a může čerpat z rezervy na refundace. Chargeback snižuje hotovost nebo pohledávku za platební bránou, může znovu otevřít částku dluženou prodejcem nebo platformou, zaznamenává sporné náklady a poplatek brány a přesouvá prostředky přes rezidentní účet.
Odsouhlasení: propojení účetní knihy s reálnými penězi
Účetní kniha může být vnitřně vyrovnaná a přesto mít zkreslený pohled na vnější svět. Odsouhlasení (reconciliation) porovnává vnitřní záznamy s externími důkazy: zúčtovacími výpisy platební brány, bankovními výpisy, soubory výplat a záznamy o refundacích a sporech.
Fungující proces vypadá následovně:
- Importujte zúčtovací nebo bankovní dávku.
- Spárujte každý řádek s objednávkou, platbou, refundací, poplatkem, výplatou nebo sporem.
- Porovnejte očekávanou hrubou částku, srážky, rezervy a čistou částku.
- Zaúčtujte potvrzené pohyby do účetní knihy.
- Nespárované položky odešlete na pojmenovaný přechodný účet (suspense account).
- Vyšetřete nesrovnalosti.
- Uzavřete období.
Materiály k odsouhlasení od Nordlet popisují přesně tento postup – import zúčtovacích dávek, párování řádek plateb a refundací a směrování nespárovaných příjmů na přechodný účet namísto hádání faktury. Dvě kontroly jsou klíčové a ani jedna nenahrazuje druhou: ověření podvojnosti se ptá, zda každý deník sedí, zatímco odsouhlasení se ptá, zda odpovídá bráně, bance a obchodní události.
Detaily návrhu, které rozhodují o úspěchu
Idempotence. Propojte klíč se stabilní událostí, například payment_captured:pi_123. Opakovaný pokus vrátí původní výsledek, nikoliv druhý deník.
Atomicita. Všechny řádky jedné události se zaúčtují společně, nebo vůbec.
Neměnnost a stornování. Zaúčtovanou historii nelze upravovat běžnými aktualizacemi. Opravy vytvářejí propojené záznamy, které zachovávají původní částku, datum, klasifikaci, důvod a autora.
Přesné peníze. Žádná binární plovoucí řádková desetinná čísla (floats). Používejte celočíselné drobné jednotky nebo přesná desetinná čísla, explicitní měnu a deterministické pravidlo zaokrouhlování pro dělení. Pokud rozdělíte €100 mezi prodejce a poplatky bez těchto pravidel, zatoulaný cent vám rozbije rovnováhu.
Data uskutečnění vs. data zaúčtování. Datum, kdy kupující zaplatil, kdy prodejce vydělal, kdy banka provedla zúčtování a kdy byla položka zaúčtována, jsou různá data. Jejich slévání činí periodické reportování a daňové načasování nespolehlivými.
Víceměnovost. Má dáti a dal by se měly vyrovnat v rámci jedné měny. Konverze vyžaduje explicitní událost kurzu s účty pro poplatek, zaokrouhlení a jakýkoliv kurzový zisk nebo ztrátu. Pouhé přijetí pole currency z účetní knihy devizový engine neudělá.
S čím vám API účetní knihy nepomůže
Nerozhodne za vás o účtové osnově. Stále musíte určit, zda vystupujete jako komisionář (principal) nebo zprostředkovatel (agent), kdy vzniká nárok na provizi, která strana nese poplatky brány, jak refundace ovlivňují provizi a jak se vypočítává a vykazuje DPH. Vlastní doporučení Nordlet radí nejprve mapovat peněžní toky, navrhnout účtovou osnovu, nechat ji zkontrolovat účetním a teprve poté implementovat jeden plný tok od objednávky přes výplatu a odsouhlasení před dalším škálováním.
Nevyřeší za vás daňové otázky. DPH závisí na umístění kupujícího a prodejce, typu produktu, registračním statusu a pravidlech o osobě považované za dodavatele (deemed-supplier rules); průvodce DPH v EU stanoví, co systém odvodí a co označí pro lidský zásah. Pokrytí DPH od Nordlet je zaměřeno na EU a EHP, takže se nevztahuje na americkou daň z prodeje (sales tax) nebo latinskoamerickou elektronickou fakturaci. A nevyřeší ani provozní nejasnosti – zda vypršela lhůta pro vrácení zboží, zda by měla být výplata zablokována nebo zda je platba podvodná. To jsou vaše rozhodnutí. Účetní kniha zaznamenává jejich finanční výsledek.
Kde má Nordlet své místo
Nordlet je účetní API vytvořené pro platformy a tržiště, které nabízí neměnnou podvojnou účetní knihu, výplaty, zpracování DPH v EU, koncové body REST, typová SDK a webhooky přístupné přes jediné rozhraní. Jeho charakteristickým rysem je integrované účetnictví přímo ve vašem produktu namísto externí pokladny. V době psaní tohoto článku je produkt v režimu předběžného přístupu (early access) s sandboxem pro partnery v oblasti návrhu, takže k němu přistupujte jako k silnému příkladu kategorie a před vlastním nasazením si ověřte provozní zralost, dostupnost (uptime) a pokrytí jurisdikcí pro váš konkrétní případ.
Pro vývojáře tržišť a platforem je užitečným mentálním modelem rozdělení mezi pohybem peněz a finanční pravdou. Vaše platební brána peníze přesouvá. API podvojné účetní knihy zaznamenává, komu se co dluží, co jste vydělali, jaké daně a rezervy držíte a zda vnější svět odpovídá vašemu účetnictví.
FAQ
Je API podvojné účetní knihy totéž co platební brána?
Ne. Brána autorizuje, zachycuje, zúčtovává a někdy vyplácí prostředky. API účetní knihy zaznamenává účetní důsledky těchto událostí. Většina tržišť používá obojí – bránu jako Stripe nebo Adyen pro pohyb peněz a účetní knihu pro vedení účetnictví.
Můžu jednoduše použít dashboard platební brány jako hlavní účetní knihu?
Můžete to zkusit, ale dříve či později neprojdete auditem. Reporty brány ukazují platby, poplatky, převody a zúčtování, ale obvykle nezachycují vaše plné závazky vůči prodejcům, daňové povinnosti, nepoplatkové náklady nebo účetní úpravy. Považujte je za vstup pro odsouhlasení.
Znamená vyrovnaná účetní kniha, že mé účetnictví je správné?
Znamená to pouze to, že vaše zápisy splňují pravidlo má dáti / dal. Dokonale vyrovnaná transakce může být stále zaúčtována na nesprávný účet, nesprávnému prodejci nebo s nesprávným daňovým režimem. Rovnováha je nutná, ale sama o sobě nestačí. Odsouhlasení je to, co odhalí zbytek.
Pokud je účetní kniha neměnná, jak mám opravit chyby?
Zadáte stornující zápis a následně opravený zápis. Původní zůstává viditelný, což je celý smysl tohoto přístupu. Neměnnost chrání auditní stopu, nezavírá vás do pasti vašich vlastních chyb.
Udělá ze mě účetní API automaticky osobu v souladu s předpisy?
Ne. Vynucuje účetní strukturu a produkuje použitelné záznamy. Soulad s právními předpisy (compliance) stále závisí na vaší jurisdikci, smluvní roli, daňovém režimu, platebních předpisech, procesech KYC a AML a vašich ohlašovacích povinnostech.