Hogyan integráljunk felhőalapú könyvelési API-t egy SaaS-platformba

Gyakorlati útmutató olyan többcélú (multi-tenant) könyvelési integráció fejlesztéséhez, amely hibátlanul kezeli az OAuth folyamatokat, a webhookokat, az adószabályokat és az egyeztetéseket a főkönyv sérülése nélkül.

A legtöbb csapat, amely úgy dönt, hogy könyvelési funkcióval bővíti SaaS termékét, ott kezdi, hogy beköt egy HTTP-klientszoftvert a szolgáltató végpontjára, és elküld egy számlát. Ez egy demóban működik is. Azonban az első olyan alkalommal összeomlik, amikor egy ügyfél két könyvelési szervezetet kapcsol össze, amikor egy webhook kétszer érkezik meg, vagy amikor egy frissítési token (refresh token) a kérés közepén lecserélődik és elvész. Ennek a feladatnak a tartósan működő változata nem egy egyszerű kliens, hanem egy integrációs réteg.

Ennek a rétegnek kezelnie kell a bérlői (tenant) kapcsolatokat, a tokenek tárolását és forgatását, a szolgáltatóspecifikus könyvelési szabályokat, az adatszinkronizálást, a kezdeti és inkrementális szinkronizációt, a webhookok fogadását újrapróbálási logikával és deduplikációval, a sebességkorlátokat (rate limits), a verziókezelést, valamint egy olyan auditnaplót, amelyet az ügyfélszolgálati csapat hajnali kettőkor is képes értelmezni. Ez a cikk ezt az architektúrát és a legfontosabb döntéseket mutatja be.

Egy hasznos szemléletbeli modell:

SaaS termék → könyvelési integrációs szolgáltatás → szolgáltatói adapter (vagy egységesített API) → aszinkron szinkronizáció és egyeztetés

A könyvelési rendszer marad a főkönyvi adatok hiteles forrása (system of record): számlák, adókódok, lekönyvelt tranzakciók, könyvelési tételek. Az Ön SaaS platformja pedig megőrzi a stabil rendszerek közötti azonosítókat, a szinkronizációs állapotot, a leképezési metaadatokat és a műveleti auditnaplót.

Mit is takar valójában a „felhőalapú könyvelési API” ebben a kontextusban?

Ez a kifejezés általában egy üzemeltetett könyvelési platform (például a QuickBooks Online, a Xero, a Sage, a Zoho Books vagy egy regionális rendszer) API-ját jelenti. Jelenthet továbbá egy egységesített könyvelési API-t is, amely több szolgáltatót normalizál egyetlen felület mögött.

Érdemes pontosan fogalmazni, mivel a megvalósítás a céltól függően eltérő. A számlák olvasása jelentések készítéséhez nem ugyanaz a feladat, mint számlák létrehozása SaaS tevékenység alapján, szállítói számlák rögzítése, ügyfelek és termékek szinkronizálása, könyvelési tételek írása vagy egy valós kétirányú szinkronizáció futtatása. Mielőtt bármilyen végponthoz hozzáérne, határozza meg, pontosan mit épít.

Van még egy fontos különbség ehhez a cikkhez. Egy fizetési API pénzt mozgat. Egy banki API számlaadatokat kér le. Egy számlázási API anélkül hozhat létre dokumentumokat, hogy felfedné a főkönyvet. Egy beágyazott könyvelési főkönyv pedig megint más: a SaaS vállalat maga tulajdonolja magát a könyvelési motort. Ez utóbbi megközelítést képviseli a Nordlet. Ahelyett, hogy a termékét egy ügyfél külső könyveléséhez kapcsolná, a Nordlet valós kettős könyvvitelt, módosíthatatlan és auditra kész főkönyvet, EU áfa-kezelést és kifizetéseket biztosít a platformoknak és piactereknek saját termékükön belül, egy típusos SDK-kkal és webhookokkal ellátott, API-központú tervezésen keresztül. Ha Ön egy piacteret üzemeltet, és azon dilemmázik, hogy integrálja-e az ügyfél könyvelési rendszerét vagy inkább saját maga vezesse a könyvelést, ez egy valódi elágazás, amelyre még visszatérünk.

Többcélúság (Multi-tenancy): minden kapcsolatot kétszer kell hatókörbe (scope) vonni

Egy SaaS termékben egyetlen alkalmazás számos ügyfélszervezethez kapcsolódik. Minden kapcsolatot korlátozni kell mind a SaaS-bérlő, mind a szolgáltató szervezeti azonosítója (például a Xero bérlői azonosítója vagy a QuickBooks realm ID-je) alapján.

Ne az OAuth felhasználói azonosító alapján határozza meg a kapcsolatokat. Egy felhasználó több könyvelési szervezetet is engedélyezhet, és egy szervezetet idővel különböző felhasználók is újra összekapcsolhatják. Ha ezt elrontja, előbb-utóbb az egyik ügyfél számláját egy másik ügyfél könyvelésébe fogja könyvelni, és ez nem olyan hiba, amelyből csendben fel lehet épülni.

Az első építészeti döntés: közvetlen összekötő, egységesített API vagy beágyazott főkönyv

Közvetlen szolgáltatói integrációk

A közvetlen integráció biztosítja a legtöbb irányítást: szolgáltatóspecifikus funkciók, egyedi mezők, hibakezelés, szinkronizációs gyakoriság, adatok megőrzése és költségszerkezet. Ennek ára van. Minden szolgáltató saját OAuth folyamattal, sémafelépítéssel, sajátosságokkal, sebességkorláttal, webhook-viselkedéssel, tanúsítási igénnyel és folyamatos karbantartási igénnyel érkezik.

Egységesített (unified) könyvelési API-k

Egy egységesített API egyetlen felületet kínál több könyvelési rendszerhez, normalizálva az olyan entitásokat, mint az ügyfelek, számlák, beszállítók, számlaszámok, kifizetések és termékek. Ezzel lefaragható a kezdeti fejlesztési idő. Ugyanakkor ez nem szünteti meg az integráció összetettségét, és gyakori hiba úgy kezelni, mintha így lenne.

Mielőtt elkötelezné magát, tegye fel a következő kérdéseket: Mely szolgáltatók és műveletek támogatottak? Az írás is működik, vagy csak az olvasás? Az írások szinkronok vagy sorba állítottak (queued)? Elérhetők a szolgáltatóspecifikus mezők áteresztő (passthrough) módon? Az adatok cache-eltek, és ha igen, mennyire frissek? Ki kezeli a szolgáltató leállásait és az API-változásokat? Az árazás hívásonként, kapcsolódó fiókonként, rekordonként vagy platformdíjonként történik? Ki tudja exportálni a leképezéseket és tisztán lecsatlakozni? Az „egységesített” ritkán jelenti azt, hogy „szolgáltatótól függetlenül azonos képességű”.

Beágyazott főkönyv

Ha platformjának alapvető problémája az, hogy könyvelést kell futtatnia a felhasználói számára, és nem pusztán tükröznie azt a meglévő könyveikbe, a beágyazott főkönyv átírja a képletet. Egy ezer eladót tömörítő piactér vagy egy olyan SaaS termék, amelynek beépített, auditra kész EU áfa-megfelelőségre és országonkénti megfelelésekre van szüksége, jobban jár, ha saját tulajdonában tudja a könyvelési motort, ahelyett, hogy N külső csatlakozót kötne be. Ez a Nordlet pozicionálása: valós könyvek API-ként, módosíthatatlan kettős könyvvitel, országonkénti áfa VIES-ellenőrzéssel és i.SAF-nyilvántartás-generálással, SEPA-exporttal, valamint XLSX-, PDF- vagy JSON-formátumú jelentésexporttal, mindez közvetlenül a terméken belül, és nem egy külső fizetési folyamat részeként.

Egy általam használt döntési szabály:

Helyzet	Legjobb illeszkedés
Egy könyvelési szolgáltató dominálja az ügyfélkört; a szolgáltatóspecifikus viselkedés kulcsfontosságú	Közvetlen összekötő
A széles körű szolgáltatói lefedettség és a piacra jutási sebesség fontosabb, mint az irányítás	Egységesített API
Ön egy olyan platform vagy piactér, amelynek saját magának kell futtatnia és birtokolnia a könyveket EU áfával és auditnaplókkal	Beágyazott főkönyv (Nordlet)
Vegyes valóság	Hibrid: egységesített a gyakori folyamatokhoz, közvetlen összekötők a stratégiai szolgáltatókhoz

Ajánlott integrációs architektúra

Az integráció elszigetelése az alapvető üzleti logikától

Ne szórja szét a szolgáltatóhívásokat a számlázás, a rendelések, az előfizetések és a jelentéskészítés között. Hozzon létre egy dedikált integrációs szolgáltatást, amely tartalmazza a szolgáltatói adaptereket, az OAuth kapcsolatkezelést, a kanonikus modelleket, az azonosító-leképezéseket, a szinkronizációs feladatokat és sorokat, a webhook-végpontokat, az újrapróbálási és hialkalmatlan (dead-letter) kezelést, az auditnaplókat, valamint az egyeztetési eszközöket. Ezzel elkerülhető, hogy egy Xero vagy QuickBooks mezőnév kiszivárogjon a saját tartományi modelljébe.

Határozzon meg egy szűk kanonikus modellt

Csak azokat a munkafolyamatokat modellezze, amelyeket támogat. Tipikus objektumok: ügyfél, termék vagy szolgáltatási tétel, számla, számlasor, fizetés, jóváíró számla (credit note), beszállító, számlaszám, adókulcs, pénznem, könyvelési tétel.

Őrizze meg a könyvelést befolyásoló különbségeket. Ne mossa össze a vázlat (draft) és a jóváhagyott (approved) vagy könyvelt (posted) állapotokat, az áfát tartalmazó (tax-inclusive) és áfa nélküli (tax-exclusive) összegeket, a jóváírásokat és a negatív számlákat, a fizetés hozzárendelését és a fizetés létezését, vagy az ügyfél felé mutató számlaszámot és a szolgáltatói objektumazonosítót. Minden rekordnak tartalmaznia kell a SaaS azonosítót, a szolgáltató azonosítóját, a szolgáltató nevét és API verzióját, a hiteles forrás (source-of-truth) jelölőt, az státuszt, az időbélyegeket, a legutóbbi szinkronizáció idejét, a külső hivatkozást, valamint a hiba-/egyeztetési státuszt.

Tartson fenn explicit leképezési táblázatokat

Kösse össze a SaaS-bérlőt a könyvelési szervezettel, a SaaS-ügyfelet a szolgáltatói partnerrel, a SaaS-terméket a szolgáltatói tétellel vagy számlával, a SaaS-számlát a szolgáltatói számlával, a SaaS-fizetést a szolgáltatói fizetéssel, az adókategóriát az adókóddal, és a bevételi kategóriát a főkönyvi számlával.

Soha ne használjon neveket vagy e-mail címeket állandó azonosítóként. A nevek változnak, duplikációk léteznek, és két ügyfél osztozhat ugyanazon az e-mail címen. Tárolja a szolgáltató módosíthatatlan (immutable) azonosítóját, és tartsa meg az eredeti SaaS azonosítót.

Vezessen be államgépezeteket (state machines)

Adjon a kapcsolatnak kifejezett állapotokat: nincs csatlakoztatva, engedélyezés folyamatban, csatlakoztatva, kezdeti szinkronizáció folyamatban, szinkronizálás alatt, egészséges, sebességkorlátozva, újraengedélyezés szükséges, a szolgáltató nem érhető el, leválasztva, véglegesen sikertelen. A rekordoknak is adjon saját állapotokat: függőben, elküldve, megerősítve, sikertelen-újrapróbálható, sikertelen-felhasználói-beavatkozást-igényel, egyeztetve, ütközés észlelve. Egy bináris „csatlakoztatva/nincs csatlakoztatva” jelző semmit sem mond az ügyfélszolgálatnak.

OAuth és a kapcsolat felvétele (onboarding)

Használja az engedélyezési kód folyamatot (authorization code flow). Az ügyfél a Csatlakozás gombra kattint, a szervere létrehoz egy rövid élettartamú engedélyezési tranzakciót, az ügyfél hitelesíti magát a szolgáltatónál és megadja a hatóköröket, Ön beváltja a kódot a tokenekre, felderíti a felhatalmazott szervezetet, eltárolja a kapcsolatot a megfelelő bérlőhöz, és sorba állít egy kezdeti szinkronizációt.

Óvatosan érvényesítse a visszahívást (callback): ellenőrizze a state paramétert egy kiszolgáló oldali tranzakció ellenében, a pontos átirányítási URI-t, a szolgáltató kiállítóját és a bérlői kontextust. Az RFC 9700, az OAuth 2.0 Security Best Current Practice formalizálja a jelenlegi iránymutatásokat: használjon PKCE-t az engedélyezési kódos folyamatokhoz, kerülje az implicit és a jelszó alapú jogosultságokat, és alkalmazzon pontos átirányítási URI-egyeztetést.

A legkisebb jogosultság elvének megfelelő hatóköröket (least-privilege scopes) kérjen. Használjon csak olvasható hozzáférést (read-only), ahol nincs szükség írásra. A hatókörmodellek változnak, ezért ne másoljon régi példákat. A Xero OAuth dokumentációja megjegyzi, hogy a széles körű könyvelési hatóköröket részletesebbek váltják fel, az új alkalmazásokhoz 2026 márciusa óta részletes hatókörök tartoznak, a széles körű hatókörök pedig a tervek szerint 2027 szeptemberéig maradnak elérhetők.

A tokeneket kizárólag a kiszolgáló oldalon tárolja. Soha ne tegye ki őket a böngésző JavaScriptjének, a mobilklienseknek, a frontend naplóknak, az analitikának vagy az ügyfél felé mutató hibaüzeneteknek. Titkosítsa őket nyugalom állapotában (at rest), rejtse ki a naplókból, és tartson fenn kapcsolatonkénti metaadatokat: titkosított hozzáférési és frissítési tokeneket, lejárati időt, szolgáltatói szervezetazonosítót, megadott hatóköröket, kiállítási időt, az utolsó sikeres frissítést, és a visszavonási státust.

A frissítési token forgatása (refresh-token rotation) az a pont, ahol az éles rendszer elromlik

Egy frissítési válasz új frissítési tokent adhat vissza. A legújabb értéket atomi módon kell perzisztálnia, különben kizárja az ügyfelet. A Xero fejlesztői GYIK-je szerint minden frissítés új frissítési tokent hoz létre, a frissítési tokenek legfeljebb 60 napig érvényesek, és egy 30 perces türelmi idő áll rendelkezésre a meglévő tokennel történő újrapróbálkozáshoz, ha egy válasz elveszik. A QuickBooks Online arra utasítja a fejlesztőket, hogy tárolják a legutóbbi válaszból származó legfrissebb frissítési tokent: a frissítési tokenek legfeljebb 100 napig érvényesek, és az érték akár 24 óránként is foroghat.

A gyakorlatban: használjon kapcsolatonkénti frissítési zárolást, atomi módon cserélje ki a frissítési tokent, kezelje az átmeneti tokenvégpont-hibákat újrapróbálásokkal, tegyen láthatóvá egyértelmű újraengedélyezési állapotot, és soha ne frissítsen minden egyes API-hívásnál, amíg egy érvényes hozzáférési token rendelkezésre áll.

Kezdeti szinkronizáció

A kezdeti szinkronizációt háttérfeladatként futtassa. Ne blokkolja vele az OAuth visszahívást vagy a felhasználói felületet.

Egy robusztus sorrend: kérje le a szervezet metaadatait, töltse le a számlákat, az adókulcsokat, a pénznemeket, a partnereket és a tételeket, tárolja el a szolgáltatói azonosítókat és leképezéseket, csak a termék által igényelt történelmi időablakot importálja, függőségi sorrendben állítsa sorba a függő rekordokat, rögzítsen egy ellenőrzőpontot (checkpoint), és csak az érvényesítés után jelölje a kapcsolatot egészségesnek.

A függőségi sorrend számít. Előfordulhat, hogy egy számlához először léteznie kell egy partnernek, egy tételnek, egy bevételi számlának, egy adókódnak és egy pénznemnek. Ne hozzon létre vakon duplikációkat. Egyeztesse a rekordokat egy tárolt külső azonosító, egy ügyfél által megadott hivatkozás, egy meghatározott egyeztetési szabály vagy kétértelmű esetekben egy explicit felhasználói kiválasztási lépés alapján.

Inkrementális szinkronizáció

Kezelje a webhookokat jelzésekként, ne hiteles rekordokként

Egy webhook általában azt jelzi, hogy valami megváltozott. Ellenőrizze az aláírást, rögzítse a nyers eseményt, gyorsan adja vissza a szükséges sikeres választ, végezzen deduplikációt, állítson sorba egy utólagos lekérést, kérje le az aktuális objektumot a szolgáltatótól, tranzakcionálisan alkalmazza a frissítést, frissítse az ellenőrzőpontot, és irányítsa át a hibákat az újrapróbálási vagy egyeztetési sorba. Ez a megközelítés kezeli a hiányos hasznos adatokat (payload) és a nem sorrendhelyes eseményeket.

A szolgáltatói szabályok eltérőek, ezért ne ígérjen egyetemes viselkedést. A Xero webhookjai HMAC-SHA256 aláírást hordoznak a x-xero-signature fejlécben, HTTPS-t igényelnek, csökkenő gyakorisággal legfeljebb 24 órán át próbálkoznak újra, ismételt hiba esetén letilthatók, és az eseményeket helyreállítás utáni visszajátszás céljából legfeljebb 31 napig őrzik meg. A QuickBooks Online HMAC-SHA256-tal és ellenőrző tokennel végez hitelesítést, három másodpercen belül HTTP 200-as választ vár, és rögzített ütemterv szerint próbálkozik újra, amely végül hatórás intervallumokra áll be, az Intuit pedig az aszinkron feldolgozást javasolja.

Deduplikáció és idempotencia

A legalább egyszeri (at-least-once) kézbesítés a normális működés. Számítson duplikált webhookokra, időtúllépés miatti újrapróbálásokra, ahol az írás valójában sikeres volt, átrendeződött eseményekre és duplikált felhasználói kattintásokra. Használjon szolgáltatói eseményazonosítót, ha elérhető, egyedi eseménykulcsot a tartós tárolásban, minden írás előtt generált műveleti azonosítót, adatbázis-egyediségi megszorításokat, upsert szemantikát, valamint egyeztetési lekérdezést kétértelmű időtúllépések után.

Ne feltételezze, hogy minden könyvelési API natív idempotencia-kulcsokat kínál. Ha a szolgáltató nem biztosít ilyet, tároljon egy belső műveleti kulcsot, és az újrapróbálás előtt ellenőrizze, hogy a várt távoli objektum létezik-e már. A Stripe idempotens kéréseiből és az általános webhook-idempotencia útmutatóból származó minták itt jól alkalmazhatók.

Lekérdezés (polling) és változásdetektálás

Párosítsa a webhookokat időszakos lekérdezéssel. A webhookok letiltódhatnak, késhetnek, eltévedhetnek a hibás konfiguráció miatt, vagy bizonyos objektumokra korlátozódhatnak. A Xero támogatja az If-Modified-Since fejlécet a UTC időbélyeg utáni változásokhoz, de a dokumentációja figyelmeztet arra, hogy nem minden változás frissíti az UpdatedDateUTC mezőt, így egyes részben kifizetett tranzakciók és partneri mezők nem fognak megjelenni ezen a szűrőn keresztül. A QuickBooks Online Change Data Capture funkciója az előző 30 nap változásait követi nyomon, legfeljebb 1 000 objektumra korlátozza a válaszokat, a törölt entitásokat Deleted státusszal küldi vissza, és rövidebb lekérdezési ablakokkal működik a legjobban.

Tároljon szolgáltatónkénti és bérlőnknti ellenőrzőpontot, és használjon átfedési ablakokat. Kérje le a változásokat valamivel az utolsó ellenőrzőpont előtti időponttól kezdve, majd deduplikáljon a szolgáltatói azonosító és a módosítási verzió alapján. Ez védelmet nyújt az óraeltérések és a részleges hibák ellen.

Könyvelési adatintegritás

Ez az a rész, amely elválaszt egy működő integrációt a megbízhatótól.

Az adózási viselkedés nem felcserélhető. A Xero dokumentációja megjegyzi, hogy a számlák, a jóváírások és a beszerzési megrendelések alapértelmezés szerint áfa nélküliek, ha a LineAmountTypes nincs megadva, a bizonylatok és a banki tranzakciók alapértelmezés szerint áfát tartalmaznak, a kézi könyvelési tételek pedig alapértelmezés szerint adómentesek. Használja a TaxType mezőt, ne az adókulcs nevét. Soha ne feltételezze, hogy a „20% ÁFA” egyértelműen azonosít egy adókódot; ez országonként, tranzakciótípustól, hatálybalépési dátumtól és a szervezet konfigurációjától függően változhat. Itt válik költségessé az EU többországos áfájának kézi kezelése, és itt érdemli ki a helyét a beágyazott főkönyv a beépített, országonkénti megfeleléssel.

A pénzösszegekhez használjon decimális vagy rögzített pontosságú aritmetikát, soha ne bináris lebegőpontos számábrázolást. Perzisztálja a pénznemkódot és a pontosságot, az egységárat, a mennyiséget, a kedvezményt, az adó összegét, a nettó, a bruttó és az árfolyam értéket. Egyértelműen döntse el, hogy sor szintű összegeket küld, és hagyja, hogy a szolgáltató számítsa ki a végösszegeket, vagy előre kiszámított végösszeget küld. A kettő keverése olyan kerekítési eltéréseket okoz, amelyeket a könyvelője ki fog szúrni.

A főkönyvi számlákat szolgáltatói azonosító vagy kód alapján hivatkozza, ne megjelenítendő név alapján. Írás előtt ellenőrizze, hogy a számlák, az adókódok, az ügyfelek, a tételek és a pénznemek aktívak és támogatottak-e. A sikertelen számlaírás általában leképezési vagy konfigurációs probléma, nem pedig átmeneti API-hiba, ezért a felhasználói felületnek a javítást kell megmagyaráznia a „szinkronizáció sikertelen” üzenet helyett.

Ne tételezzen fel objektum-egyenértékűséget. A „fizetés” jelenthet bevételi bizonylatot, allokációt, betétet, banki tranzakciót vagy könyvelési tételt. Előfordulhat, hogy egy SaaS „előfizetés” nem képezhető le tisztán egy könyvelési „számlára”. Határozza meg a megjeleníteni kívánt könyvelési eseményt, mielőtt kiválaszt egy API-objektumot. Tekintse meg a Xero kifizetési dokumentációját arról, hogy az egyik szolgáltató hogyan modellezi ezt.

Sebességkorlátok (rate limits) és verziókezelés

A korlátok általában bérlő, szervezet, alkalmazás vagy ezek kombinációja szerint vannak hatókörbe vonva. A Xero korlátokra vonatkozó GYIK-je szerint: bérlőnként legfeljebb öt egyidejű kérés, percenként 60 bérlőnként, naponta 5 000 bérlőnként, és percenként 10 000 az egész alkalmazásra, a fennmaradó korlátot jelző fejlécekkel és a 429-es válaszok esetén megadott Retry-After értékkel. A QuickBooks Online percenként 500 kérést és realm ID-nként másodpercenként 10 kérést dokumentál, egy kérésenként legfeljebb 30 műveletet támogató kötegelt (batch) végponttal.

Építsen ki bérlőnkénti sebességkorlátozást, globális szabályozást (throttling), exponenciális hátrálást (backoff) véletlenszerű csúszással (jitter), a Retry-After tiszteletben tartását, korlátozott párhuzamosságot, lapozást, valamint a 429-es hibákra és a fennmaradó kvótára vonatkozó metrikákat. Az importálásokhoz ne használjon korlátlan párhuzamosságot; egyetlen nagy ügyfél kiéheztetheti az összes többi feladatot az adott bérlőn.

Rögzítse vagy kifejezetten kezelje az API-verziókat. A QuickBooks Online alapértelmezés szerint a 75-ös alverziót (minor version) használja, ha nincs más megadva. Központosítsa a verziókat a konfigurációban, futtasson szerződéses teszteket (contract tests) a tesztkörnyezeteken (sandboxes), figyelje a kiadási megjegyzéseket (release notes), és kezelje az ismeretlen válaszmezőket visszafelé kompatibilis módon. A tesztkörnyezetek nem adják vissza az összes éles körülményt, ezért indulás előtt tesztelje a lekapcsolást, az újracsatlakozást, a visszavont hozzájárulást, a lejárt tokeneket, a sebességkorlátokat és a szolgáltató oldali módosításokat.

Mit építenék meg először?

Ha holnap kezdeném ezt, az alábbi sorrendben haladnék:

Határozza meg a pontos könyvelési folyamatot: mely eseményeket és objektumokat olvassa vagy írja.
Válassza ki a szolgáltatói stratégiát: közvetlen, egységesített, beágyazott vagy hibrid.
Építsen ki egy bérlői hatókörű kapcsolatmodellt szolgáltatói szervezetazonosítókkal, hatókörökkel, státusszal és token metaadatokkal.
Valósítsa meg az OAuth-t az engedélyezési kód folyamattal, PKCE-vel, állapot-ellenőrzéssel, a legkisebb jogosultság elvének megfelelő hatókörökkel és kiszolgáló oldali tokentárolással.
Hozzon létre egy szolgáltatói adaptert egy stabil belső felület mögött.
Hozzon létre azonosító-leképezéseket a módosíthatatlan szolgáltatói azonosítókon.
Először az olvasásokat valósítsa meg; az írások előtt importálja a referenciatámogató adatokat.
Adjon hozzá egy kezdeti szinkronizációs feladatot lapozással, sebességkorlátozással, ellenőrzőpontokkal és függőségi sorrenddel.
Csak a partner, a tétel, az adó és a számlaszám leképezésének érvényesítése után valósítson meg egy szűk írást (számla létrehozása).
Tegye az írásokat újrapróbálás-biztossá belső műveleti azonosítókkal, egyediségi megszorításokkal és a távoli állapot ellenőrzésével.
Adjon hozzá aláírt webhookokat, amelyek gyorsan nyugtáznak és aszinkron módon dolgoznak fel.
Adjon hozzá lekérdezést és egyeztetést, hogy a webhookok gyorsítók legyenek, ne pedig az igazság egyetlen forrásai.
Célzottan tesztelje a hibamódokat.
Építsen ki olyan ügyfélszolgálati és audit eszközöket, amelyek érthetővé és javíthatóvá teszik a hibákat.
Fokozatosan bővítse az objektumlefedettséget.

FAQ

Egységesített API-t használjak, vagy építsek közvetlen összekötőket?

Használjon közvetlen összekötőt, ha egy szolgáltató dominálja az ügyfeleit, vagy a szolgáltatóspecifikus viselkedés kulcsfontosságú. Akkor érdemes egységesített API-t választani, ha a széles körű lefedettség és a sebesség fontosabb, mint az irányítás. Ha az igazi cél az, hogy saját maga vezesse a könyveket ahelyett, hogy egy ügyfél rendszerével szinkronizálna, egyik opció sem ad választ; tekintse meg inkább a Nordlethez hasonló beágyazott főkönyveket.

Elegendők a webhookok a szinkronban maradáshoz?

Nem. A webhookok letiltódhatnak, késhetnek vagy elveszhetnek, a hasznos adatok pedig lehetnek hiányosak vagy sorrenden kívüliek. Kezelje őket változási jelzésként, kérje le utána az aktuális objektumot, és támogassa meg őket időszakos lekérdezéssel és egyeztetéssel.

Hogyan akadályozhatom meg, hogy a frissítési tokenek hibái kizárják az ügyfeleket?

Minden frissítés során atomi módon perzisztálja a legújabb frissítési tokent, használjon kapcsolatonkénti zárolást, próbálja újra az átmeneti tokenvégpont-hibákat, és tegyen láthatóvá egyértelmű újraengedélyezési állapotot. A Xero 30 perces türelmi ideje segít, de az atomi perzisztálás az, ami megmenti a rendszert.

Összeilleszthetem a rekordokat ügyfélnév vagy e-mail cím alapján?

Állandó azonosítóként semmiképpen. A nevek változnak, duplikációk fordulnak elő, és két ügyfél osztozhat ugyanazon az e-mail címen. Tárolja a szolgáltató módosíthatatlan azonosítóját, és tartsa meg mellette a saját SaaS azonosítóját.