Nordlet

← Blog

X'Inhu API tal-Kontabilità? Gwida f'Lingwa Sempliċi għal Dawk li Jbnu l-Pjattaformi

Definizzjoni f'lingwa sempliċi tal-API tal-kontabilità, x'jifridha minn API tat-taxxa jew API tal-pagamenti, u x'għandek tiċċekkja qabel ma tibni fuqha.

Nordlet Team · · 6 min qari

API tal-kontabilità hija interface li tħalli programm wieħed iżomm il-kotba ta' programm ieħor. Is-software tiegħek jibgħat avveniment finanzjarju permezz tal-HTTP. L-API tikkonverti dak l-avveniment f'entries fil-ġurnal tad-dħul doppju bilanċjati kontra pjan tal-kontijiet (chart of accounts), taħżinhom b'tali mod li ma tkunx tista' tibdilhom fis-skiet, tapplika t-trattament tat-taxxa, u tagħtik lura rapporti, dokumenti, u esportazzjonijiet permezz tal-istess interface.

Dik id-definizzjoni tagħmel il-biċċa l-kbira tax-xogħol. Kull ħaġa oħra f'dan l-artikolu hija konsegwenza tagħha.

Il-verżjoni ta' sentenza waħda

API tal-kontabilità taċċetta avvenimenti finanzjarji mill-applikazzjoni tiegħek, tikkonverti lil kull wieħed f'entry tal-ġurnal bilanċjata, taħżinhom b'mod immutabbli bit-trattament tat-taxxa u l-evidenza ta' sostenn tagħhom, u tesponi l-ledger, id-dokumenti, u r-rapporti li jirriżultaw bħala endpoints programmabbli.

Jekk prodott isejjaħ lil innifsu API tal-kontabilità iżda ma jipproduċix entries fil-ġurnal, ikun xi ħaġa oħra b'isem tajjeb. Dak mhux neċessarjament ħażin. Ifisser biss li ma tagħmilx ix-xogħol li int se titlobha tagħmel.

X'm'hix API tal-kontabilità

Erbgħa kategoriji ta' prodotti li jmissu ma' xulxin jitħalltu ma' APIs tal-kontabilità, ġeneralment tard f'proġett.

Kategorija X'tagħmel X'ma tagħmilx
API tal-kalkolu tat-taxxa Tirritorna r-rata korretta jew l-ammont tat-taxxa għal tranżazzjoni Żomm il-kotba tiegħek, jew taħżen l-evidenza wara d-deċiżjoni għall-perjodu ta' żamma
API tal-pagamenti Tmexxi l-flus bejn il-partijiet u tirrapporta dwar dawk il-movimenti Tirreġistra l-kummissjoni mirbuħa, il-VAT dovuta, jew ir-responsabbiltà lejn bejjiegħ bejn il-pagament u l-ħlas lura (payout)
API unifikata jew aggregatriċi Taqra u tikteb data fis-software tal-kontabilità eżistenti tal-klijent tiegħek Taġixxi b-sistema tar-reġistrazzjoni; il-kotba tiegħek jgħixu f'liema għodda diġà juża kull klijent
API tar-rapportar jew BI Taqra figuri minn ledger eżistenti u viżwalizzahom Toħloq l-entries li minnhom huma derivati l-figuri

Kieku dawk kollha għandhom użi reali. Pjattaforma li teħtieġ tkun is-sistema tar-reġistrazzjoni teħtieġ l-API tal-kontabilità taħtha, mhux minflokha.

Il-ħames affarijiet li API tal-kontabilità trid tagħmel

1. Tireġistra entries bilanċjati. Kull avveniment isir debiti u krediti li jingħaddew għall-istess figura. Meta xerrej iħallas €100 fuq marketplace li jieħu kummissjoni ta' €15, l-entry tiddébita kont ta' clearing b'€100, tikkrédita ammont pagabbli lill-bejjiegħ bi €85, u tikkrédita d-dħul mill-kummissjoni bi €15. Din mhix ċerimonja tal-bookkeeping. Hija verifika strutturali li taqbad klassijiet sħaħ ta' bugs tal-integrazzjoni qabel ma jaslu f'rapport.

2. Żomm l-istorja. Entry li tkun ġiet posted ma tiġix editjata. Żball jiġi kkoreġut b'reversal flimkien ma' entry ikkoreġuta, it-tnejn marbuta mal-oriġinali. Xhur magħluqa jiġu msakkra sabiex xewqa ġdida ma tkunx tista' tiġi datata fihom.

3. Soluzzjoni tat-taxxa. Għall-kummerċ fl-UE, dan ifisser il-post tal-provvista, ir-reverse charge, in-numri tal-identifikazzjoni tal-VAT iċċekkjati kontra r-reġistru uffiċjali, u l-evidenza li ġġustifikat id-deċiżjoni, kollha maħżuna flimkien mat-tranżazzjoni minflok ma jintremew wara l-kalkolu.

4. Rikonċiljazzjoni kontra flus ta' barra. Kotba li qatt ma jiltaqgħu ma' bank statement huma suppożizzjoni. L-API trid tinġerixxi dikjarazzjonijiet jew settlements tal-fornitur u tqabbelhom ma' dak li ġie rreġistrat.

5. Esportazzjoni. Rapporti, dokumenti, u fajls tal-awditjar, f'formati li accountant uman u awtorità tat-taxxa jaċċettaw.

Prodott li jagħmel l-ewwel tlieta iżda mhux l-aħħar tnejn xorta jħalli persuna tagħmel xogħol fuq spreadsheet kull xahar.

Kif tidher sejħa fil-verità

Il-mekkaniżmi huma aktar sempliċi mill-kontabilità. Fil-API ta' Nordlet kull operazzjoni hija POST stil RPC b'forma prevedibbli:

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

Tirbaħ fattura tal-bejgħ, imbagħad toħroġha. Il-ħruġ huwa l-mument li fih iseħħ il-kontabilità: id-dokument jieħu n-numru sekwenzjali tiegħu mingħajr lakuni, l-entry bilanċjata tal-ġurnal tiġi posted, u l-linji tal-VAT jiġu rreġistrati magħha. Il-pjattaforma tiegħek qatt ma tgħaqqad debiti u krediti bl-idejn.

Tliet dettalji f'dak is-snipett jimportaw aktar mill-isem tal-endpoint:

  • L-iskop (scope) fuq i-key. Key iġġorr permessi bħal sales:write, sabiex integrazzjoni tieħu biss l-aċċess li teħtieġ.
  • L-idempotency key. Erġa' pprova l-istess talba bl-istess payload u tieħu r-rispons maħżun lura minflok it-tieni fattura. Ibgħat l-istess key b'payload differenti u t-talba tiġi miċħuda b'idempotency_key_reuse minflok ma tiġi aċċettata bil-kwiet.
  • Flus bħala string. L-ammonti huma string deċimali, mhux numri floating-point, minħabba li l-floats jitilfu ċ-ċenteżmi b'modi li joħorġu fil-wiċċ fi tmiem is-sena.

Fejn toqgħod fl-arkitettura tiegħek

L-applikazzjoni tiegħek tibqa' l-front end u s-sors tal-avvenimenti kummerċjali. L-API tal-kontabilità ssir is-sistema finanzjarja tar-reġistrazzjoni warajha. Il-fluss normalment ikun:

  1. Jiġri xi ħaġa fil-prodott tiegħek: ordni, rifużjoni, payout, tiġdid ta' abbonament.
  2. Il-backend tiegħek jsejjaħ lill-API tal-kontabilità bl-avveniment u idempotency key.
  3. L-API tipposta l-entry fil-ġurnal, tapplika l-VAT, u tirritorna identifikaturi li taħżen kontra r-reġistri tiegħek stess.
  4. Webhook bħal sale_invoice.paid jgħid is-sistema tiegħek meta l-istat jinbidel, sabiex tirreaġixxi għall-avvenimenti minflok ma tagħmel polling għalihom.
  5. Tranżazzjonijiet bankarji jaslu permezz ta' bank feed jew importazzjoni ta' statement u jiġu mqabbla kontra d-dokumenti rreġistrati.
  6. Fi tmiem il-perjodu, jiġu ġenerati rapporti u reġistri tat-taxxa mill-istess data, u x-xahar magħluq jissakkar.

Xejn f'dik il-lista ma jeħtieġ li bniedem jiftaħ applikazzjoni tal-kontabilità. Dak huwa l-punt tal-kategorija.

Kif tqabbel mal-alternattivi

Approċċ Sforz biex tibda Pożizzjoni tal-awditjar Tiskala bil-volum tat-tranżazzjonijiet
Spreadsheets u dħul manwali L-aktar baxx Dgħajfa; l-istorja tista' tiġi editjata Le
App tal-kontabilità flimkien ma' esportazzjonijiet CSV Baxx Tiddependi kompletament fuq id-dixxiplina Ħażin; xi ħadd jimporta l-fajls
API aggregatriċi fil-kotba proprji ta' kull klijent Medju Tiviret dak li tagħmel l-għodda tal-klijent Iva, im libsql qatt ma tkun sid ir-reġistru
API tal-kontabilità inkorporata (embedded) Medju Qawwija jekk il-ledger huwa immutabbli u l-perjodi jissakkru Iva
Ibni l-ledger tiegħek stess L-ogħla Qawwija biss jekk tibni l-kontrolli wkoll Iva, u żżommu għal dejjem

Il-bini tas-sistema tiegħek huwa għażla leġittima għal xi timijiet. Huwa koprut f'aktar dettall fil-gwida tagħna dwar il-bini kontra x-xiri għall-marketplaces.

X'għandek tiċċekkja qabel tibni fuqha

  • Il-bilanċ huwa derivat jew maħżun? Staqsi jekk il-bilanċ ta' bejjiegħ huwiex query fuq il-linji tal-ġurnal jew kolonna li xi ħadd aġġorna. Waħda biss minn dawk tibqa' ħajja f'awditjar.
  • X'jiġri meta jkun hemm tentattiv ripetut (retry)? Ibgħat l-istess talba darbtejn u aħgodd l-entries.
  • Tista' teditja entry li tkun ġiet posted? It-tweġiba għandha tkun le, b'mogħdija ta' korrezzjoni dokumentata.
  • Perjodu msakkar fil-fatt jirrifjuta posting? Ipprovaha f'sandbox. Nordlet jirritorna 409 għal posting iddatat ġewwa perjodu msakkar.
  • Il-flus kif huma rappreżentati? String deċimali jew unitajiet minuri sħaħ. Qatt floats.
  • X'hemm fir-reġistru tal-awditjar? L-attur, l-azzjoni, l-entità, u l-bidla nnifisha, li tista' ssirilha query minflok ma tkun midfuna fil-fajls tar-reġistri (log files).
  • X'inhu l-limitu tar-rati (rate limits)? Nordlet jippermetti 300 talba kull minuta għal kull API key u jirrapporta l-baġit li fadal tiegħek fl-headers tar-rispons. Kido jkun in-numru, afulu qabel ma tfassal is-sync tiegħek.
  • Kif toħroġ id-data tiegħek barra? Rapporti, dokumenti, u ġurnali, f'formati li tista' tagħti lil accountant.

Kull waħda minn dawk tista' tiġi ttestjata f'nofsinhar kontra kumpanija tas-sandbox. Il-listi tal-karatteristiċi tal-bejjiegħ mhumiex evidenza; test riproduċibbli huwa.

FAQ

L-API tal-kontabilità hija l-istess bħas-software tal-kontabilità?

Hija software tal-kontabilità bl-interface mċaqalqa. Is-software tal-kontabilità tradizzjonali jqiegħed persuna quddiem il-ledger; API tal-kontabilità tpoġġi l-kodiċi tiegħek hemmhekk. L-obbligi sottostanti, l-istruttura tad-dħul doppju, u ir-rapporti huma l-istess.

Xorta neħtieġ accountant jekk nuża waħda?

Iva. API awtomatizza r-reġistrazzjoni, il-kalkolu, u r-rapportar. Ma tagħmilx ġudizzji dwar il-klassifikazzjoni, id-dispożizzjonijiet, jew kif kuntratt speċifiku għandu jiġi ttrattat, u fil-biċċa l-kbira tal-pajjiżi ma tiffirmax jew ma tressqux il-kontijiet statutorji tiegħek.

Nista' nuża API tal-kontabilità mingħajr ma nifhem id-dħul doppju?

Parzjalment. API tajba tikkostruwixxi l-entries tal-ġurnal għalik minn dokument kummerċjali bħal fattura. Xorta trid tifhem xi jfissiru l-kontijiet meta taqra rapport jew tispjega bilanċ lil awditur.

X'inhi d-differenza bejn API tal-kontabilità u API tal-ledger?

API tal-ledger tirreġistra movimenti bilanċjati bejn il-kontijiet. API tal-kontabilità tagħmel dan u żżid is-saff statutorju fuq fuq: dokumenti b'numrazzjoni legali, trattament tal-VAT, reġistri tat-taxxa, assi fissi, għeluq tal-perjodu, u r-rapporti li ġurisdizzjoni tistenna. Kull API tal-kontabilità fiha ledger; mhux kull ledger huwa sistema tal-kontabilità.

Kemm tieħu żmien biex tintegra waħda?

Għall-ewwel fluss tax-xogħol li jaħdem - oħloq klijent, oħroġ fattura, irċievi pagament, ara l-entry fil-ġurnal - ippjana jiem minflok ġimgħat b'SDK tat-tipi (typed SDK) u sandbox. Integrazzjoni ta' produzzjoni li tkopri rifużjonijiet, korrezzjonijiet, muniti multipli, rikonċiljazzjoni, u għeluq tal-perjodu hija biċċa xogħol akbar, u l-istima onesta tiddependi fuq kemm minn dawk il-każijiet il-prodott tiegħek ġenwinament jiġġenera.

Aktar qari