Kaip integruoti debesijos apskaitos API į SaaS platformą

Praktinis vadovas, kaip sukurti kelių nuomininkų (multi-tenant) apskaitos integraciją, kuri susitvarko su OAuth, „webhooks“, mokesčių taisyklėmis ir likučių derinimu nesugadinant didžiosios knygos.

Dauguma komandų, nusprendusių „pridėti apskaitą“ prie savo SaaS produkto, pradeda nuo HTTP kliento sujungimo su tiekėjo galiniu tašku (endpoint) ir sąskaitos faktūros išsiuntimo. Demonstracinėje versijoje tai veikia. Tačiau viskas sugriūva, kai klientas pirmą kartą prijungia dvi apskaitos organizacijas, kai „webhook“ ateina du kartus, ir kai atnaujinimo prieigos raktas (refresh token) pasikeičia ir pasimeta užklausos viduryje. Tvarus šio darbo sprendimas yra ne klientas, o integracijos lygmuo.

Šis lygmuo turi valdyti nuomininkų (tenants) ryšius, prieigos raktų saugojimą ir atnaujinimą, specifines tiekėjo apskaitos taisykles, įrašų susiejimą, pradinį ir inkrementinį sinchronizavimą, „webhook“ priėmimą su pakartotiniais bandymais ir dublikatų šalinimu, užklausų ribojimus (rate limits), versijavimą ir audito seką, kurią jūsų palaikymo komanda galėtų suprasti net 2 valandą nakties.

Naudingas mentalinis modelis:

SaaS produktas → apskaitos integracijos paslauga → tiekėjo adapteris (arba unifikuotas API) → asinchroninis sinchronizavimas ir likučių derinimas (reconciliation)

Apskaitos sistema išlieka pagrindiniu didžiosios knygos objektų – sąskaitų, mokesčių kodų, užregistruotų operacijų, bendrojo žurnalo įrašų – šaltiniu. Jūsų SaaS platforma saugo stabilius tarpsisteminius identifikatorius, sinchronizacijos būseną, susiejimo metaduomenis ir operacijų audito žurnalą.

Ką iš tikrųjų čia apima „debesijos apskaitos API“

Ši frazė paprastai reiškia priglobtos buhalterinės apskaitos platformos, tokios kaip QuickBooks Online, Xero, Sage, Zoho Books, arba regioninės sistemos API. Tai taip pat gali reikšti unifikuotą apskaitos API, kuris standartizuoja kelis tiekėjus per vieną sąsają.

Verta būti tiksliems, nes įgyvendinimas skiriasi priklausomai nuo tikslo. Sąskaitų faktūrų nuskaitymas ataskaitoms nėra tas pats, kas sąskaitų faktūrų kūrimas pagal SaaS veiklą, pirkimo sąskaitų registravimas, pirkėjų ir produktų sinchronizavimas, bendrojo žurnalo įrašų registravimas ar tikro dvikrypčio sinchronizavimo vykdymas. Prieš pradėdami dirbti su galiniais taškais, nuspręskite, kurį iš šių variantų kursite.

Šiame kontekste svarbus dar vienas skirtumas. Mokėjimų API perveda pinigus. Bankininkystės API surenka sąskaitų duomenis. Sąskaitų išrašymo (invoicing) API gali kurti dokumentus neatveriant prieigos prie didžiosios knygos. Įterptoji apskaitos didžioji knyga (embedded accounting ledger) vėlgi skiriasi: pati SaaS įmonė valdo apskaitos variklį. Būtent šiai paskutinei kategorijai priklauso Nordlet. Užuot sujungus jūsų produktą su kliento išorine apskaitos sistema, Nordlet platformoms ir prekyvietėms (marketplaces) suteikia tikrą dvejybinio įrašo (double-entry) apskaitą, nekeičiamą ir auditui paruoštą didžiąją knygą, ES PVM tvarkymą ir išmokėjimus pačiame produkte, naudojant į API orientuotą (API-first) dizainą su tipizuotais SDK ir „webhooks“. Jei esate prekyvietė, sprendžianti, ar integruoti kliento apskaitos sistemą, ar patiems tvarkyti buhalteriją, tai yra esminis pasirinkimas, prie kurio dar grįšime.

Kelių nuomininkų (multi-tenancy) architektūra: dvigubas kiekvieno ryšio atskyrimas

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

Nesusiekite ryšių vien tik pagal OAuth vartotojo ID. Vienas vartotojas gali autorizuoti kelias apskaitos organizacijas, o vieną organizaciją laikui bėgant gali iš naujo prijungti skirtingi vartotojai. Jei čia suklysite, galiausiai užregistruosite vieno kliento sąskaitą faktūrą kito kliento apskaitoje, o tai nėra klaida, kurią būtų galima ištaisyti nepastebimai.

Pirmasis architektūrinis sprendimas: tiesioginė jungtis, unifikuotas API ar įterptoji didžioji knyga

Tiesioginės tiekėjų integracijos

Tiesioginė integracija suteikia daugiausiai kontrolės: tiekėjui būdingos funkcijos, pasirinktiniai laukai (custom fields), klaidų apdorojimas, sinchronizavimo dažnumas, duomenų saugojimas ir kaštų struktūra. Tačiau už tai tenka sumokėti. Kiekvienas tiekėjas turi savo OAuth srautą, duomenų schemą, ypatumus, užklausų ribojimus, „webhook“ elgseną, sertifikavimą ir nuolatinę priežiūrą.

Unifikuoti apskaitos API

Unifikuotas API siūlo vieną sąsają kelioms apskaitos sistemoms, standartizuojant tokius subjektus kaip pirkėjai, sąskaitos faktūros, tiekėjai, sąskaitos, mokėjimai ir produktai. Tai gali sutrumpinti pradinį kūrimo laiką. Tačiau tai nepašalina integracijos sudėtingumo, ir manyti kitaip yra dažna klaida.

Prieš įsipareigodami paklauskite: kokie tiekėjai ir operacijos yra palaikomi? Ar veikia duomenų įrašymas (writes), ar tik nuskaitymas (reads)? Ar įrašymai yra sinchroniniai, ar statomi į eilę? Ar per unifikuotą sąsają galima pasiekti tiekėjui specifinius laukus? Ar duomenys talpinami į podėlį (cached) ir kokio jie šviežumo? Kas sprendžia problemas, kai tiekėjas neveikia arba kai keičiasi API? Ar kainodara pagrįsta API iškvietimais, susietomis paskyromis, įrašais, ar taikomas platformos mokestis? Ar galite eksportuoti savo susiejimus (mappings) ir tvarkingai atsijungti? „Unifikuotas“ retai reiškia „turintis vienodas funkcijas tarp visų tiekėjų“.

Įterptoji didžioji knyga

Jei pagrindinė jūsų platformos problema yra tvarkyti vartotojų apskaitą, o ne atvaizduoti ją jų esamoje apskaitoje, įterptoji didžioji knyga iš esmės keičia situaciją. Prekyvietei, turinčiai tūkstančius pardavėjų, arba SaaS produktui, kuriam reikalinga auditui paruošta ES PVM ir atskirų šalių mokestinių reikalavimų atitiktis, kur kas geriau turėti nuosavą apskaitos variklį nei jungti N išorinių jungčių. Būtent tai ir siūlo Nordlet: tikra apskaita per API, nekeičiamas dvejybinis įrašas, konkrečios šalies PVM su VIES patikrinimu ir i.SAF registrų generavimu, SEPA eksportas ir ataskaitų eksportavimas XLSX, PDF ar JSON formatu – visa tai tiesiogiai jūsų produkte, o ne trečiosios šalies atsiskaitymo puslapyje.

Mano naudojama sprendimų priėmimo taisyklė:

Situacija	Tinkamiausias sprendimas
Jūsų klientų bazėje dominuoja vienas apskaitos sistemų tiekėjas; tiekėjui būdinga elgsena yra esminė	Tiesioginė jungtis (Direct connector)
Plati tiekėjų aprėptis ir išleidimo į rinką greitis yra svarbesni nei kontrolė	Unifikuotas API (Unified API)
Esate platforma ar prekyvietė, kuriai reikia pačiai tvarkyti apskaitą, atitikti ES PVM reikalavimus ir turėti audito seką	Įterptoji didžioji knyga (Nordlet)
Mišri situacija	Hibridas: unifikuotas API bendriems srautams, tiesioginės jungtys strateginiams tiekėjams

Rekomenduojama integracijos architektūra

Atskirkite integraciją nuo pagrindinės verslo logikos

Neišbarstykite tiekėjo API iškvietimų atsiskaitymų, užsakymų, prenumeratų ir ataskaitų moduliuose. Sukurkite tam skirtą integracijos paslaugą (service), kurioje bus tiekėjų adapteriai, OAuth ryšių valdymas, kanoniniai modeliai, ID susiejimai, sinchronizacijos užduotys ir eilės, „webhook“ galiniai taškai, pakartotinių bandymų ir neapdorotų pranešimų (dead-letter) valdymas, audito žurnalai ir likučių derinimo įrankiai. Tai apsaugos nuo to, kad Xero arba QuickBooks laukų pavadinimai neprasiskverbtų į jūsų domeno modelį.

Apibrėžkite siaurą kanoninį modelį

Modeliuokite tik tuos darbo srautus, kuriuos palaikote. Tipiški objektai: pirkėjas, produktas ar paslauga, sąskaita faktūra, sąskaitos eilutė, mokėjimas, kreditinė sąskaita (credit note), tiekėjas, sąskaita (account), mokesčio tarifas, valiuta, bendrojo žurnalo įrašas (journal entry).

Išsaugokite skirtumus, turinčius įtakos apskaitai. Nesuvienodinkite tokių dalykų kaip juodraštis, patvirtintas ir užregistruotas dokumentas; sumos su mokesčiais ir sumos be mokesčių; kreditinės sąskaitos ir neigiamos sąskaitos faktūros; mokėjimo paskirstymas (allocation) ir paties mokėjimo faktas; klientui matomas sąskaitos faktūros numeris ir tiekėjo objekto ID. Kiekviename įraše turi būti SaaS ID, tiekėjo ID, tiekėjo pavadinimas ir API versija, duomenų šaltinio (source-of-truth) indikatorius, būsena, laiko žymos (timestamps), paskutinio sinchronizavimo laikas, išorinė nuoroda (external reference) ir klaidos / derinimo būsena.

Palaikykite aiškias susiejimo lenteles

Susiekite SaaS nuomininką su apskaitos organizacija, SaaS pirkėją su tiekėjo kontaktu, SaaS produktą su tiekėjo preke ar sąskaita, SaaS sąskaitą faktūrą su tiekėjo sąskaita faktūra, SaaS mokėjimą su tiekėjo mokėjimu, mokesčių 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 naudoti tą patį el. pašto adresą. Saugokite nekeičiamą tiekėjo ID ir išlaikykite pradinį SaaS ID.

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

Suteikite ryšiui aiškias būsenas: neprijungtas, laukiama autorizacijos, prijungtas, laukiama pradinio sinchronizavimo, sinchronizuojama, veikia tinkamai (healthy), ribojamas užklausų kiekis, reikalinga pakartotinė autorizacija, tiekėjas nepasiekiamas, atjungtas, negrįžtamai sugedęs. Įrašams priskirkite atskiras būsenas: laukiama, išsiųsta, patvirtinta, nepavyko-galima-kartoti, nepavyko-reikalingas-vartotojo-veiksmas, suderinta (reconciled), aptiktas konfliktas. Dvejetainė būsena „prijungta / neprijungta“ jūsų palaikymo komandai nesuteikia jokios naudingos informacijos.

OAuth ir ryšio (connection) sukūrimas

Naudokite autorizacijos kodo srautą (authorization code flow). Klientas paspaudžia „Prisijungti“, jūsų serveris sukuria trumpalaikę autorizacijos transakciją, klientas autentifikuojasi tiekėjo sistemoje ir suteikia leidimus (scopes), jūs iškeičiate kodą į prieigos raktus (tokens), identifikuojate autorizuotą organizaciją, išsaugote ryšį atitinkamam nuomininkui ir įtraukiate į eilę pradinį sinchronizavimą.

Atidžiai patikrinkite atgalinį iškvietimą (callback): parametrą state palyginkite su serverio transakcija, tikslų peradresavimo URI (redirect URI), tiekėjo išdavėją (issuer) ir nuomininko kontekstą. RFC 9700, OAuth 2.0 Security Best Current Practice formalizuoja dabartines rekomendacijas: naudokite PKCE su autorizacijos kodo srautais, venkite numanomo (implicit) ir slaptažodžių pagrindu veikiančio leidimų suteikimo (password grants) bei naudokite tikslų peradresavimo URI atitikimą.

Prašykite tik mažiausių būtinų privilegijų (least-privilege scopes). Naudokite tik skaitymo teisę ten, kur jums nereikia rašyti. Leidimų modeliai keičiasi, todėl nekopijuokite senų pavyzdžių. Xero OAuth dokumentacijoje pažymima, kad platūs apskaitos leidimai keičiami į detalius (granular) – nuo 2026 m. kovo naujoms programėlėms priskiriami detalūs leidimai, o plačius leidimus planuojama palikti prieinamus iki 2027 m. rugsėjo.

Prieigos raktus (tokens) saugokite tik serverio pusėje. Niekada neatskleiskite jų naršyklės JavaScript, mobiliesiems klientams, naudotojo sąsajos žurnalams (frontend logs), analitikai ar klientams matomuose klaidų pranešimuose. Šifruokite ramybės būsenoje (at rest), pašalinkite iš žurnalų (redact) ir išsaugokite kiekvieno ryšio metaduomenis: šifruotus prieigos (access) ir atnaujinimo (refresh) raktus, galiojimo laiką, tiekėjo organizacijos ID, suteiktus leidimus (scopes), išdavimo laiką, paskutinio sėkmingo atnaujinimo laiką, atšaukimo būseną.

Atnaujinimo rakto (refresh-token) rotacija – vieta, kur sistemos lūžta gamybinėje aplinkoje (production)

Atnaujinimo atsakas gali grąžinti naują atnaujinimo raktą (refresh token). Privalote išsaugoti naujausią reikšmę atomiškai, kitaip užblokuosite klientą. Remiantis Xero kūrėjų D.U.K., kiekvienas atnaujinimas sugeneruoja naują atnaujinimo raktą; atnaujinimo raktai galioja iki 60 dienų, be to, yra 30 minučių lengvatinis laikotarpis (grace period) pakartotiniam bandymui su esamu raktu, jei atsakas prarandamas. QuickBooks Online nurodo kūrėjams išsaugoti naujausią atnaujinimo raktą iš paskutinio atsako: atnaujinimo raktai galioja iki 100 dienų, o reikšmė gali keistis net ir kas 24 valandas.

Praktiškai: naudokite atnaujinimo užraktą (lock) kiekvienam ryšiui atskirai, atnaujinimo raktą pakeiskite atomiškai, valdykite laikinus prieigos raktų galinio taško (token-endpoint) gedimus atliekant pakartotinius bandymus, pateikite aiškią pakartotinės autorizacijos būseną ir niekada neatnaujinkite raktų su kiekvienu API iškvietimu, kol galioja prieigos raktas (access token).

Pradinis sinchronizavimas

Vykdykite pradinį sinchronizavimą kaip foninę užduotį. Neblokuokite OAuth atgalinio iškvietimo ar vartotojo sąsajos laukdami, kol jis pasibaigs.

Patikima seka: gaukite organizacijos metaduomenis, gaukite sąskaitas (accounts), mokesčių tarifus, valiutas, kontaktus ir prekes (items), išsaugokite tiekėjo ID ir susiejimus, importuokite tik tą istorinį langą, kurio reikia produktui, į eilę įtraukite priklausomus įrašus atsižvelgiant į priklausomybių tvarką, užfiksuokite atskaitos tašką (checkpoint) ir tik po patvirtinimo pažymėkite ryšį kaip tinkamai veikiantį.

Priklausomybių tvarka yra svarbi. Kad sąskaita faktūra galėtų egzistuoti, pirmiausia gali prireikti kontakto, prekės, pajamų sąskaitos, mokesčio kodo ir valiutos. Aklai nekurkite dublikatų. Sutapdinkite įrašus pagal išsaugotą išorinį ID, kliento pateiktą nuorodą, apibrėžtą atitikimo taisyklę arba pateikite aiškų vartotojo pasirinkimo žingsnį dviprasmiškais atvejais.

Inkrementinis sinchronizavimas

Traktuokite „webhooks“ kaip signalus, o ne kaip autoritetingus įrašus

„Webhook“ dažniausiai praneša, kad kažkas pasikeitė. Patikrinkite parašą, užregistruokite neapdorotą (raw) įvykį, greitai grąžinkite reikalaujamą sėkmės atsaką, pašalinkite dublikatus, į eilę įtraukite vėlesnį duomenų gavimą, paimkite dabartinį objektą iš tiekėjo, pritaikykite atnaujinimą transakcijos būdu, atnaujinkite atskaitos tašką ir nukreipkite gedimus į pakartotinių bandymų ar derinimo procesus. Tai padeda susitvarkyti su nevisavertėmis naudingosiomis apkrovomis (payloads) ir ne iš eilės gautais įvykiais.

Tiekėjų taisyklės skiriasi, todėl nežadėkite vienos universalios elgsenos. Xero „webhooks“ turi HMAC-SHA256 parašą x-xero-signature antraštėje, reikalauja HTTPS, bando pakartotinai mažėjančiu dažnumu iki 24 valandų, gali būti išjungti po pasikartojančių gedimų ir gali saugoti įvykius iki 31 dienos pakartotiniam paleidimui po atsistatymo. QuickBooks Online tikrina parašus su HMAC-SHA256 ir patvirtinimo raktu (verifier token), tikisi sulaukti HTTP 200 per tris sekundes ir bando pakartotinai pagal fiksuotą grafiką, kuris galiausiai nusistovi ties šešių valandų intervalais, o Intuit rekomenduoja taikyti asinchroninį apdorojimą.

Dublikatų šalinimas ir idempotentiškumas

Pristatymas „bent kartą“ (at-least-once) yra įprasta praktika. Tikėkitės besidubliuojančių „webhooks“, pakartotinių bandymų po laukimo pabaigos (timeout), nors įrašymas iš tikrųjų buvo sėkmingas, ne iš eilės pateiktų įvykių ir besidubliuojančių vartotojo paspaudimų. Naudokite tiekėjo įvykio ID, jei toks yra, unikalų įvykio raktą ilgalaikėje saugykloje, operacijos ID, sugeneruotą prieš kiekvieną įrašymą, duomenų bazės unikalumo apribojimus (constraints), įrašymo arba atnaujinimo (upsert) semantiką ir derinimo užklausą po dviprasmiškų laukimo pabaigų (timeouts).

Nemanykite, kad kiekvienas apskaitos API siūlo natyvius idempotentiškumo raktus. Jei tiekėjas to nedaro, saugokite vidinį operacijos raktą ir prieš bandydami pakartotinai patikrinkite, ar laukiamas nuotolinis objektas jau egzistuoja. Čia puikiai tinka šablonai iš Stripe idempotentinių užklausų ir bendrųjų „webhook“ idempotentiškumo gairių.

Apklausos (polling) ir pokyčių aptikimas

„Webhooks“ derinkite su periodinėmis apklausomis (polling). „Webhooks“ gali būti išjungti, vėluoti, pasimesti dėl netinkamos konfigūracijos arba būti taikomi tik tam tikriems objektams. Xero palaiko antraštę If-Modified-Since pokyčiams po UTC laiko žymos, bet dokumentacija įspėja, kad ne kiekvienas pakeitimas atnaujina UpdatedDateUTC, todėl kai kurios dalinai apmokėtos operacijos ir kontaktų laukai per šį filtrą neatsispindės. QuickBooks Online „Change Data Capture“ seka paskutinių 30 dienų pokyčius, riboja atsakus iki 1 000 objektų, grąžina ištrintus subjektus su būsena Deleted ir geriausiai veikia naudojant trumpesnius apklausų intervalus.

Saugokite atskirą atskaitos tašką (checkpoint) kiekvienam tiekėjui ir nuomininkui bei naudokite persidengiančius laiko langus (overlap windows). Prašykite pokyčių nuo šiek tiek ankstesnio laiko nei paskutinis atskaitos taškas, o tada pašalinkite dublikatus pagal tiekėjo ID ir modifikacijos versiją. Tai apsaugo nuo laikrodžių nesutapimo (clock skew) ir dalinių gedimų.

Su apskaita susijęs duomenų vientisumas

Būtent ši dalis skiria veikiančią integraciją nuo patikimos integracijos.

Mokesčių elgsena nėra vienoda (interchangeable). Xero dokumentacijoje pažymima, kad sąskaitos faktūros, kreditinės sąskaitos ir pirkimo užsakymai pagal nutylėjimą yra be mokesčių (tax-exclusive), kai nenustatytas LineAmountTypes, kvitai ir banko operacijos pagal nutylėjimą yra su mokesčiais (tax-inclusive), o rankiniai bendrojo žurnalo įrašai pagal nutylėjimą yra be jokių mokesčių (no tax). Naudokite TaxType lauką, o ne mokesčio tarifo pavadinimą. Niekada nemanykite, kad „20% PVM“ vienareikšmiškai identifikuoja mokesčio kodą; tai gali skirtis priklausomai nuo šalies, operacijos tipo, įsigaliojimo datos ir organizacijos konfigūracijos. Būtent čia daugelio ES šalių PVM tvarkymas rankiniu būdu tampa brangus, ir būtent čia pasiteisina įterptoji didžioji knyga su įdiegta atskirų šalių reikalavimų atitiktimi.

Pinigams naudokite dešimtainę (decimal) arba fiksuoto tikslumo aritmetiką, niekada nenaudokite dvejetainio slankiojo kablelio (binary floating point). Saugokite valiutos kodą ir tikslumą, vieneto kainą (unit amount), kiekį, nuolaidą, mokesčio sumą, grynąją (net) ir bendrąją (gross) sumas bei valiutos kursą. Aiškiai nuspręskite, ar siunčiate eilučių sumas ir leidžiate tiekėjui apskaičiuoti galutines sumas, ar siunčiate iš anksto apskaičiuotą bendrą sumą. Šių dviejų būdų maišymas sukuria apvalinimo neatitikimus, kuriuos jūsų buhalteris tikrai pastebės.

Nurodykite didžiosios knygos sąskaitas pagal tiekėjo ID arba kodą, o ne pagal rodomą pavadinimą. Prieš įrašydami patikrinkite, ar sąskaitos, mokesčių kodai, pirkėjai, prekės ir valiuta yra aktyvūs ir palaikomi. Nesėkmingas sąskaitos faktūros įrašymas dažniausiai yra susiejimo arba konfigūracijos problema, o ne trumpalaikė API klaida, todėl vartotojo sąsaja turėtų paaiškinti, kaip tai ištaisyti, užuot rodžiusi „sinchronizavimas nepavyko“.

Nedarykite prielaidos dėl objektų lygiavertiškumo (equivalence). „Mokėjimas“ gali reikšti kvitą (receipt), paskirstymą (allocation), indėlį (deposit), banko operaciją arba bendrojo žurnalo įrašą. SaaS „prenumerata“ gali netiksliai atitikti apskaitos „sąskaitą faktūrą“. Prieš pasirinkdami API objektą, apibrėžkite apskaitos įvykį, kurį norite atvaizduoti. Žr. Xero mokėjimų dokumentaciją, kurioje parodyta, kaip šį procesą modeliuoja vienas tiekėjas.

Užklausų ribojimai (rate limits) ir versijavimas

Apribojimai paprastai taikomi nuomininkui, organizacijai, programai arba jų deriniui. Remiantis Xero apribojimų D.U.K.: penkios lygiagrečios užklausos vienam nuomininkui, 60 per minutę vienam nuomininkui, 5 000 per dieną vienam nuomininkui ir 10 000 per minutę visai programai; grąžinamos likusio limito antraštės ir Retry-After gaunant 429 klaidą. QuickBooks Online dokumentacijoje nurodoma 500 užklausų per minutę ir 10 užklausų per sekundę vienam srities (realm) ID, o paketinis (batch) galinis taškas palaiko iki 30 operacijų vienoje užklausoje.

Sukurkite užklausų ribojimą kiekvienam nuomininkui (per-tenant), bendrą pralaidumo ribojimą (global throttling), eksponentinį atidėjimą su atsietumu (exponential backoff with jitter), reaguokite į Retry-After, apribokite lygiagretumą, įdiekite puslapiavimą (pagination) ir sekite metrikas, susijusias su 429 klaidomis bei likusiomis kvotomis. Nenaudokite neriboto paralelizmo importams; vienas didelis klientas gali užblokuoti (starve) visas kitas to nuomininko užduotis.

Fiksuokite (pin) arba aiškiai valdykite API versijas. QuickBooks Online pagal nutylėjimą naudoja antrinę (minor) versiją 75, kai jokia versija nenurodyta. Centralizuokite versijas konfigūracijoje, vykdykite API sutarčių testus (contract tests) smėliadėžėse (sandboxes), stebėkite laidų pastabas (release notes) ir traktuokite nežinomus atsako laukus kaip suderinamus su ateities versijomis (forward-compatible). Smėliadėžės neatkurs visų gamybinių sąlygų, todėl prieš paleisdami produktą ištestuokite atsijungimą, prisijungimą iš naujo, sutikimo atšaukimą, pasibaigusio galiojimo prieigos raktus, užklausų ribojimus ir pakeitimus tiekėjo sistemoje.

Ką pirmiausia sukurčiau

Jei tai pradėčiau rytoj, seka būtų tokia:

Tiksliai apibrėžkite apskaitos darbo srautą: kokius įvykius ir objektus skaitote ar įrašote.
Pasirinkite tiekėjo strategiją: tiesioginė, unifikuota, įterptoji ar hibridinė.
Sukurkite nuomininkui priskirtą (tenant-scoped) ryšio modelį su tiekėjo organizacijos ID, leidimais (scopes), būsena ir prieigos raktų metaduomenimis.
Įgyvendinkite OAuth naudodami autorizacijos kodo srautą, PKCE, state patvirtinimą, mažiausių privilegijų leidimus ir prieigos raktų saugojimą serverio pusėje.
Sukurkite vieną tiekėjo adapterį, paslėptą po stabilia vidine sąsaja.
Sukurkite ID susiejimus naudodami nekeičiamus tiekėjo ID.
Pirmiausia įgyvendinkite nuskaitymą (reads); prieš bet kokį įrašymą importuokite pamatinius duomenis (reference data).
Pridėkite pradinio sinchronizavimo užduotį su puslapiavimu, užklausų ribojimu, atskaitos taškais ir priklausomybių išdėstymu.
Įgyvendinkite vieną siaurą įrašymą (sukurti sąskaitą faktūrą) tik patvirtinę pirkėjo, prekės, mokesčių ir sąskaitos susiejimus.
Padarykite įrašymus atsparius pakartotiniams bandymams (retry-safe), naudodami vidinius operacijų ID, unikalumo apribojimus ir nuotolinės būsenos patikras.
Pridėkite pasirašytus „webhooks“, kurie greitai patvirtina gavimą ir yra apdorojami asinchroniškai.
Pridėkite apklausas (polling) ir likučių derinimą, kad „webhooks“ veiktų tik kaip pagreitinimas, o ne kaip vienintelis duomenų šaltinis.
Tyčia ištestuokite gedimų scenarijus.
Pridėkite palaikymo ir audito įrankius, dėl kurių gedimai taptų paaiškinami ir ištaisomi.
Palaipsniui plėskite palaikomų objektų aprėptį.

D.U.K.

Ar turėčiau naudoti unifikuotą API, ar kurti tiesiogines jungtis?

Naudokite tiesioginę jungtį, kai tarp jūsų klientų dominuoja vienas tiekėjas arba tiekėjui specifinė elgsena yra esminė. Svarstykite unifikuotą API, kai plati aprėptis ir greitis yra svarbiau už kontrolę. Jei jūsų tikrasis poreikis yra patiems tvarkyti buhalteriją, o ne sinchronizuoti su kliento sistema, nei vienas variantas neatsako į šį klausimą; geriau atkreipkite dėmesį į įterptąją didžiąją knygą, tokią kaip Nordlet.

Ar sinchronizavimui užtenka „webhooks“?

Ne. „Webhooks“ gali būti išjungti, vėluoti ar pasimesti, o naudingosios apkrovos (payloads) gali būti neišsamios arba gautos ne iš eilės. Traktuokite juos kaip pokyčių signalus, vėliau gaukite dabartinį objektą iš tiekėjo ir palaikykite šį procesą periodinėmis apklausomis bei derinimu.

Kaip išvengti to, kad atnaujinimo rakto gedimai užblokuotų klientus?

Atomiškai išsaugokite naujausią atnaujinimo raktą per kiekvieną atnaujinimą, naudokite atnaujinimo užraktą kiekvienam ryšiui atskirai, pakartokite bandymus esant laikiniems raktų galinio taško gedimams ir pateikite aiškią pakartotinės autorizacijos būseną. Xero 30 minučių lengvatinis laikotarpis padeda, bet būtent atominis išsaugojimas (atomic persist) yra tai, kas jus apsaugos.

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

Ne kaip nuolatinį identifikatorių. Vardai keičiasi, pasitaiko dublikatų, ir du klientai gali naudoti tą patį el. paštą. Saugokite nekeičiamą tiekėjo ID ir šalia išlaikykite savo SaaS ID.