Ako integrovať API cloudového účtovníctva do platformy SaaS

Praktická príručka pre vývojárov na vytvorenie viacnájomnej (multi-tenant) účtovnej integrácie, ktorá zvládne OAuth, webhooky, daňové pravidlá a rekonciliáciu bez poškodenia účtovnej knihy.

Väčšina tímov, ktoré sa pustia do „pridania účtovníctva“ do svojho produktu SaaS, začína prepojením HTTP klienta s koncovým bodom poskytovateľa a odoslaním faktúry. To funguje v deme. Celé to však zlyhá pri prvom prípade, keď zákazník prepojí dve účtovné organizácie, keď webhook dorazí dvakrát, alebo keď sa obnovovací token (refresh token) počas požiadavky obmení a stratí. Odolná verzia tejto práce nie je len klient. Je to integračná vrstva.

Táto vrstva musí spravovať pripojenia nájomníkov (tenants), ukladanie a rotáciu tokenov, účtovné pravidlá špecifické pre daného poskytovateľa, párovanie záznamov, počiatočnú a prírastkovú synchronizáciu, príjem webhookov s opakovanými pokusmi a deduplikáciou, limity požiadaviek (rate limits), verzionovanie a auditnú stopu, ktorú si váš tím podpory dokáže prečítať o 2. ráno. Tento článok vás przeprowadí touto architektúrou a rozhodnutiami, na ktorých záleží najviac.

Užitočný mentálny model:

Produkt SaaS → integračná služba účtovníctva → adaptér poskytovateľa (alebo zjednotené API) → asynchrónna synchronizácia a rekonciliácia

Účtovný systém zostáva zdrojom pravdy (system of record) pre objekty hlavnej knihy: účty, daňové kódy, zaúčtované transakcie, účtovné zápisy. Vaša platforma SaaS udržiava stabilné identifikátory naprieč systémami, stav synchronizácie, metadáta párovania a prevádzkový denník auditov.

Čo „API cloudového účtovníctva“ v tomto kontexte skutočne zahŕňa

Toto slovné spojenie zvyčajne označuje API hostenej účtovnej platformy, ako je QuickBooks Online, Xero, Sage, Zoho Books alebo regionálny systém. Môže znamenať aj zjednotené účtovné API (unified accounting API), ktoré normalizuje niekoľko poskytovateľov pod jedno rozhranie.

Oplatí sa byť presný, pretože implementácia sa líši podľa zámeru. Čítanie faktúr na účely reportovania nie je tá istá práca ako vytváranie faktúr z aktivity SaaS, zaúčtovanie prijatých faktúr (bills), synchronizácia zákazníkov a produktov, zápis účtovných položiek alebo spustenie skutočnej obojsmernej synchronizácie. Skôr než sa dotknete koncového bodu, rozhodnite sa, čo z toho vlastne staviate.

Pre tento článok je dôležité ešte jedno rozlíšenie. Platobné API presúva peniaze. Bankové API sťahuje údaje o účtoch. Fakturačné API môže vytvárať dokumenty bez toho, aby sprístupnilo hlavnú knihu. Vložená účtovná kniha (embedded ledger) je opäť niečo iné: spoločnosť SaaS vlastní samotný účtovný engine. Práve sem smeruje Nordlet. Namiesto pripájania vášho produktu k externým knihám vášho zákazníka poskytuje Nordlet platformám a trhoviskám reálne podvojné účtovníctvo, nemennú knihu pripravenú na audit, spracovanie DPH v EÚ a výplaty priamo vo vlastnom produkte prostredníctvom dizajnu založeného na API s typovými SDK a webhookmi. Ak ste trhovisko (marketplace), ktoré sa rozhoduje, či má integrovať účtovný systém zákazníka, alebo si viesť účtovníctvo samé, je to zásadná križovatka, k ktorej sa ešte vrátime.

Viacnájomnosť (multi-tenancy): každé pripojenie preverte dvakrát

V produkte SaaS sa jedna aplikácia pripája k mnohým zákazníckym organizáciám. Každé pripojenie musí byť vymedzené (scoped) jak nájomníkom SaaS, tak identifikátorom organizácie poskytovateľa, ako je napríklad ID nájomníka Xero alebo ID oblasti (realm ID) v QuickBooks.

Nezakladajte pripojenia iba na ID používateľa OAuth. Jeden používateľ môže autorizovať niekoľko účtovných organizácií a jednu organizáciu môžu v priebehu času opätovne prepojiť rôzni používatelia. Ak to urobíte zle, nakoniec zaúčtujete faktúru jedného zákazníka do kníh iného zákazníka, a to nie je chyba, z ktorej sa bezstarostne zotavíte.

Prvé architektonické rozhodnutie: priamy konektor, zjednotené API alebo vložená kniha

Priame integrácie s poskytovateľmi

Priama integrácia vám poskytuje najväčšiu kontrolu: funkcie špecifické pre daného poskytovateľa, vlastné polia, spracovanie chýb, frekvenciu synchronizácie, uchovávanie údajov a cenovú štruktúru. Cena za to je však reálna. Každý poskytovateľ prináša vlastný OAuth tok, schému, špecifiká, limity požiadaviek, správanie webhookov, certifikáciu a priebežnú údržbu.

Zjednotené účtovné API (Unified Accounting APIs)

Zjednotené API ponúka jedno rozhranie pre viaceré účtovné systémy a normalizuje entity, ako sú zákazníci, faktúry, dodávatelia, účty, platby a produkty. Dokáže skrátiť počiatočný čas vývoja. Neodstraňuje však zložitosť integrácie a správať sa tak, akoby ju odstraňovalo, je bežnou chybou.

Predtým, než sa zaviažete k spolupráci, opýtajte sa: Ktoré poskytovateľa a operácie sú podporované? Fungujú zápisy, alebo iba čítania? Sú zápisy synchrónne alebo zaradené do fronty? Sú polia špecifické pre poskytovateľa dostupné cez passthrough? Sú údaje vo vyrovnávacej pamäti a aké sú čerstvé? Kto rieši výpadky poskytovateľa a zmeny API? Je cenová politika za volanie, za prepojený účet, za záznam alebo formou poplatku za platformu? Môžete exportovať svoje mapovania a čisto sa odpojiť? Pojem „zjednotený“ málokedy znamená „rovnaká funkčnosť u všetkých poskytovateľov“.

Vložená účtovná kniha (Embedded ledger)

Ak je hlavným problémom vašej platformy vedenie účtovníctva pre vašich používateľov, a nie jeho zrkadlenie do ich existujúcich kníh, vložená účtovná kniha mení celú rovnicu. Trhovisko s tisíckami predajcov alebo produkt SaaS, ktorý potrebuje vstavanú DPH v EÚ pripravenú na audit a dodržiavanie predpisov pre jednotlivé krajiny, lepšie uspeje, ak bude vlastníkom účtovného enginu, než keby prepájal N externých konektorov. To je pozícia spoločnosti Nordlet: skutočné účtovníctvo formou API, nemenné podvojné účtovníctvo, DPH pre jednotlivé krajiny s overovaním cez VIES a generovaním výkazov i.SAF, export SEPA a exporty reportov vo formátoch XLSX, PDF alebo JSON, a to všetko vo vnútri vášho produktu namiesto externého platobného procesu.

Rozhodovacie pravidlo, ktoré používam:

Situácia	Najvhodnejšia voľba
Vašu zákaznícku základňu dominuje jeden poskytovateľ účtovníctva; kľúčové je správanie špecifické pre daného poskytovateľa	Priamy konektor
Široké pokrytie poskytovateľov a rýchlosť uvedenia na trh sú dôležitejšie ako kontrola	Zjednotené API
Ste platforma alebo trhovisko, ktoré potrebuje prevádzkovať a vlastniť účtovníctvo, vrátane DPH v EÚ a auditných stôp	Vložená účtovná kniha (Nordlet)
Zmiešaná realita	Hybrid: zjednotené pre bežné toky, priame konektory pre strategických poskytovateľov

Odporúčaná integračná architektúra

Izolujte integráciu od core biznis logiky

Nerozptyľujte volania poskytovateľa naprieč fakturáciou, objednávkami, predplatným a reportingom. Vytvorte vyhradenú integračnú službu, ktorá obsahuje adaptéry poskytovateľov, správu pripojení OAuth, kanonické modely, mapovania ID, synchronizačné úlohy a fronty, koncové body webhookov, spracovanie opakovaných pokusov a mŕtvych front (dead-letter), denníky auditov a nástroje na rekonciliáciu. Vďaka tomu zabránite tomu, aby názov poľa zo systému Xero alebo QuickBooks presakoval do vášho doménového modelu.

Definujte úzky kanonický model

Modelujte iba tie pracovné postupy, ktoré podporujete. Typické objekty: zákazník, položka produktu alebo služby, faktúra, riadok faktúry, platba, dobropis, dodávateľ, účet, sadzba dane, mena, účtovný zápis.

Zachovajte rozdiely, ktoré ovplyvňujú účtovníctvo. Nespájajte do jednej roviny koncepty ako koncept (draft) verzus schválené verzus zaúčtované, sumy s daňou verzus sumy bez dane, dobropisy verzus záporné faktúry, priradenie platby verzus existencia platby, prípadne číslo faktúry viditeľné zákazníkom verzus ID objektu u poskytovateľa. Každý záznam by mal obsahovať ID v SaaS, ID poskytovateľa, názov poskytovateľa a verziu API, indikátor zdroja pravdy, stav, časové značky, čas poslednej synchronizácie, externú referenciu a stav chýb alebo rekonciliácie.

Udržiavajte explicitné tabuľky mapovania

Mapujte nájomníka SaaS na účtovnú organizáciu, zákazníka SaaS na kontakt u poskytovateľa, produkt SaaS na položku alebo účet poskytovateľa, faktúru SaaS na faktúru poskytovateľa, platbu SaaS na platbu poskytovateľa, daňovú kategóriu na daňový kód a kategóriu výnosov na účet hlavnej knihy.

Nikdy nepoužívajte mená alebo e-mailové adresy ako trvalé identifikátory. Názvy sa menia, existujú duplicity a dvaja zákazníci môžu zdieľať rovnaký e-mail. Uložte nemenné ID poskytovateľa a zachovajte pôvodné ID zo systému SaaS.

Pridajte stavové stroje (state machines)

Priraďte pripojeniu explicitné stavy: nepripojené, čaká sa na autorizáciu, pripojené, čaká sa na počiatočnú synchronizáciu, prebieha synchronizácia, v poriadku, prekročený limit požiadaviek, vyžaduje sa opätovná autorizácia, poskytovateľ nedostupný, odpojené, trvalo zlyhalo. Záznamom priraďte ich vlastné stavy: čaká sa, odoslané, potvrdené, zlyhané s možnosťou opakovania, zlyhané – vyžaduje zásah používateľa, odsúhlasené, zistený konflikt. Binárny príznak „pripojené/nepripojené“ neposkytuje vášmu tímu podpory žiadnu užitočnú informáciu.

OAuth a registrácia pripojenia

Použite tok autorizačného kódu (authorization code flow). Zákazník klikne na tlačidlo Pripojiť, váš server vytvorí krátkodobú autorizačnú transakciu, zákazník sa autentifikuje u poskytovateľa a udelí rozsahy oprávnení (scopes), vy vymeníte kód za tokeny, zistíte autorizovanú organizáciu, uložite pripojenie k správnemu nájomníkovi a zaradíte do fronty počiatočnú synchronizáciu.

Spätné volanie (callback) dôkladne overte: state oproti transakcii na strane servera, presné presmerovacie URI (redirect URI), vydávajúcu stranu (issuer) poskytovateľa a kontext nájomníka. RFC 9700, OAuth 2.0 Security Best Current Practice formalizuje aktuálne odporúčania: používajte PKCE s tokmi autorizačného kódu, vyhýbajte sa implicitným grantom a grantom s hesom a používajte presnú zhodu presmerovacích URI.

Vyžadujte rozsahy oprávnení s najmenšími možnými oprávneniami (least-privilege scopes). Ak nepotrebujete zapisovať, použite režim len na čítanie. Modely rozsahov oprávnení sa menia, preto nekopírujte staré príklady. Dokumentácia k OAuth od spoločnosti Xero uvádza, že široké účtovné rozsahy sa nahrádzajú granulárnymi, pričom novým aplikáciám sa granulárne rozsahy priraďujú od marca 2026 a široké rozsahy zostanú k dispozícii do septembra 2027.

Ukladajte tokeny výhradne na strane servera. Nikdy ich nevystavujte v JavaScriptovom kóde prehliadača, mobilným klientom, denníkom frontendu, analytickým nástrojom ani chybovým háseniam pre zákazníkov. Šifrujte v pokoji (at rest), redigujte z logov a uchovávajte metadáta pre každé pripojenie: šifrovaný prístupový a obnovovací token, platnosť, ID organizácie poskytovateľa, udelené rozsahy, čas vydania, posledné úspešné obnovenie, stav zrušenia platnosti.

Rotácia obnovovacích tokenov je miestom, kde produkcia zlyháva

Odpoveď pri obnove môže vrátiť nový obnovovací token. Najnovšiu hodnotu musíte uložiť atomicky, inak zákazníka zablokujete. Podľa častých otázok pre vývojárov od spoločnosti Xero, každá obnova vytvára nový obnovovací token, obnovovacie tokeny platia až 60 dní a existuje 30-minútová lehota na opätovný pokus s existujúcim tokenom v prípade straty odpovede. QuickBooks Online odporúča vývojárom ukladať najnovší obnovovací token z poslednej odpovede: obnovovacie tokeny platia až 100 dní a hodnota sa môže meniť až každých 24 hodín.

V praxi: používajte zámok obnovenia pre každé pripojenie, nahraďte obnovovací token atomicky, riešte prechodné zlyhania koncového bodu tokenov opakovanými pokusmi, vystavte jasný stav opätovnej autorizácie a nikdy neobnovujte pri každom volaní API, kým platí platný prístupový token.

Počiatočná synchronizácia

Počiatočnú synchronizáciu spustite ako úlohu na pozadí (background job). Neblokujte ňou spätné volanie OAuth ani používateľské rozhranie.

Robustná sekvencia: načítajte metadáta organizácie, získajte účty, sadzby daní, meny, kontakty a položky, uložte ID poskytovateľa a mapovania, importujte iba historické okno, ktoré produkt potrebuje, zariaďte závislé záznamy do fronty v poradí závislostí, zaznamenajte kontrolný bod (checkpoint) a označte pripojenie za zdravé až po úspešnej validácii.

Poradie závislostí je dôležité. Faktúra môže vyžadovať, aby najskôr existoval kontakt, položka, účet výnosov, daňový kód a mena. Nevytvárajte bezducho duplicity. Vykonávajte párovanie na základe uloženého externého ID, referencie dodanej zákazníkom, definovaného pravidla párovania alebo kroku explicitného výberu používateľom v nejednoznačných prípadoch.

Prírastková synchronizácia

Považujte webhooky za signály, nie za autoritatívne záznamy

Webhook zvyčajne informuje, že sa niečo zmenilo. Overte podpis, zaznamenajte surovú udalosť, rýchlo vráťte požadovanú úspešnú odpoveď, deduplikujte, zaradte do fronty následné načítanie, získajte aktuálny objekt od poskytovateľa, transakčne aplikujte aktualizáciu, aktualizujte kontrolný bod a smerujte zlyhania na opakovaný pokus alebo rekonciliáciu. Týmto spôsobom zvládnete neúplné dátové časti (payloads) a udalosti doručené mimo poradia.

Pravidlá poskytovateľov sa líšia, preto nesľubujte jedno univerzálne správanie. Webhooky Xero obsahujú podpis HMAC-SHA256 v hlavičke x-xero-signature, vyžadujú HTTPS, opakujú pokusy s klesajúcou frekvenciou až 24 hodín, po opakovanom zlyhaní sa môžu deaktivovať a dokážu uchovať udalosti až na 31 dní na opätovné prehratie po obnovení. QuickBooks Online overuje pomocou HMAC-SHA256 a overovacieho tokenu, očakáva HTTP 200 do troch sekúnd a opakuje pokusy podľa pevného harmonogramu, ktorý nakoniec prechádza do šesťhodinových intervalov, pričom Intuit odporúča asynchrónne spracovanie.

Deduplikácia a idempotentnosť

Doručenie aspoň raz (at-least-once delivery) je bežné. Očakávajte duplicitné webhooky, opakované pokusy po vypršaní časového limitu (timeout), kým zápas v skutočnosti úspešne prebehol, udalosti v zmenenom poradí a duplicitné kliknutia používateľov. Použite ID udalosti poskytovateľa, ak je k dispozícii, jedinečný kľúč udalosti v trvalom úložisku, ID operácie vygenerované pred každým zápisom, obmedzenia jedinečnosti v databáze (database uniqueness constraints), sémantiku upsert a rekonciličný dotaz po nejednoznačných vypršaniach časových limitov.

Nečakajte, že každé účtovné API ponúka natívne idempotentné kľúče. Ak ich poskytovateľ nemá, uložte interný kľúč operácie a pred opakovaním skontrolujte, či očakávaný vzdialený objekt už neexistuje. Vzory zo správy idempotentných požiadaviek od Stripe a všeobecné odporúčania pre idempotentnosť webhookov sa tu dajú dobre uplatniť.

Polling a detekcia zmien

Kombinujte webhooky s pravidelným dopytovaním (polling). Webhooky sa môžu deaktivovať, oneskoriť, stratiť nesprávnou konfiguráciou alebo byť obmedzené na určité objekty. Xero podporuje hlavičku If-Modified-Since pre zmeny po časovej značke UTC, ale jeho dokumentácia varuje, že nie každá zmena aktualizuje UpdatedDateUTC, takže niektoré čiastočne zaplatené transakcie a polia kontaktov sa prostredníctvom tohto filtra nezobrazia. Funkcia Change Data Capture v QuickBooks Online sleduje zmeny za predchádzajúcich 30 dní, obmedzuje odpovede na 1 000 objektov, vracia zmazané entity so stavom Deleted a najlepšie funguje s kratšími oknami dopytovania.

Ukladajte kontrolný bod pre každého poskytovateľa a nájomníka a používajte prekrývajúce sa okná. Vyžiadajte si zmeny od chvíle mierne predchádzajúcej poslednému kontrolnému bodu, následne deduplikujte podľa ID poskytovateľa a verzie úprav. To vás ochráni pred nesúladom hodín (clock skew) a čiastočnými zlyhaniami.

Účtovná integrita údajov

Toto je časť, ktorá oddeľuje fungujúcu integráciu od dôveryhodnej.

Daňové správanie nie je zameniteľné. Dokumentácia Xero uvádza, že faktúry, dobropisy a objednávky predvolene používajú sumy bez dane, ak nie je nastavené pole LineAmountTypes, pričom príjmy a bankové transakcie štandardne obsahujú daň v cene a manuálne denníky nemajú daň žiadnu. Používajte pole TaxType, nie názov daňovej sadzby. Nikdy nepredpokladajte, že „20 % DPH“ jednoznačne identifikuje daňový kód; môže sa líšiť podľa krajiny, typu transakcie, dátumu účinnosti a konfigurácie organizácie. Tu sa DPH pre viaceré krajiny v EÚ stáva nákladnou, ak sa robí ručne, a práve tu si vložená kniha s vstavaným dodržiavaním predpisov pre jednotlivé krajiny obhájí svoje miesto.

Pre peniaze používajte desatinnú aritmetiku alebo pevnú presnosť (fixed-precision), nikdy binárnu plávajúcu rádovú čiarku (floating point). Ukladajte kód meny a presnosť, mernú sumu, množstvo, zľavu, sumu dane, čistú sumu, hrubú sumu a výmenný kurz. Jasne sa rozhodnite, či odosielate sumy na úrovni riadkov a necháte poskytovateľa vypočítať celkové sumy, alebo odošlete vopred vypočítaný súčet. Miešanie týchto dvoch prístupov vytvára zaokrúhľovacie rozdiely, ktoré váš účtovník určite odhalí.

Na účty hlavnej knihy sa odvolávajte prostredníctvom ID poskytovateľa alebo kódu, nie zobrazovaného názvu. Pred zápisom overte, či sú účty, daňové kódy, zákazníci, položky a mena aktívne a podporované. Zlyhanie zápisu faktúry býva problémom mapovania alebo konfigurácie, nie prechodnou chybou API, takže používateľské rozhranie by malo vysvetliť spôsob nápravy namiesto zobrazenia hlášky „synchronizácia zlyhala“.

Nepredpokladajte rovnocennosť objektov. Pojem „platba“ môže znamenať príjem, priradenie, vklad, bankovú transakciu alebo účtovný zápis. Predplatné v SaaS nemusí čisto pasovať na „faktúru“ v účtovníctve. Skôr než vyberiete objekt API, definujte účtovnú udalosť, ktorú chcete reprezentovať. Pozrite si dokumentáciu k platbám v systéme Xero, kde je uvedené, ako jeden poskytovateľ modeluje túto oblasť.

Limity požiadaviek (Rate limits) a verzionovanie

Limity sa zvyčajne vymedzujú pre nájomníka, organizáciu, aplikáciu alebo ich kombináciu. Podľa častých otázok k limitom pre Xero: päť súbežných požiadaviek na nájomníka, 60 za minútu na nájomníka, 5 000 za deň na nájomníka a 10 000 za minútu naprieč celou aplikáciou, spolu s hlavičkami zostávajúcich limitov a hlavičkou Retry-After pri kóde 429. QuickBooks Online dokumentuje 500 požiadaviek za minútu a 10 za sekundu na ID oblasti, pričom dávkový koncový bod podporuje až 30 operácií na požiadavku.

Zostavte obmedzovanie počtu požiadaviek pre jednotlivých nájomníkov, globálne obmedzovanie priepustnosti, exponenciálny návrat s náhodným rozptylom (exponential backoff with jitter), rešpektovanie hlavičky Retry-After, obmedzenú súbežnosť, stránkovanie a metriky pre stavové kódy 429 a zostávajúcu kvótu. Nepoužívajte neobmedzenú paralelizmus pri importoch; jeden veľký zákazník môže vyčerpať všetky ostatné úlohy pre daného nájomníka.

Pripnite alebo explicitne spravujte verzie API. QuickBooks Online štandardne používa vedľajšiu verziu 75 (minor version 75), ak nie je špecifikovaná žiadna iná. Centralizujte verzie v konfigurácii, spúšťajte testy zmlúv (contract tests) v testovacích prostrediach (sandboxes), sledujte poznámky k vydaniu (release notes) a zaobchádzajte s neznámymi poliami v odpovediach tak, aby boli spätne kompatibilné. Testovacie prostredia nebudú reprodukovať každú produkčnú podmienku, preto pred spustením otestujte odpojenie, opätovné pripojenie, odvolaný súhlas, vypršané tokeny, limity požiadaviek a úpravy na strane poskytovateľa.

Čo by som postavil najskôr

Ak by som s tým začínal zajtra, postupoval by som v tomto poradí:

Definujte presný účtovný pracovný postup: ktoré udalosti a objekty čítate alebo zapisujete.
Zvoľte stratégiu poskytovateľa: priamy, zjednotený, vložený alebo hybridný.
Vytvorte model pripojenia viazaný na nájomníka, obsahujúci ID organizácií poskytovateľa, rozsahy oprávnení, stav a metadáta tokenov.
Implementujte OAuth s tokom autorizačného kódu, PKCE, overovaním stavu, oprávneniami s najmenšími možnými právami a ukladaním tokenov na strane servera.
Zostavte jedného adaptéra poskytovateľa za stabilným interným rozhraním.
Vytvorte mapovania ID na nemenných ID poskytovateľa.
Najskôr implementujte čítania; pred akýmkoľvek zápisom importujte referenčné údaje.
Pridajte úlohu počiatočnej synchronizácie so stránkovaním, obmedzovaním požiadaviek, kontrolnými bodmi a usporiadaním závislostí.
Implementujte jeden úzky zápis (vytvorenie faktúry) až po overení mapovaní zákazníka, položky, dane a účtu.
Zabezpečte, aby zápisy umožňovali opakované pokusy pomocou interných ID operácií, obmedzení jedinečnosti a kontrol vzdialeného stavu.
Pridajte podpísané webhooky, ktoré rýchlo potvrdzujú príjem a spracúvajú sa asynchrónne.
Pridajte dopytovanie a rekonciliáciu, aby webhooky slúžili na zrýchlenie, a nie ako jediný zdroj pravdy.
Zámerne otestujte stavy zlyhania.
Pridajte nástroje podpory a auditné nástroje, vďaka ktorým budú zlyhania zrozumiteľné a opraviteľné.
Postupne rozširujte pokrytie objektov.

FAQ

Mám použiť zjednotené API alebo postaviť priame konektory?

Priamy konektor použite vtedy, keď vašu zákaznícku základňu dominuje jeden poskytovateľ alebo keď je kľúčové správanie špecifické pre daného poskytovateľa. Zjednotené API zvážte vtedy, keď je široké pokrytie a rýchlosť dôležitejšie ako kontrola. Ak vašou skutočnou potrebou je viesť účtovníctvo sami namiesto synchronizácie do systému zákazníka, ani jedna možnosť neodpovedá na vašu otázku – pozrite sa radšej na vloženú knihu, akou je Nordlet.

Sú webhooky dostatočné na udržanie synchronizácie?

Nie. Webhooky sa môžu deaktivovať, oneskoriť alebo stratiť a dátové časti môžu byť neúplné alebo doručené mimo poradia. Považujte ich za signály zmeny, následne si vyžiadajte aktuálny objekt a podporte ich pravidelným dopytovaním a rekonciliáciou.

Ako zabránim tomu, aby zlyhania obnovovacích tokenov zablokovali zákazníkov?

Ukladajte najnovší obnovovací token atomicky pri každej obnove, používajte zámok pre každé pripojenie, opakujte pokusy pri prechodných zlyhaniach koncového bodu tokenov a vystavte jasný stav opätovnej autorizácie. 30-minútová lehota systému Xero pomáha, ale záchranou je práve atomické ukladanie.

Môžem párovať záznamy podľa mena alebo e-mailu zákazníka?

Nie ako trvalý identifikátor. Názvy sa menia, vyskytujú sa duplicity a dvaja zákazníci môžu zdieľať rovnaký e-mail. Uložte nemenné ID poskytovateľa a ponechajte si vedľa neho vlastné ID zo systému SaaS.