Kaip integruoti debesų kompiuterijos buhalterinės apskaitos API į SaaS platformą

Praktiškas vadovas, kaip sukurti kelių nuomininkų (multi-tenant) apskaitos integraciją, kuri atlaiko OAuth, demonstracinius pranešimus (webhooks), mokesčių taisykles ir suderinimą, nepažeisdama didžiosios knygos (ledger).

Dauguma komandų, nusprendusių „pridėti apskaitą“ prie savo SaaS produkto, pradeda nuo HTTP kliento prijungimo prie paslaugų teikėjo galinio taško ir sąskaitos faktūros išsiuntimo. Tai veikia demonstracijoje. Tai sugriūva pirmą kartą klientui sujungus dvi apskaitos organizacijas, pirmą kartą demonstraciniam pranešimui (webhook) atkeliavus du kartus ir pirmą kartą atnaujinimo prieigos raktui (refresh token) pasikeitus bei pasimetus užklausos viduryje. Ilgaamžė šio darbo versija nėra kliento aplikacija. Tai yra integracijos sluoksnis.

Šis sluoksnis privalo valdyti nuomininkų ryšius, prieigos raktų saugojimą ir keitimą, konkrečiam teikėjui būdingas apskaitos taisykles, įrašų susiejimą, pradinį ir papildomą sinchronizavimą, demonstracinių pranešimų (webhooks) priėmimą su pakartojimais ir dublikatų šalinimu, dažnio limito ribas (rate limits), versijavimą ir audito seką, kurią jūsų palaikymo komanda gali perskaityti 2 val. nakties. Šiame straipsnyje apžvelgiama ši architektūra ir svarbiausi sprendimai.

Naudingas minties modelis:

SaaS produktas → apskaitos integracijos paslauga → teikėjo adapteris (arba vieningas API) → asinchroninis sinchronizavimas ir suderinimas

Apskaitos sistema lieka didžiosios knygos (ledger) objektų apskaitos šaltiniu: sąskaitos, mokesčių kodai, užregistruotos operacijos, žurnalo įrašai. Jūsų SaaS platforma išlaiko stabilius tarpusavio identifikatorius, sinchronizavimo būseną, susiejimo metaduomenis ir operacinį audito žurnalą.

Ką čia iš tikrųjų apima „debesų kompiuterijos buhalterinės apskaitos API“

Ši frazė paprastai reiškia talpinamos buhalterinės apskaitos platformos, tokios kaip QuickBooks Online, Xero, Sage, Zoho Books ar regioninė sistema, API. Tai taip pat gali reikšti vieningą apskaitos API (unified accounting API), kuris normalizuoja kelis teikėjus po viena sąsaja.

Verta būti tiksliems, nes įgyvendinimas skiriasi priklausomai nuo tikslo. Sąskaitų faktūrų skaitymas ataskaitoms teikti nėra tas pats darbas, kaip sąskaitų faktūrų kūrimas iš SaaS veiklos, pirkimo sąskaitų faktūrų (bills) registravimas, klientų ir produktų sinchronizavimas, žurnalo įrašų rašymas arba tikro dvipusio sinchronizavimo vykdymas. Nuspręskite, ką iš to kuriate, prieš liesdami bet kokį galinį tašką (endpoint).

Šiam straipsniui svarbus dar vienas skirtumas. Mokėjimų API perkelia pinigus. Bankininkgybės API paima sąskaitos duomenis. Sąskaitų faktūrų išrašymo API gali kurti dokumentus neatskleisdama didžiosios knygos (general ledger). Įterptoji apskaitos didžioji knyga (embedded accounting ledger) yra visai kas kita: SaaS įmonė pati valdo apskaitos varikliuką. Šis paskutinis požiūris yra ten, kur yra Nordlet. Vietoj to, kad prijungtumėte savo produktą prie kliento išorinės buhalterijos, Nordlet suteikia platformoms ir prekyvietėms (marketplace) tikras dvejybinio įrašo (double-entry) knygas, nekeičiamą auditui paruoštą didžiąją knygą (ledger), ES PVM tvarkymą ir išmokėjimus jų pačių produkte per API pirmo tipo dizainą su tipizuotais SDK ir demonstraciniais pranešimais (webhooks). Jei esate prekyvietė, sprendžianti, ar integruoti kliento apskaitos sistemą, ar patiems tvarkyti buhalteriją, tai yra tikra kryžkelė, ir mes prie jos dar sugrįšime.

Kelių nuomininkų architektūra (multi-tenancy): dukart apibrėžkite kiekvieną ryšį

SaaS produkte viena programa prisijungia prie daugelio klientų organizacijų. Kiekvienas ryšys turi būti apribotas tiek SaaS nuomininko, tiek teikėjo organizacijos identifikatoriumi, pavyzdžiui, Xero nuomininko ID arba QuickBooks srities (realm) ID.

Nenustatykite ryšių rakto tik pagal OAuth vartotojo ID. Vienas vartotojas gali autorizuoti kelias apskaitos organizacijas, o vieną organizaciją laikui bėgant iš naujo gali prijungti skirtingi vartotojai. Jei padarysite klaidą, galiausiai įrašysite vieno kliento sąskaitą faktūrą į kito kliento buhalteriją, o tai nėra klaida, iš kurios galima tyliai atsigauti.

Pirmasis architektūrinis sprendimas: tiesioginis jungiklis, vieningasis API ar įterptoji didžioji knyga (ledger)

Tiesioginės teikėjo integracijos

Tiesioginė integracija suteikia daugiausia kontrolės: konkrečiam teikėjui būdingas funkcijas, pasirinktinius laukus, klaidų valdymą, sinchronizavimo dažnumą, duomenų saugojimą ir kainodaros struktūrą. Kaina yra reali. Kiekvienas teikėjas atsineša savo OAuth srautą, schemą, ypatybes, dažnio limitus, demonstracinių pranešimų (webhooks) elgseną, sertifikavimą ir nuolatinę priežiūrą.

Vieningos apskaitos API (unified accounting APIs)

Vieningas API siūlo vieną sąsają keliose apskaitos sistemose, normalizuodamas tokius objektus kaip klientai, sąskaitos faktūros, tiekėjai, sąskaitos, mokėjimai ir produktai. Tai gali sutrumpinti pradinį kūrimo laiką. Tai nepašalina integracijos sudėtingumo, o elgimasis taip, tarsi pašalintų, yra dažna klaida.

Prieš įsipareigodami paklauskite: kurie teikėjai ir operacijos yra palaikomi? Ar įrašymas veikia, ar tik skaitymas? Ar įrašymas yra sinchroninis, ar eilėje? Ar teikėjui būdingi laukai pasiekiami per tiesioginį perdavimą (passthrough)? Ar duomenys kaupiami talpykloje ir kiek jie švieži? Kas sprendžia teikėjo veiklos sutrikimus ir API pakeitimus? Ar kainodara taikoma už užklausą, už susietą paskyrą, už įrašą, ar tai platformos mokestis? Ar galite eksportuoti savo susiejimus ir švariai atsijungti? „Vieningas“ retai reiškia „su vienodomis funkcijomis pas visus teikėjus“.

Įterptoji didžioji knyga (embedded ledger)

Jei pagrindinė jūsų platformos problema yra apskaitos tvarkymas jūsų vartotojams, o ne jos atspindėjimas jų esamoje buhalterijoje, įterptoji didžioji knyga pakeičia apskaičiavimą. Prekyvietei su tūkstančiais pardavėjų arba SaaS produktui, kuriam reikalingas auditui paruoštas ES PVM ir atitiktis kiekvienoje šalyje, geriau pasitarnaus pačių valdomas apskaitos variklis, nei N išorinių jungčių prijungimas. Tai yra „Nordlet“ pozicionavimas: tikros knygos kaip API, nekintamas dvejybinis įrašas (double-entry), PVM pagal šalis su VIES patvirtinimu ir i.SAF registro generavimu, SEPA eksportas ir ataskaitų eksportavimas XLSX, PDF arba JSON formats, visa tai jūsų produkte, o ne trečiosios šalies atsiskaitymo sistemoje.

Sprendimo taisyklė, kuria vadovaujuosi:

Situacija	Geriausiai tinka
Viena apskaitos sistema dominuoja jūsų klientų bazėje; teikėjo specifinė elgsena yra esminė	Tiesioginis jungiklis
Platus teikėjų palaikymas ir greitis rinkai yra svarbesni už kontrolę	Vieningas API
Esate platforma arba prekyvietė, kuriai reikia valdyti ir turėti nuosavą buhalteriją su ES PVM ir audito sekomis	Įterptoji didžioji knyga (Nordlet)
Mišri realybė	Hibridinė: vieningas API įprastiems srautams, tiesioginiai jungikliai strateginiams teikėjams

Rekomenduojama integracijos architektūra

Izoliuokite integraciją nuo pagrindinės verslo logikos

Neskleiskite teikėjo iškvietimų per atsiskaitymus, užsakymus, prenumeratas ir ataskaitas. Sukurkite dedikuotą integracijos paslaugą, kurioje būtų teikėjų adapteriai, OAuth ryšio valdymas, kanoniniai modeliai, ID susiejimai, sinchronizavimo užduotys ir eilės, demonstracinių pranešimų (webhooks) galiniai taškai, pakartojimų ir nepasiekiamų pranešimų (dead-letter) valdymas, audito žurnalai ir suderinimo įrankiai. Tai neleidžia Xero arba QuickBooks lauko pavadinimui nutekėti į jūsų domeno modelį.

Apibrėžkite siaurą kanoninį modelį

Modeliuokite tik tuos darbo procesus, kuriuos palaikote. Tipiniai objektai: klientas, produktas arba paslaugos prekė, sąskaita faktūra, sąskaitos faktūros eilutė, mokėjimas, kreditinė sąskaita, tiekėjas, sąskaita (account), mokesčio tarifas, valiuta, žurnalo įrašas.

Išsaugokite skirtumus, kurie turi įtakos apskaitai. Nesuvienodinkite juodraščio (draft), patvirtinto (approved) ir užregistruoto (posted), sumų su mokesčiais ir be mokesčių, kreditinių sąskaitų faktūrų ir neigiamų sąskaitų faktūrų, mokėjimo paskirstymo ir mokėjimo egzistavimo, arba klientui rodomo sąskaitos faktūros numerio ir teikėjo objekto ID. Kiekvienas įrašas turėtų turėti SaaS ID, teikėjo ID, teikėjo pavadinimą ir API versiją, tiesos šaltinio (source-of-truth) rodiklį, būseną, laiko žymas, paskutinio sinchronizavimo laiką, išorinę nuorodą ir klaidos / suderinimo būseną.

Palaikykite aiškias susiejimo lenteles

Susiekite SaaS nuomininką su apskaitos organizacija, SaaS klientą su teikėjo kontaktu, SaaS produktą su teikėjo preke arba sąskaita, SaaS sąskaitą faktūrą su teikėjo sąskaita faktūra, SaaS mokėjimą su teikėjo mokėjimu, mokesčio kategoriją su mokesčio kodu ir pajamų kategoriją su didžiosios knygos sąskaita.

Niekada nenaudokite vardų ar el. pašto adresų kaip nuolatinių identifikatorių. Vardai keičiasi, pasitaiko dublikatų, du klientai gali dalintis vienu el. paštu. Saugokite teikėjo nekintamą ID ir išsaugokite originalų SaaS ID.

Pridėkite būsenos mašinas (state machines)

Suteikite ryšiui aiškias būsenas: neprijungtas, autorizacija laukiama, prijungtas, pradinio sinchronizavimo laukiama, sinchronizuojama, sveikas, apribotas dažnis (rate limited), reikalingas pakartotinis autorizavimas, teikėjas nepasiekiamas, atsijungęs, nepataisomai sugriuvęs. Suteikite įrašams jų pačių būsenas: laukia, išsiųsta, patvirtinta, nepavyko-pakartoti, nepavyko-reikia-vartotojo-veiksmo, suderinta, aptiktas konfliktas. Dvejetainė vėliavėlė „prijungtas / neprijungtas“ jūsų palaikymo komandai nepasako nieko naudingo.

OAuth ir ryšio diegimas (onboarding)

Naudokite autorizacijos kodo srautą. Klientas spusteli „Prisijungti“, jūsų serveris sukuria trumpalaikę autorizacijos operaciją, klientas autentifikuojasi pas teikėją ir suteikia prieigos teises (scopes), jūs iškeičiate kodą į prieigos raktus, aptinkate autorizuotą organizaciją, išsaugote ryšį atitinkamam nuomininkui ir įtraukite į eilę pradinį sinchronizavimą.

Atidžiai patvirtinkite atgalinį iškvietimą (callback): state palyginkite su serverio pusės operacija, tikslų peradresavimo URI, teikėjo išdavėją ir nuomininko kontekstą. RFC 9700, OAuth 2.0 saugumo geriausia dabartinė praktika (OAuth 2.0 Security Best Current Practice) formalizuoja dabartines rekomendacijas: naudokite PKCE su autorizacijos kodo srautais, venkite implicit ir slaptažodžio suteikimų ir naudokite tikslų peradresavimo URI atitikimą.

Prašykite minimalių teisių prieigos sferų (least-privilege scopes). Naudokite tik skaitymo teises, kur nereikia rašyti. Sferų modeliai keičiasi, todėl nekopijuokite senų pavyzdžių. Xero OAuth dokumentacijoje pastebima, kad plačios apskaitos sferos keičiamos į smulkesnes, o naujoms programoms nuo 2026 m. kovo mėn. priskiriamos smulkesnės sferos, o plačios sferos planuojamos palikti prieinamos iki 2027 m. rugsėjo mėn.

Saugokite prieigos raktus tik serverio pusėje. Niekada jų neatskleiskite naršyklės „JavaScript“, mobiliesiems klientams, priekinės dalies (frontend) žurnaluose, analitikoje ar klientams skirtuose klaidų pranešimuose. Užšifruokite ramybės būsenoje (at rest), paslėpkite iš žurnalų ir saugokite metaduomenis kiekvienam ryšiui: užšifruotus prieigos ir atnaujinimo raktus, galiojimo pabaigą, teikėjo organizacijos ID, suteiktas sferas, išdavimo laiką, paskutinį sėkmingą atnaujinimą, atšaukimo būseną.

Atnaujinimo rakto (refresh-token) sukimas yra vieta, kur gamybinė aplinka sugriūsta

Atnaujinimo atsakas gali grąžinti naują atnaujinimo raktą. Turite atominiu būdu išsaugoti naujausią vertę, kitaip atskirsite klientą nuo sistemos. Remiantis Xero kūrėjų D.U.K., kiekvienas atnaujinimas sukuria naują atnaujinimo raktą, atnaujinimo raktai galioja iki 60 dienų, o praradus atsaką yra 30 minučių lengvatinis laikotarpis bandyti dar kartą su esamu raktu. QuickBooks Online nurodo kūrėjams saugoti naujausią atnaujinimo raktą iš naujausio atsakomojo pranešimo: atnaujinimo raktai galioja iki 100 dienų, o reikšmė gali suktis net kas 24 valandas.

Praktikoje: naudokite atnaujinimo užrakto mechanizmą kiekvienam ryšiui, atominiu būdu pakeiskite atnaujinimo raktą, su laikinomis tokeno galinio taško klaidomis kovokite pakartojimais, atskleiskite aiškią pakartotinio autorizavimo būseną ir niekada neatnaujinkite per kiekvieną API iškvietimą, kol galiojantis prieigos raktas lieka galioti.

Pradinis sinchronizavimas

Vykdykite pradinį sinchronizavimą kaip foninį darbą. Neblokuokite dėl jo OAuth atgalinio iškvietimo ar vartotojo sąsajos (UI).

Tvirta seka: gauti organizacijos metaduomenis, nuskaityti sąskaitas, mokesčių tarifus, valiutas, kontaktus ir prekes, išsaugoti teikėjo ID ir susiejimus, importuoti tik tą istorinį langą, kurio produktui reikia, įtraukti priklausomus įrašus į eilę priklausomybės tvarka, įrašyti kontrolinį tašką (checkpoint) ir pažymėti ryšį sveiku tik po patvirtinimo.

Priklausomybės tvarka yra svarbi. Sąskaitai faktūrai gali prireikti, kad pirmiausia egzistuotų kontaktas, prekė, pajamų sąskaita, mokesčio kodas ir valiuta. Aklai nekurkite dublikatų. Sutapdinkite pagal saugomą išorinį ID, kliento pateiktą nuorodą, apibrėžtą atitikties taisyklę arba aiškų vartotojo pasirinkimo žingsnį dviprasmiškais atvejais.

Papildomas (incremental) sinchronizavimas

Laikykite demonstracinius pranešimus (webhooks) signalais, o ne autoritetingais įrašais

Demonstracinis pranešimas (webhook) paprastai praneša, kad kažkas pasikeitė. Patvirtinkite parašą, įrašykite neapdorotą įvykį, greitai grąžinkite reikiamą sėkmės atsakymą, pašalinkite dublikatus, įtraukite į eilę tolesnį duomenų gavimą, nuskaitykite dabartinį objektą iš teikėjo, pritaikykite atnaujinimo operaciją sandoriu (transactionally), atnaujinkite kontrolinį tašką ir nukreipkite klaidas pakartojimui arba suderinimui. Tai padeda apdoroti nepilnus duomenų paketus (payloads) ir netvarkingai atvykstančius įvykius.

Teikėjo taisyklės skiriasi, todėl nežadėkite vienos universalios elgsenos. Xero demonstraciniai pranešimai (webhooks) turi HMAC-SHA256 parašą x-xero-signature antraštėje, reikalauja HTTPS, kartoja bandymus mažėjančiu dažniu iki 24 valandų, pakartotinai nesėkmės atveju gali būti išjungti ir gali išsaugoti įvykius iki 31 dienos, kad juos būtų galima pakartoti po atsigavimo. QuickBooks Online tikrina naudodama HMAC-SHA256 ir tikrintojo (verifier) raktą, tikisi HTTP 200 per tris sekundes ir kartoja bandymus fiksuotu grafiku, kuris galiausiai virsta šešių valandų intervalais, o Intuit rekomenduoja asinchroninį apdorojimą.

Dublikatų šalinimas ir operacijų vienkarttisiškumas (idempotency)

Pristatymas bent vieną kartą (at-least-once delivery) yra norma. Tikėkitės pasikartojančių demonstracinių pranešimų, pakartojimų po skirto laiko pabaigos, kai rašymas iš tikrųjų pavyko, perrikiuotų įvykių ir pasikartojančių vartotojo paspaudimų. Naudokite teikėjo įvykio ID, kai jis pasiekiamas, unikalų įvykio raktą ilgalaikėje saugykloje, operacijos ID, sugeneruotą prieš kiekvieną įrašymą, duomenų bazės unikalumo apribojimus, upsert semantiką ir suderinimo užklausą po dviprasmiškų laiko limitų.

Nemanykite, kad kiekvienas apskaitos API siūlo vietinius operacijos vienkarttisiškumo (idempotency) raktus. Jei teikėjas to nedaro, išsaugokite vidinį operacijos raktą ir prieš pakartodami patikrinkite, ar laukiamas nuotolinis objektas jau egzistuoja. Šablonai iš Stripe vienkarttisiškumo užklausų (idempotent requests) ir bendros demonstracinių pranešimų (webhooks) vienkarttisiškumo gairės čia puikiai tinka.

Apklausa (polling) ir pakeitimų aptikimas

Susiokite demonstracinius pranešimus (webhooks) su periodine apklausa. Demonstraciniai pranešimai išjungiami, vėluoja, prarandami dėl neteisingų nustatymų arba ribojami tam tikriems objektams. Xero palaiko If-Modified-Since antraštę pakeitimams po UTC laiko žymos, tačiau jos dokumentacijoje įspėjama, kad ne kiekvienas pakeitimas atnaujina UpdatedDateUTC, todėl kai kurios dalinai apmokėtos operacijos ir kontakto laukai nepasirodys per šį filtrą. QuickBooks Online pakeitimų duomenų surinkimas (Change Data Capture) seka pakeitimus per pastarąsias 30 dienų, apriboja atsakymus iki 1 000 objektų, grąžina ištrintus subjektus su Deleted būsena ir geriausiai veikia su trumpesniais apklausos langais.

Saugokite kontrolinį tašką kiekvienam teikėjui, kiekvienam nuomininkui ir naudokite persidengiančius langus. Prašykite pakeitimų nuo šiek tiek ankstesnio laiko nei paskutinis kontrolinis taškas, tada pašalinkite dublikatus pagal teikėjo ID ir pakeitimo versiją. Tai apsaugo nuo laikrodžio išsiderinimo ir dalinių gedimų.

Būdingas apskaitos duomenų vientisumas

Tai yra dalis, skirianti veikiančią integraciją nuo patikimos.

Mokesčių elgsena nėra keičiama. Xero dokumentacijoje pastebima, kad sąskaitos faktūros, kreditinės sąskaitos ir pirkimo užsakymai pagal nutylėjimą yra be mokesčių (tax-exclusive), kai LineAmountTypes nenurodytas, kvitai ir banko operacijos pagal nutylėjimą apima mokesčius (tax-inclusive), o rankiniai žurnalai neturi mokesčių. Naudokite TaxType lauką, o ne mokesčio tarifo pavadinimą. Niekada nemanykite, kad „20 % PVM“ vienareikšmiškai identifikuoja mokesčio kodą; jis gali skirtis priklausomai nuo šalies, operacijos tipo, įsigaliojimo datos ir organizacijos konfigūracijos. Tai vieta, kur ES kelių šalių PVM tvarkymas rankiniu būdu tampa brangus, ir kur įterptoji didžioji knyga su įmontuota atitiktimi pagal šalis užsitarnauja savo vietą.

Pinigams skaičiuoti naudokite dešimtainę arba fiksuoto tikslumo aritmetiką, niekada nenaudokite slankiojo kablelio dvejetainės aritmetikos. Išsaugokite valiutos kodą ir tikslumą, vieneto sumą, kiekį, nuolaidą, mokesčio sumą, grynąją, bendrąją sumą ir valiutos keitimo kursą. Aiškiai apsispręskite, ar siunčiate eilutės lygio sumas ir leidžiate teikėjui apskaičiuoti bendras sumas, ar siunčiate iš anksto apskaičiuotą bendrą sumą. Šių dviejų dalykų maišymas sukuria apvalinimo neatitikimus, kuriuos jūsų buhalteris pastebės.

Nuorodos į didžiosios knygos sąskaitas teikiamos pagal teikėjo ID arba kodą, o ne rodomą pavadinimą. Prieš rašydami patvirtinkite, kad sąskaitos, mokesčių kodai, klientai, prekės ir valiuta yra aktyvūs ir palaikomi. Nepavykęs sąskaitos faktūros įrašymas dažniausiai yra susiejimo arba konfigūracijos problema, o ne laikina API klaida, todėl vartotojo sąsaja turėtų paaiškinti pataisymą, o ne rodyti „sinchronizavimas nepavyko“.

Nemanykite, kad objektai yra lygiaverčiai. „Mokėjimas“ gali reikšti kvitą, paskirstymą, depozitą, banko operaciją arba žurnalo įrašą. SaaS „prenumerata“ gali netiksliai atitikti apskaitos „sąskaitą faktūrą“. Apibrėžkite apskaitos įvykį, kurį norite pavaizduoti, prieš pasirinkdami API objektą. Žiūrėkite Xero mokėjimų dokumentaciją, kaip vienas teikėjas tai modeliuoja.

Dažnio limitai (rate limits) ir versijavimas

Limitai paprastai taikomi nuomininkui, organizacijai, programai arba jų deriniui. Remiantis Xero limitų D.U.K.: penkios lygiagrečios užklausos nuomininkui, 60 per minutę nuomininkui, 5 000 per dieną nuomininkui ir 10 000 per minutę visai programai, su likučio antraštėmis ir Retry-After esant 429 klaidoms. QuickBooks Online dokumentuoja 500 užklausų per minutę ir 10 per sekundę sritim (realm ID), o paketinė (batch) galinė sąsaja palaiko iki 30 operacijų vienoje užklausoje.

Sukurkite nuomininko lygio dažnio ribojimą, pasaulinį srauto ribojimą (throttling), eksponentinį grįžimą su atsitiktine dedamąja (exponential backoff with jitter), Retry-After paisymą, ribotą lygiagretumą, puslapiavimą ir metriką apie 429 klaidas bei likusią kvotą. Nenaudokite neriboto lygiagretumo importavimui; vienas didelis klientas gali „bado režimu“ palikti kiekvieną kitą darbą tam nuomininkui.

Užfiksuokite arba aiškiai valdykite API versijas. QuickBooks Online pagal nutylėjimą naudoja 75 mažąją versiją (minor version), kai nenurodyta jokia kita. Centralizuokite versijas konfigūracijoje, paleiskite sutarčių testus smėlio dėžėse (sandboxes), stebėkite išleidimo pastabas ir nežinomus atsakymo laukus laikykite suderinamais su ateities versijomis (forward-compatible). Smėlio dėžės neatkuria kiekvienos gamybinės sąlygos, todėl prieš paleidimą išbandykite atjungimą, prijungimą, atšauktą sutikimą, pasibaigusio galiojimo prieigos raktus, dažnio limitus ir teikėjo pusės pakeitimus.

Ką aš pastatyčiau pirmiausia

Jei pradėčiau tai rytoj, tokia tvarka:

Apibrėžkite tikslų apskaitos darbo procesą: kokius įvykius ir objektus skaitote ar įrašote.
Pasirinkite teikėjo strategiją: tiesioginį, vieningą, įterptąjį arba hibridinį.
Sukurkite nuomininko lygio ryšio modelį su teikėjo organizacijos ID, sferomis, būsena ir prieigos raktų metaduomenimis.
Įdiekite OAuth su autorizacijos kodo srautu, PKCE, būsenos patvirtinimu, minimalių teisių sferomis ir serverio pusės prieigos raktų saugojimu.
Sukurkite vieną teikėjo adapterį už stabilios vidinės sąsajos.
Sukurkite ID susiejimus pagal nekintamus teikėjo ID.
Pirmiausia įdiekite skaitymą; importuokite pagrindinius duomenis prieš bet kokį rašymą.
Pridėkite pradinio sinchronizavimo užduotį su puslapiavimu, dažnio ribojimu, kontroliniais taškais ir priklausomybės tvarka.
Įdiekite vieną siaurą įrašymą (sukurkite sąskaitą faktūrą) tik po to, kai patvirtinami kliento, prekės, mokesčio ir sąskaitos susiejimai.
Padarykite įrašus atsparius pakartojimams naudodami vidinius operacijų ID, unikalumo apribojimus ir nuotolinės būsenos patikrinimus.
Pridėkite pasirašytus demonstracinius pranešimus (webhooks), kurie greitai patvirtina gavimą ir apdoroja asinchroniškai.
Pridėkite apklausą ir suderinimą, kad demonstraciniai pranešimai būtų pagreitinimo priemonė, o ne vienintelis tiesos šaltinis.
Tikslingai išbandykite gedimo režimus.
Pridėkite palaikymo ir audito įrankius, kurie krizes paverčia suprantamomis ir pataisomomis.
Laipsniškai plėskite objektų aprėptį.

D.U.K.

Ar turėčiau naudoti vieningą API ar kurti tiesioginius jungiklius?

Naudokite tiesioginį jungiklį, kai vienas teikėjas dominuoja tarp jūsų klientų arba teikėjo specifinė elgsena yra esminė. Apsvarstykite vieningą API, kai plati aprėptis ir greitis yra svarbesni už kontrolę. Jei jūsų tikrasis poreikis yra paties valdoma buhalterija, o ne sinchronizavimas su kliento sistema, nei vienas neatsako į klausimą – verčiau apsvarstykite įterptąją didžiąją knygą, tokią kaip Nordlet.

Ar demonstracinių pranešimų (webhooks) pakanka sinchronizavimui palaikyti?

Ne. Demonstraciniai pranešimai išjungiami, vėluoja arba pasimeta, o duomenų paketai gali būti nepilni arba netvarkingi. Laikykite juos pakeitimų signalais, po to nuskaitykite esamą objektą ir palaikykite periodine apklausa bei suderinimu.

Kaip apsisaugoti, kad atnaujinimo rakto gedimai neužrakintų klientų?

Atominiu būdu išsaugokite naujausią atnaujinimo raktą per kiekvieną atnaujinimą, naudokite užraktą kiekvienam ryšiui, pakartokite laikinų tokeno galinio taško klaidų atvejus ir atskleiskite aiškią pakartotinio autorizavimo būseną. Xero 30 minučių lengvatinis laikotarpis padeda, bet atominiu būdu atliekamas išsaugojimas yra tai, kas jus išgelbėja.

Ar galiu suderinti įrašus pagal kliento vardą arba el. paštą?

Ne kaip nuolatinį identifikatorių. Vardai keičiasi, pasitaiko dublikatų, o du klientai gali dalintis vienu el. paštu. Saugokite teikėjo nekintamą ID ir šalia jo laikykite savo SaaS ID.