Mis on raamatupidamise API? Praktiline juhend platvormi loojatele
Raamatupidamise API lihtne määratlus, mis eristab seda maksu- või makselahenduse API-st ning mida tuleks enne sellele ehitamist kontrollida.
Raamatupidamise API on liides, mis võimaldab ühel programmil pidada teise programmi raamatupidamist. Teie tarkvara saadab finantssündmuse HTTP kaudu. API muudab selle sündmuse kontoplaani alusel tasakaalustatud kahekordse kirjendamise (double-entry) kande(te)ks, salvestab need viisil, mida ei saa märkamatult muuta, rakendab maksutöötluse ning tagastab sama liidese kaudu aruanded, dokumendid ja eksportfailid.
See määratlus teeb ära suurema osa tööst. Kõik muu selles artiklis tuleneb otseselt sellest.
Ühe lause versioon
Raamatupidamise API võtab teie rakendusest vastu finantssündmused, teisendab iga sündmuse tasakaalustatud kandeühikuks, salvestab selle muutumatul kujul koos maksustamise ja alusdokumentidega ning teeb tulemuseks oleva pearaamatu, dokumendid ja aruanded kättesaadavaks programmeeritavate otspunktidena (endpoints).
Kui toode nimetab end raamatupidamise API-ks, kuid ei loo kandeid, on tegemist millegi muuga, millel on lihtsalt hea nimi. See ei ole tingimata halb asi, kuid see tähendab, et see ei tee seda tööd, mida te temalt ootate.
Mida raamatupidamise API ei tee
Raamatupidamise API-dega aetakse sageli – tavaliselt projekti hilises faasis – segi neli lähedast tootokategooriat.
| Kategooria | Mida see teeb | Mida see EI TEE |
|---|---|---|
| Maksuarvutuse API | Tagastab tehingu jaoks õige maksumäära või maksusumma | Ei pea raamatupidamist ega säilita säilitustähtaja jooksul otsuse aluseks olevaid tõendeid |
| Maksete API | Liigutab osapoolte vahel raha ja raporteerib nendest liikumistest | Ei kirjenda teenitud vahendustasu, maksmisele kuuluvat käibemaksu ega müüja ees olevat kohustust makse ja väljamakse vahel |
| Ühendatud (aggregated) API | Loeb ja kirjutab andmeid teie kliendi olemasolevasse raamatupidamistarkvarasse | Ei toimi arvestussüsteemina (system of record); teie raamatupidamine asub tööriistas, mida iga klient juba kasutab |
| Aruandluse või BI API | Loeb arvandmeid olemasolevast pearaamatust ja visualiseerib neid | Ei loo kandeid, millest need arvud on tuletatud |
Igal neist on oma kindel kasutusotstarve. Platvorm, mis peab ise olema arvestussüsteem, vajab oma toimimiseks raamatupidamise API-t, mitte ei saa seda millegagi asendada.
Viis asja, mida raamatupidamise API peab tegema
1. Kirjendama tasakaalustatud kanded. Iga sündmus muutub deebetiteks ja kreedititeks, mille summad on võrdsed. Kui ostja maksab platvormil 100 eurot ja platvorm võtab 15 eurot vahendustasu, debiteeritakse arvelduskontot 100 euroga, kreediteritakse müüja kohustust 85 euroga ja kreediteritakse vahendustasu tulu 15 euroga. See ei ole lihtsalt raamatupidamislik rituaal, vaid struktuurne kontroll, mis püüab integratsioonivead kinni enne, kui need aruandesse jõuavad.
2. Hoidma ajalugu. Sisestatud kannet ei redigeerita. Viga parandatakse paranduskande ja uue õige kande abil, mis mõlemad on algse kandega seotud. Suletud kuud lukustatakse, et nendesse ei saaks enam uusi kandeid lisada.
3. Lahendama maksud. EL-i siseste tehingute puhul tähendab see käibe tekkimise kohta, pöördmaksustamist, ametlikust registrist kontrollitud käibemaksukohustuslase numbreid ja otsust õigustavaid tõendeid – ning seda kõike hoitakse koos tehinguga, mitte ei visata pärast arvutust minema.
4. Teostama pangakonto võrdlemist (reconciliation). Raamatupidamine, mis ei kohta kunagi pangaväljavõtet, on vaid oletus. API peab sisse lugema väljavõtteid või teenusepakkujate arveldusi ja sobitama neid salvestatuga.
5. Võimaldama eksporti. Aruanded, dokumendid ja auditifailid vormingutes, mida inimraamatupidaja ja maksuhaldur aktsepteerivad.
Toode, mis teeb kolm esimest asja, kuid mitte kahte viimast, jätab inimese ikkagi iga kuu tabelarvutustega töötama.
Kuidas üks API päring tegelikult välja näeb
Tehniline pool on lihtsam kui raamatupidamine ise. Nordleti API-s on iga toiming RPC-stiilis POST-päring etteaimatava struktuuriga:
POST /v1/{module}/{resource}/{action}
Authorization: Bearer <api key>
Idempotency-Key: <your event id>
Loote müügiarve ja seejärel kinnitate selle. Kinnitamine on hetk, mil toimub raamatupidamine: dokument saab oma katkematu numbri, tasakaalustatud kanne postitatakse ja käibemaksuread salvestatakse koos sellega. Teie platvorm ei pea kunagi deebeteid ja kreedeteid käsitsi kokku panema.
Selles koodilõigus on kolm detaili, mis on otspunkti nimest olulisemad:
- Võtme ulatus (scope). Võti kannab endas õiguseid, näiteks
sales:write, nii et integratsioon saab ainult vajaliku juurdepääsu. - Idempotentsuse võti (idempotency key). Sama päringu kordamine sama sisuga tagastab salvestatud vastuse, mitte teise arve. Sama võtme saatmine erineva sisuga lükatakse tagasi veaga
idempotency_key_reuse, selle asemel et seda vaikimisi aktsepteerida. - Raha esitamine stringidena. Summad on kümnendmurruna stringid, mitte ujukomaarvud (floats), sest ujukomaarvud kaotavad sente viisidel, mis tulevad esile aasta lõpus.
Kus see teie arhitektuuris paikneb
Teie rakendus jääb kasutajaliideseks ja ärisündmuste allikaks. Raamatupidamise API-st saab selle taga olev finantsarvestuse süsteem. Protsess näeb tavaliselt välja järgmiselt:
- Teie tootes toimub sündmus: tellimus, tagasimakse, väljamakse või tellimuse pikendamine.
- Teie taustsüsteem kutsub raamatupidamise API-t välja koos sündmuse ja idempotentsuse võtmega.
- API postitab kande, rakendab käibemaksu ja tagastab identifikaatorid, mida salvestate oma andmebaasi.
- Veebikonks (webhook), näiteks
sale_invoice.paid, annab teie süsteemile teada oleku muutumisest, nii et saate sündmustele reageerida, selle aega korduvalt andmeid pärimata (polling). - Pangatehingud saabuvad pangaliidese või väljavõtte impordi kaudu ja need seotakse salvestatud dokumentidega.
- Perioodi lõpus genereeritakse samade andmete põhjal aruanded ja maksuaruanded ning suletud kuu lukustatakse.
Ükski punkt selles loendis ei eelda, et inimene peaks avama eraldi raamatupidamistarkvara. Selles ongi selle kategooria mõte.
Kuidas see võrdub alternatiividega
| Lähenemine | Alustamise keerukus | Auditeeritavus | Skaleeruvus tehingute mahuga |
|---|---|---|---|
| Tabelarvutused ja käsitsi sisestamine | Madal | Nõrk; ajalugu on muudetav | Ei |
| Raamatupidamistarkvara plus CSV eksport | Madal | Sõltub täielikult distsipliinist | Halvasti; keegi peab faile importima |
| Agregaatori API iga kliendi enda raamatupidamisse | Keskmine | Pärib selle, mida kliendi tööriist võimaldab | Jah, aga te ei oma andmeid ise |
| Integreeritud raamatupidamise API | Keskmine | Tugev, kui pearaamat on muutumatu ja perioodid lukustuvad | Jah |
| Oma pearaamatu ehitamine | Kõrge | Tugev ainult siis, kui ehitate ka kontrollmehhanismid | Jah, ja te hooldate seda igavesti |
Oma lahenduse ehitamine on teatud meeskondade jaoks õigustatud valik. Seda on üksikasjalikumalt kirjeldatud meie turupõhise tarkvara ehitamise ja ostmise juhendis.
Mida kontrollida enne API-le ehitamist
- Kas saldo on tuletatud või salvestatud? Küsige, kas müüja saldo on päring üle kandereade või veerus olemasolev väärtus, mida keegi uuendab. Ainult üks neist peab auditi vastu.
- Mis juhtub päringu kordamisel (retry)? Saatke sama päring kaks korda ja lugege kandeid.
- Kas postitatud kannet saab muuta? Vastus peaks olema eitav, koos dokumenteeritud paranduste tegemise viisiga.
- Kas lukustatud periood lükkab kande tegelikult tagasi? Katsetage seda liivakastis (sandbox). Nordlet tagastab lukustatud perioodi sisse jääva kande korral veakoodi
409. - Kuidas raha esitatakse? Kümnendmurruna stringidena või täisarvuliste sendiühikutena. Mitte kunagi ujukomaarvudena.
- Mis sisaldub auditilogis? Toimepanija, toiming, olem ja muudatus ise, mis on päritavad, mitte logifailidesse mattunud.
- Millised on päringupiirangud (rate limits)? Nordlet lubab 300 päringut minutis API-võtme kohta ja raporteerib ülejäänud limiiti vastuse päistes. Mis tahes number see ka poleks, teadke seda enne sünkroonimise kujundamist.
- Kuidas te omaandmed kätte saate? Aruanded, dokumendid ja kanded vormingutes, mida saate raamatupidajale esitada.
Igaüks neist punktidest on ühel pärastlõunal testitav liivakastikeskkonnas. Tarnijate funktsioonide loendid ei ole tõend – korratav test on.
FAQ
Kas raamatupidamise API on sama mis raamatupidamistarkvara?
See on raamatupidamistarkvara, mille liides on viidud teise kohta. Traditsiooniline raamatupidamistarkvara paneb inimese pearaamatu ette istuma, raamatupidamise API aga teie koodi. Aluseks olevad kohustused, kahekordse kirjendamise struktuur ja aruanded on samad.
Kas mul on endiselt raamatupidajat vaja, kui ma seda kasutan?
Jah. API automatiseerib kirjendamist, arvutamist ja aruandlust. See ei tee otsuseid klassifitseerimise, eraldiste ega konkreetse lepingu käsitlemise kohta ning enamikus riikides ei allkirjasta ega esita see teie kohustuslikke majandusaasta aruandeid.
Kas ma saan raamatupidamise API-t kasutada kahekordset kirjendamist mõistmata?
Osaliselt. Hea API koostab teie eest äridokumendi, näiteks arve, põhjal raamatupidamiskanded. Peate siiski mõistma, mida kontod aruannet lugedes tähendavad või kuidas selgitada saldot audiitorile.
Mis vahe on raamatupidamise API-l ja pearaamatu (ledger) API-l?
Pearaamatu API kirjendab tasakaalustatud liikumisi kontode vahel. Raamatupidamise API teeb seda ja lisab peale seadusandliku kihi: juriidilise numeratsiooniga dokumendid, käibemaksutöötluse, maksuaruanded, põhivarad, perioodi sulgemise ja aruanded, mida vastav jurisdiktsioon oodatakse. Iga raamatupidamise API sisaldab pearaamatut, kuid iga pearaamat ei ole raamatupidamissüsteem.
Kui kaua võtab integreerimine aega?
Esimese töötava protsessi jaoks – kliendi loomine, arve väljastamine, makse laekumine, kande nägemine – plaanige tüüpilise SDK ja liivakasti abil pigem päevi kui nädalaid. Tootmisintegratsioon, mis katab tagasimaksed, parandused, mitme valuuta toega arvelduse, võrdlemise ja perioodi sulgemise, on suuremahulisem töö ning aus hinnang sõltub sellest, kui palju selliseid juhtumeid teie toode reaalselt genereerib.