Kā integrēt mākoņgrāmatvedības API SaaS platformā

Lielākā daļa komandu, kas apņemas SaaS produktam "pievienot grāmatvedību", sāk ar to, ka savieno HTTP klientu ar pakalpojumu sniedzēja galapunktu un nosūta rēķinu. Tas lieliski darbojas demonstrācijā. Līdz brīdim, kad klients pirmo reizi savieno divas grāmatvedības organizācijas, kad webhook pienāk divas reizes un kad piekļuves marķieris (refresh token) pieprasījuma vidū tiek atjaunots un pazaudēts. Šāda darba ilgtermiņa versija nav vienkārši klients. Tā ir integrācijas slānis.

Šim slānim ir jāpārvalda īrnieku (tenants) savienojumi, marķieru glabāšana un rotācija, pakalpojumu sniedzēja specifiskie grāmatvedības noteikumi, ierakstu kartēšana, sākotnējā un inkrementālā sinhronizācija, webhook saņemšana ar atkārtotiem mēģinājumiem un dublikātu novēršanu, pieprasījumu biežuma ierobežojumi (rate limits), versiju kontrole un audita žurnāls, ko jūsu atbalsta komanda spēj izlasīt arī pulksten divos naktī. Šajā rakstā mēs aplūkojam šo arhitektūru un lēmumus, kam ir vislielākā nozīme.

Noderīgs vizuālais modelis:

SaaS produkts → grāmatvedības integrācijas serviss → pakalpojumu sniedzēja adapteris (vai vienotais API) → asinhronā sinhronizācija un saskaņošana

Grāmatvedības sistēma paliek par galveno informācijas avotu virsgrāmatas objektiem: kontiem, nodokļu kodiem, iegrāmatotiem darījumiem un grāmatojumiem. Savukārt jūsu SaaS platforma uztur stabilus identifikatorus starp sistēmām, sinhronizācijas stāvokli, kartēšanas metadatus un operatīvo audita žurnālu.

Ko šeit patiesībā nozīmē "mākoņgrāmatvedības API"

Šī frāze parasti apzīmē mitinātas grāmatvedības platformas, piemēram, QuickBooks Online, Xero, Sage, Zoho Books vai kādas reģionālas sistēmas API. Tas var nozīmēt arī vienoto grāmatvedības API (unified accounting API), kas normalizē vairāku pakalpojumu sniedzēju darbību aiz vienas saskarnes.

Ir vērts būt precīziem, jo ieviešana atšķiras atkarībā no mērķa. Rēķinu nolasīšana pārskatu sagatavošanai nav tas pats, kas rēķinu izveide no SaaS aktivitātēm, rēķinu (bills) grāmatošana, klientu un produktu sinhronizācija, grāmatojumu rakstīšana vai pilnvērtīgas divvirzienu sinhronizācijas nodrošināšana. Pirms pieskaraties jebkuram galapunktam, izlemiet, ko tieši jūs būvējat.

Šim rakstam ir svarīga vēl viena atšķirība. Maksājumu API pārvieto naudu. Bankas API pavelk konta datus. Rēķinu izrakstīšanas API var izveidot dokumentus, neatklājot virsgrāmatu. Iegultā grāmatvedības virsgrāmata (embedded ledger) ir kas cits: SaaS uzņēmums pats ir grāmatvedības dzinēja īpašnieks. Šī pēdējā pieeja ir tā, kurā atrodas Nordlet. Tā vietā, lai savienotu jūsu produktu ar klienta ārējo grāmatvedību, Nordlet nodrošina platformām un tirdzniecības vietām reālas divkāršā ieraksta virsgrāmatas, pret auditu drošu nemainīgu reģistru, ES PVN apstrādi un izmaksas to pašu produktā, izmantojot API orientētu dizainu ar tipizētiem SDK un webhook. Ja esat tirdzniecības vieta (marketplace), kas lemj, vai integrēt klienta grāmatvedības sistēmu vai pašam uzturēt grāmatvedību, tā ir reāla izvēle krustcelēs, un mēs pie tā vēl atgriezīsimies.

Vairākīrnieku arhitektūra (multi-tenancy): katrs savienojums jāierobežo divreiz

SaaS produktā viena lietojumprogramma izveido savienojumu ar daudzām klientu organizācijām. Katram savienojumam jābūt ierobežotam gan ar SaaS īrnieku, gan ar pakalpojumu sniedzēja organizācijas identifikatoru, piemēram, Xero īrnieka ID vai QuickBooks uzņēmuma (realm) ID.

Nepiesaistiet savienojumus tikai OAuth lietotāja ID. Viens lietotājs var autorizēt vairākas grāmatvedības organizācijas, un vienu organizāciju laika gaitā var no jauna savienot dažādi lietotāji. Ja šeit kļūdīsieties, jūs agrāk vai vēlāk ievietosiet viena klienta rēķinu cita klienta grāmatvedībā, un tā nav kļūda, ko var nemanāmi novērst.

Pirmais arhitektoniskais lēmums: tiešais savienotājs, vienotais API vai iegultā virsgrāmata

Tiešās pakalpojumu sniedzēju integrācijas

Tiešā integrācija sniedz vislielāko kontroli: pakalpojumu sniedzējam raksturīgas funkcijas, pielāgoti lauki, kļūdu apstrāde, sinhronizācijas biežums, datu glabāšana un izmaksu struktūra. Taču cena ir reāla. Katrs pakalpojums ievieš savu OAuth plūsmu, shēmu, īpatnības, ierobežojumus, webhook darbību, sertifikāciju un pastāvīgu uzturēšanu.

Vienotie grāmatvedības API

Vienotais API piedāvā vienu saskarni vairākām grāmatvedības sistēmām, normalizējot tādus elementus kā klienti, rēķini, piegādātāji, konti, maksājumi un produkti. Tas var saīsināt sākotnējo izstrādes laiku. Tomēr tas nenovērš integrācijas sarežģītību, un uzskatīt, ka tas tā ir, ir izplatīta kļūda.

Pirms saistību uzņemšanās pajautājiet: kuri pakalpojumu sniedzēji un operācijas tiek atbalstīti? Vai rakstīšana darbojas, vai tikai lasīšana? Vai rakstīšana ir sinhrona vai rindā? Vai pakalpojuma specifiskie lauki ir pieejami, izmantojot caurlaidi (passthrough)? Vai dati tiek kešatmiņā un cik tie ir svaigi? Kurš risina pakalpojumu sniedzēja pārtraukumus un API izmaiņas? Vai cenas ir par izsaukumu, par saistīto kontu, par ierakstu vai platformas maksa? Vai varat eksportēt savas kartēšanas un tīri atvienoties? "Vienots" reti nozīmē "funkcionāli identisks visiem pakalpojumu sniedzējiem".

Iegultā virsgrāmata

Ja jūsu platformas galvenā problēma ir grāmatvedības nodrošināšana lietotājiem, nevis tās atspoguļošana viņu esošajā grāmatvedībā, iegultā virsgrāmata maina aprēķinus. Tirgum ar tūkstošiem pārdevēju vai SaaS produktam, kam nepieciešama auditam gatava ES PVN un katrai valstij atbilstoša likumdošana, ir izdevīgāk pašam pārvaldīt grāmatvedības dzinēju, nevis pieslēgt N ārējos savienotājus. Tā ir Nordlet pozīcija: reālas grāmatas kā API, nemainīgs divkāršais ieraksts, katrai valstij specifisks PVN ar VIES validāciju un i.SAF reģistru ģenerēšanu, SEPA eksports un pārskatu eksports XLSX, PDF vai JSON formātā tieši jūsu produktā, nevis trešās puses norēķinos.

Lēmuma pieņemšanas likums, ko izmantoju es:

Situācija	Vispiemērotākais variants
Viens grāmatvedības pakalpojums dominē jūsu klientu bāzē; specifiska uzvedība ir centrālā	Tiešais savienotājs
Plašs pakalpojumu sniedzēju pārklājums un nonākšana tirgū ir svarīgāka par kontroli	Vienotais API
Jūs esat platforma vai tirdzniecības vieta, kurai nepieciešams pašai uzturēt grāmatvedību, ar ES PVN un audita žurnāliem	Iegultā virsgrāmata (Nordlet)
Jaukta situācija	Hibrīds: vienotais API standarta plūsmām, tiešie savienotāji stratēģiskajiem pakalpojumiem

Ieteicamā integrācijas arhitektūra

Izolējiet integrāciju no pamatbiznesa loģikas

Neizkliedējiet pakalpojumu sniedzēju izsaukumus pa rēķinu izrakstīšanu, pasūtījumiem, abonementiem un atskaitēm. Izveidojiet īpašu integrācijas servisu, kurā atrodas pakalpojumu sniedzēju adapteri, OAuth savienojumu pārvaldība, kanoniskie modeļi, ID kartēšanas, sinhronizācijas darbi un rindas, webhook galapunkti, atkārtoto mēģinājumu un neatgriezeniski kļūdaino ziņojumu (dead-letter) apstrāde, audita žurnāli un saskaņošanas rīki. Tas neļauj Xero vai QuickBooks lauku nosaukumiem noplūst jūsu domēna modelī.

Definējiet šauru kanonisko modeli

Modelējiet tikai tās plūsmas, kuras atbalstāt. Tipiski objekti: klients, produkts vai pakalpojums, rēķins, rēķina rinda, maksājums, kredītrēķins, piegādātājs, konts, nodokļa likme, valūta, grāmatojums.

Saglabājiet atšķirības, kas ietekmē grāmatvedību. Neaplīdziniet melnrakstu, apstiprinātu un iegrāmatotu statusu, summas ar vai bez nodokļa, kredītrēķinus un negatīvus rēķinus, maksājuma sadali un maksājuma eksistenci, vai klienta rēķina numuru un pakalpojumu sniedzēja objekta ID. Katram ierakstam jāsatur SaaS ID, pakalpojumu sniedzēja ID, pakalpojuma nosaukums un API versija, patiesības avota (source-of-truth) rādītājs, statuss, laika zīmogi, pēdējās sinhronizācijas laiks, ārējā atsauce un kļūdu/saskaņošanas statuss.

Uzturiet skaidras kartēšanas tabulas

Kartējiet SaaS īrnieku uz grāmatvedības organizāciju, SaaS klientu uz pakalpojumu sniedzēja kontaktu, SaaS produktu uz pakalpojumu sniedzēja preci vai kontu, SaaS rēķinu uz pakalpojumu sniedzēja rēķinu, SaaS maksājumu uz pakalpojumu sniedzēja maksājumu, nodokļu kategoriju uz nodokļa kodu un ieņēmumu kategoriju uz virsgrāmatas kontu.

Nekad neizmantojiet vārdus vai e-pasta adreses kā pastāvīgus identifikatorus. Vārdi mainās, pastāv dublikāti, un divi klienti var dalīt vienu e-pastu. Saglabājiet pakalpojumu sniedzēja nemainīgo ID un paturiet oriģinālo SaaS ID.

Pievienojiet stāvokļu mašīnas (state machines)

Piešķiriet savienojumam skaidrus statusus: nav savienots, autorizācija gaidīšanas režīmā, savienots, sākotnējā sinhronizācija gaida, notiek sinhronizācija, veselīgs, pārsniegts pieprasījumu limits, nepieciešama atkārtota autorizācija, pakalpojumu sniedzējs nav pieejams, atvienots, neatgriezeniski kļūdains. Piešķiriet ierakstiem savus statusus: gaida, nosūtīts, apstiprināts, kļūda ar atkārtotu mēģinājumu, kļūda, kur nepieciešama lietotāja rīcība, saskaņots, konstatēts konflikts. Binārs karodziņš "savienots/nav savienots" jūsu atbalsta komandai nesniedz nekādu noderīgu informāciju.

OAuth un savienojuma izveide

Izmantojiet autorizācijas koda plūsmu (authorization code flow). Klients noklikšķina uz "Savienot", jūsu serveris izveido īslaicīgu autorizācijas darījumu, klients autentificējas pakalpojumu sniedzējā un piešķir tiesības (scopes), jūs apmaināt kodu pret marķieriem, atklājat autorizēto organizāciju, saglabājat savienojumu pret pareizo īrnieku un ievietojat rindā sākotnējo sinhronizāciju.

Rūpīgi pārbaudiet atgriezenisko zvanu (callback): state pret servera puses darījumu, precīzu pāradresācijas URI, pakalpojumu sniedzēja emitentu un īrnieka kontekstu. RFC 9700, OAuth 2.0 Security Best Current Practice formalizē pašreizējos ieteikumus: izmantojiet PKCE ar autorizācijas koda plūsmām, izvairieties no netiešām (implicit) un paroles grantu plūsmām, kā arī izmantojiet precīzu pāradresācijas URI sakritību.

Pieprasiet minimālās nepieciešamās tiesības (least-privilege scopes). Izmantojiet tikai lasīšanu, ja nav nepieciešams rakstīt. Tiesību modeļi mainās, tāpēc nekopējiet vecos piemērus. Xero OAuth dokumentācija norāda, ka plašas grāmatvedības tiesības tiek aizstātas ar granulētām, un jaunām lietotnēm kopš 2026. gada marta tiek piešķirtas granulētas tiesības, savukārt plašās tiesības paliks pieejamas līdz 2027. gada septembrim.

Glabājiet marķierus tikai servera pusē. Nekad nepaveriet tos pārlūkprogrammas JavaScript, mobilajiem klientiem, frontend žurnāliem, analītikai vai klienta puses kļūdu ziņojumiem. Šifrējiet datus datu glabāšanā, aizklājiet tos žurnālos un saglabājiet katra savienojuma metadatus: šifrētus piekļuves un atsvaidzināšanas marķierus, derīguma termiņu, pakalpojumu sniedzēja organizācijas ID, piešķirtās tiesības, izdošanas laiku, pēdējo veiksmīgo atsvaidzināšanu un atsaukšanas statusu.

Atsvaidzināšanas marķiera rotācija ir vieta, kur sistēmas lūzt

Atsvaidzināšanas atbilde var atgriezt jaunu atsvaidzināšanas marķieri. Jums jaunākā vērtība ir jāsaglabā atomāri, pretējā gadījumā jūs bloķēsiet klientu. Saskaņā ar Xero izstrādātāju FAQ, katra atsvaidzināšana ģenerē jaunu atsvaidzināšanas marķieri, marķieri ir derīgi līdz 60 dienām, un pastāv 30 minūšu labvēlības periods, lai mēģinātu vēlreiz ar esošo marķieri, ja atbilde ir pazaudēta. QuickBooks Online iesaka izstrādātājiem saglabāt jaunāko atsvaidzināšanas marķieri no pēdējās atbildes: marķieri ir derīgi līdz 100 dienām, un to vērtība var rotēt tik bieži kā reizi 24 stundās.

Praksē: izmantojiet katra savienojuma atsvaidzināšanas slēdzi, aizvietojiet atsvaidzināšanas marķieri atomāri, apstrādājiet īslaicīgas marķiera galapunkta kļūdas ar atkārtotiem mēģinājumiem, nodrošiniet skaidru atkārtotas autorizācijas stāvokli un nekad neveiciet atsvaidzināšanu katrā API izsaukumā, ja derīgs piekļuves marķieris vēl pastāv.

Sākotnējā sinhronizācija

Veiciet sākotnējo sinhronizāciju kā fona darbu. Nebloķējiet ar to OAuth atgriezenisko zvanu vai lietotāja saskarni.

Izturīga secība: iegūt organizācijas metadatus, ielādēt kontus, nodokļu likmes, valūtas, kontaktus un preces, saglabāt pakalpojumu sniedzēja ID un kartēšanas, importēt tikai to vēsturisko logu, kas produktam nepieciešams, ievietot rindā atkarīgos ierakstus atkarību secībā, ierakstīt kontrolpunktu un atzīmēt savienojumu par veselīgu tikai pēc validācijas.

Atkarību secībai ir nozīme. Rēķinam vispirms var būt nepieciešams kontakts, prece, ieņēmumu konts, nodokļa kods un valūta. Neveidojiet dublikātus akli. Meklējiet sakritību pēc saglabātā ārējā ID, klienta norādītas atsauces, definēta salīdzināšanas noteikuma vai skaidras lietotāja izvēles neskaidros gadījumos.

Inkrementālā sinhronizācija

Uzskatiet webhook par signāliem, nevis autoritatīviem ierakstiem

Webhook parasti norāda, ka kaut kas ir mainījies. Pārbaudiet parakstu, reģistrējiet neapstrādāto notikumu, ātri atgrieziet nepieciešamo veiksmes atbildi, novērsiet dublikātus, ielieciet rindā turpmāko pieprasījumu, ielādējiet pašreizējo objektu no pakalpojuma sniedzēja, darījuma veidā lietojiet atjauninājumu, atjauniniet kontrolpunktu un novirziet kļūdas uz atkārtotiem mēģinājumiem vai saskaņošanu. Tas palīdz tikt galā ar nepilnīgiem datu kopumiem un nepareizā secībā saņemtiem notikumiem.

Pakalpojumu sniedzēju noteikumi atšķiras, tāpēc neapsoliet vienu universālu uzvedību. Xero webhook satur HMAC-SHA256 parakstu x-xero-signature galvenē, pieprasa HTTPS, mēģina atkārtot ar samazinātu biežumu līdz 24 stundām, pēc atkārtotām kļūdām var tikt atspējoti un var saglabāt notikumus līdz 31 dienai atkārtotai atskaņošanai pēc sistēmas atjaunošanas. QuickBooks Online veic pārbaudi ar HMAC-SHA256 un verifikācijas marķieri, gaida HTTP 200 trīs sekundju laikā un atkārto mēģinājumus pēc fiksēta grafika, kas galu galā pāriet sešu stundu intervālos, Intuit iesakot izmantot asinhrono apstrādi.

Dublikātu novēršana un idepotence (idempotency)

Vismaz vienas reizes piegāde (at-least-once) ir standarts. Sagaidiet dubultus webhook, atkārtotus mēģinājumus pēc taimauta, kad ieraksts patiesībā ir izdevies, mainītas notikumu secības un dubultus lietotāja klikšķus. Izmantojiet pakalpojumu sniedzēja notikuma ID, ja tas ir pieejams, unikālu notikuma atslēgu ilglaicīgā krātuvē, operācijas ID, kas ģenerēts pirms katras rakstīšanas, datu bāzes unikālos ierobežojumus, upsert semantiku un saskaņošanas vaicājumu pēc neskaidriem taimautiem.

Neuzskatiet, ka katrs grāmatvedības API piedāvā vietējās idepotences atslēgas. Ja pakalpojumu sniedzējs to nedara, saglabājiet iekšējo operācijas atslēgu un pārbaudiet, vai gaidītais attālinātais objekts jau pastāv, pirms mēģināt vēlreiz. Šeit lieliski noder Stripe idepotento pieprasījumu modeļi un vispārīgie webhook idepotences ieteikumi.

Aptauja (polling) un izmaiņu noteikšana

Apvienojiet webhook ar periodisku aptauju. Webhook mēdz tikt atspējoti, aizkavēti, pazaudēti nepareizas konfigurācijas dēļ vai ierobežoti noteiktiem objektiem. Xero atbalsta If-Modified-Since galveni izmaiņām pēc UTC laika zīmoga, taču dokumentācija brīdina, ka ne katras izmaiņas atjaunina UpdatedDateUTC, tāpēc daži daļēji apmaksāti darījumi un kontakta lauki caur šo filtru nebūs redzami. QuickBooks Online izmaiņu datu uztveršana (Change Data Capture) izseko izmaiņas no iepriekšējām 30 dienām, ierobežo atbildes līdz 1 000 objektiem, atgriež dzēstos elementus ar Deleted statusu un vislabāk darbojas ar īsākiem aptaujas logiem.

Glabājiet katram pakalpojumu sniedzējam un īrniekam kontrolpunktu un izmantojiet pārklāšanās logus (overlap windows). Pieprasiet izmaiņas no brīža, kas ir nedaudz pirms pēdējā kontrolpunkta, un pēc tam novērsiet dublikātus pēc pakalpojuma sniedzēja ID un modifikācijas versijas. Tas aizsargā pret sistēmas pulksteņu nobīdi un daļējām kļūdām.

Grāmatvedībai specifiska datu integritāte

Šī ir daļa, kas atšķir strādājošu integrāciju no uzticamas.

Nodokļu uzvedība nav savstarpēji aizvietojama. Xero dokumentācija norāda, ka rēķini, kredītrēķini un pirkuma pasūtījumi pēc noklusējuma neietver nodokli, ja LineAmountTypes nav iestatīts, ieņēmumu kvītis un bankas darījumi pēc noklusējuma ietver nodokli, savukārt manuālie žurnāli pēc noklusējuma ir bez nodokļa. Izmantojiet TaxType lauku, nevis nodokļa likmes nosaukumu. Nekad nepaļaujieties uz to, ka "20% PVN" unikāli identificē nodokļa kodu; tas var mainīties atkarībā no valsts, darījuma veida, spēkā stāšanās datuma un organizācijas konfigurācijas. Šeit ES starpvalstu PVN aprēķināšana ar rokām kļūst dārga, un šeit iegultā virsgrāmata ar iebūvētu atbilstību katrai valstij attaisno savu vietu.

Naudas aprēķiniem izmantojiet decimālskaitļus vai fiksētas precizitātes aritmētiku, nekad neizmantojiet bināro peldošo komatu (floating point). Saglabājiet valūtas kodu un precizitāti, vienības summu, daudzumu, atlaidi, nodokļa summu, neto, bruto un valūtas maiņas kursu. Skaidri izlemiet, vai sūtāt summas rindas līmenī un ļaujat pakalpojumu sniedzējam aprēķināt kopsummas, vai sūtāt iepriekš aprēķinātu kopsummu. Šo divu pieeju sajaukšana rada noapaļošanas atšķirības, ko jūsu grāmatvedis noteikti atradīs.

Atsaucieties uz virsgrāmatas kontiem, izmantojot pakalpojumu sniedzēja ID vai kodu, nevis parādāmo nosaukumu. Pirms ieraksta veikšanas pārbaudiet, vai konti, nodokļu kodi, klienti, preces un valūta ir aktīvi un tiek atbalstīti. Neizdevies rēķina ieraksts parasti ir kartēšanas vai konfigurācijas problēma, nevis īslaicīga API kļūda, tāpēc lietotāja saskarnei vajadzētu paskaidrot risinājumu, nevis parādīt ziņojumu "sinhronizācija neizdevās".

Neuzskatiet objektus par savstarpēji aizvietojamiem. "Maksājums" var nozīmēt kvīti, summas sadali, depozītu, bankas darījumu vai grāmatojumu. SaaS "abonements" var precīzi neatbilst grāmatvedības "rēķinam". Pirms izvēlaties API objektu, definējiet grāmatvedības notikumu, kuru vēlaties atspoguļot. Skatiet Xero maksājumu dokumentāciju, lai redzētu, kā viens pakalpojumu sniedzējs to modelē.

Pieprasījumu limiti (rate limits) un versiju kontrole

Limiti parasti tiek noteikti katram īrniekam, organizācijai, lietotnei vai to kombinācijai. Saskaņā ar Xero limitu FAQ: pieci vienlaicīgi pieprasījumi vienam īrniekam, 60 minūtē vienam īrniekam, 5 000 dienā vienam īrniekam un 10 000 minūtē visai lietotnei, izmantojot atlikušo limitu galvenes un Retry-After kļūdas 429 gadījumā. QuickBooks Online dokumentē 500 pieprasījumus minūtē un 10 sekundē uz vienu uzņēmuma (realm) ID, ar pakešu (batch) galapunktu, kas atbalsta līdz 30 operācijām vienā pieprasījumā.

Izveidojiet katra īrnieka pieprasījumu limitu kontroli, globālu ierobežošanu, eksponenciālu aizturi ar gadījuma nobīdi (jitter), ievērojiet Retry-After, ierobežojiet vienlaicīgo darbību skaitu, lapošanu (pagination) un mērījumus kļūdām 429 un atlikušajai kvotai. Neizmantojiet neierobežotu paralēlismu importēšanai; viens liels klients var noplicināt visus pārējos darbus šim īrniekam.

Fiksējiet vai pārvaldiet API versijas. QuickBooks Online pēc noklusējuma izmanto apakšversiju 75, ja nav norādīts citādi. Centralizējiet versijas konfigurācijā, palaidiet līguma testus pret smilšu kastēm (sandboxes), uzraugiet izlaiduma piezīmes un uztveriet nezināmus atbildes laukus kā savietojamus uz priekšu. Smilšu kastes neatveidos visus ražošanas vides apstākļus, tāpēc pirms palaišanas testējiet atvienošanu, atkārtotu savienošanu, atsaukto piekrišanu, beigušos marķierus, limitus un pakalpojumu sniedzēja puses labojumus.

Ko es būvētu vispirms

Ja es to sāktu rīt, šādā secībā:

1. Definējiet precīzu grāmatvedības plūsmu: kurus notikumus un objektus jūs nolasāt vai ierakstāt.
2. Izvēlieties pakalpojumu sniedzēja stratēģiju: tiešais, vienotais, iegultais vai hibrīds.
3. Izveidojiet īrnieka līmeņa savienojuma modeli ar pakalpojumu sniedzēja organizācijas ID, tiesībām, statusu un marķiera metadatiem.
4. Ieviesiet OAuth ar autorizācijas koda plūsmu, PKCE, stāvokļa validāciju, minimālajām tiesībām un servera puses marķieru glabāšanu.
5. Izveidojiet vienu pakalpojumu sniedzēja adapteri aiz stabilas iekšējās saskarnes.
6. Izveidojiet ID kartēšanas, pamatojoties uz nemainīgiem pakalpojumu sniedzēja ID.
7. Vispirms ieviesiet lasīšanu; importējiet references datus pirms jebkādas rakstīšanas.
8. Pievienojiet sākotnējās sinhronizācijas darbu ar lapošanu, limitu kontroli, kontrolpunktiem un atkarību secību.
9. Ieviesiet vienu šauru rakstīšanas darbību (izveidot rēķinu) tikai pēc tam, kad klienta, preces, nodokļa un konta kartēšanas ir apstiprinātas.
10. Padariet rakstīšanu drošu pret atkārtotiem mēģinājumiem, izmantojot iekšējos operāciju ID, unikalitātes ierobežojumus un attālinātā stāvokļa pārbaudes.
11. Pievienojiet parakstītus webhook, kas ātri apstiprina saņemšanu un tiek apstrādāti asinhroni.
12. Pievienojiet aptauju un saskaņošanu, lai webhook ir paātrinājums, nevis vienīgais patiesības avots.
13. Mērķtiecīgi testējiet kļūdu scenārijus.
14. Pievienojiet atbalsta un audita rīkus, kas padara kļūdas izskaidrojamas un labojamas.
15. Pakāpeniski paplašiniet objektu pārklājumu.

FAQ

Vai man vajadzētu izmantot vienoto API vai būvēt tiešos savienotājus?

Izmantojiet tiešo savienotāju, ja viens pakalpojumu sniedzējs dominē starp jūsu klientiem vai specifiska uzvedība ir centrālā. Apsveriet vienoto API, ja plašs pārklājums un ātrums ir svarīgāki par kontroli. Ja jūsu patiesā vajadzība ir pašam uzturēt grāmatvedību, nevis sinhronizēt ar klienta sistēmu, neviena no šīm opcijām neatbild uz jautājumu; tā vietā aplūkojiet tādu iegulto virsgrāmatu kā Nordlet.

Vai webhook ir pietiekami, lai uzturētu sinhronizāciju?

Nē. Webhook mēdz tikt atspējoti, aizkavēti vai pazaudēti, un dati var būt nepilnīgi vai nepareizā secībā. Uztveriet tos kā izmaiņu signālus, pēc tam ielādējiet pašreizējo objektu un papildiniet to ar periodisku aptauju un saskaņošanu.

Kā novērst situāciju, kad atsvaidzināšanas marķiera kļūdas bloķē klientus?

Atomāri saglabājiet jaunāko atsvaidzināšanas marķieri katrā atsvaidzināšanas reizē, izmantojiet katra savienojuma slēdzi, atkārtojiet īslaicīgas marķiera galapunkta kļūdas un nodrošiniet skaidru atkārtotas autorizācijas stāvokli. Xero 30 minūšu labvēlības periods palīdz, taču tieši atomārā saglabāšana ir tas, kas jūs glābj.

Vai varu saskaņot ierakstus pēc klienta vārda vai e-pasta?

Nē, nevis kā pastāvīgu identifikatoru. Vārdi mainās, rodas dublikāti, un divi klienti var dalīt vienu e-pastu. Saglabājiet pakalpojumu sniedzēja nemainīgo ID un turiet savu SaaS ID tam blakus.

Papildu literatūra

• Xero OAuth 2.0 pārskats
• Xero API limiti
• Stripe idepotentie pieprasījumi
• Nordlet API dokumentācija