SaaS-alustan pilvikirjanpitorajapinnan integrointi

Käytännön opas monen vuokralaisen (multi-tenant) kirjanpitointegraation rakentamiseen siten, että OAuth, verkkokoukut, verosäännöt ja täsmäytys toimivat korruptoimatta kirjanpitoa.

Useimmat tiimit, jotka päättävät "lisätä kirjanpidon" SaaS-tuotteeseensa, aloittavat kytkemällä HTTP-asiakasohjelman palveluntarjoajan rajapintaan ja lähettämällä laskun. Se toimii demossa. Se hajoaa ensimmäisen kerran, kun asiakas yhdistää kaksi kirjanpito-organisaatiota, ensimmäisen kerran, kun verkkokoukku (webhook) saapuu kahdesti, ja ensimmäisen kerran, kun käyttövaltuustunniste (refresh token) kierrätetään ja se katoaa kesken pyynnön. Tämän työn kestävä versio ei ole pelkkä asiakasohjelma. Se on integraatiokerros.

Kyseisen kerroksen on hallittava vuokralaisyhteyksiä, tunnisteiden tallennusta ja kiertoa, palveluntarjoajakohtaisia kirjanpitosääntöjä, tietueiden täsmäytystä (mapping), alustavaa ja inkrementaalista synkronointia, verkkokoukkujen vastaanottoa uudelleenyrityksillä ja kaksoiskappaleiden poistolla, nopeusrajoituksia (rate limits), versionhallintaa sekä auditointilokia (audit trail), jonka tukitiimisi pystyy lukemaan aamuyöllä kahdelta. Tämä artikkeli käy läpi kyseisen arkkitehtuurin ja tärkeimmät päätökset.

Hyödyllinen ajatusmalli:

SaaS-tuote → kirjanpitointegraatiopalvelu → palveluntarjoajan sovitin (tai yhtenäinen rajapinta) → asynkroninen synkronointi ja täsmäytys

Kirjanpitojärjestelmä pysyy pääkirjanpito-objektien totuuden lähteenä (source of truth): tileinä, verokoodeina, kirjatuttuina tapahtumina ja tositteina. SaaS-alustasi ylläpitää vakaita järjestelmien välisiä tunnisteita, synkronointitilaa, täsmäytysmetatietoa ja toiminnallista auditointilokia.

Mitä "pilvikirjanpitorajapinta" tässä todellisuudessa kattaa

Ilmaisu tarkoittaa yleensä isännöidyn kirjanpitoalustan, kuten QuickBooks Onlinen, Xeron, Sagen, Zoho Booksin tai alueellisen järjestelmän, rajapintaa. Se voi tarkoittaa myös yhtenäistä kirjanpitorajapintaa (unified accounting API), joka normalisoi useita palveluntarjoajia yhden liittymän taakse.

Asiat kannattaa pitää täsmällisinä, sillä toteutus vaihtelee tarkoituksen mukaan. Laskujen lukeminen raportointia varten ei ole sama tehtävä kuin laskujen luominen SaaS-toiminnasta, ostolaskujen kirjaaminen, asiakkaiden ja tuotteiden synkronointi, kirjanpitotositteiden kirjoittaminen tai aidon kaksisuuntaisen synkronoinnin pyörittäminen. Päätä, mitä näistä olet rakentamassa, ennen kuin kosketkaan rajapintapisteeseen.

Tämän artikkelin kannalta on tärkeää tehdä vielä yksi erottelu. Maksurajapinta siirtää rahaa. Pankkirajapinta noutaa tilitietoja. Laskutusrajapinta voi luoda asiakirjoja paljastamatta pääkirjanpitoa. Sulautettu kirjanpitotase (embedded accounting ledger) on puolestaan aivan eri asia: SaaS-yritys omistaa itse kirjanpito-ohjelmiston. Jälkimmäinen lähestymistapa on se, missä Nordlet toimii. Sen sijaan, että yhdistäisit tuotteesi asiakkaan ulkoiseen kirjanpitoon, Nordlet tarjoaa alustoille ja markkinapaikoille aidon kahdenkertaisen kirjanpidon, muuttumattoman auditointivalmiin pääkirjanpidon, EU:n arvonlisäveron käsittelyn ja tilitykset suoraan omassa tuotteessaan tyypitettyjä SDK-kirjastoja ja verkkokoukkuja hyödyntävän rajapintalähtöisen suunnittelun (API-first design with typed SDKs and webhooks) kautta. Jos olet markkinapaikka, joka päättää, pitäisikö integroida asiakkaan kirjanpitojärjestelmä vai pyörittää kirjanpitoa itse, kyseessä on todellinen risteyksekotaus, johon palaamme vielä.

Monen vuokralaisen arkkitehtuuri: rajaa jokainen yhteys kahdesti

SaaS-tuotteessa yksi sovellus yhdistää useisiin asiakasorganisaatioihin. Jokainen yhteys on rajattava sekä SaaS-vuokralaisen että palveluntarjoajan organisaatiotunnisteen, kuten Xero-vuokralaisen tunnisteen tai QuickBooks-realm-tunnisteen, perusteella.

Älä anna yhteystunnisteiden perustua pelkkään OAuth-käyttäjätunnukseen. Yksi käyttäjä voi valtuuttaa useita kirjanpito-organisaatioita, ja eri käyttäjät voivat yhdistää saman organisaation uudelleen ajan kuluessa. Jos teet tämän virheen, tulet jossain vaiheessa kirjanneeksi yhden asiakkaan laskun toisen asiakkaan kirjanpitoon, eikä siitä virheestä toivuta ilman vaivaa.

Ensimmäinen arkkitehtuuripäätös: suora liitin, yhtenäinen rajapinta vai sulautettu tase

Suorat palveluntarjoajaintegraatiot

Suora integraatio antaa eniten hallintaa: palveluntarjoajakohtaiset ominaisuudet, mukautetut kentät, virheiden käsittely, synkronointitiheys, tiedon säilytys ja kustannusrakenne. Hinta on kuitenkin todellinen. Jokainen palveluntarjoaja tuo mukanaan oman OAuth-kulkunsa, tietorakenteensa, erikoisuutensa, nopeusrajoituksensa, verkkokoukkukäyttäytymisensä, sertifiointinsa ja jatkuvan ylläpitonsa.

Yhtenäiset kirjanpitorajapinnat

Yhtenäinen rajapinta tarjoaa yhden liittymän useiden kirjanpitojärjestelmien yli ja normalisoi entiteettejä, kuten asiakkaita, laskuja, toimittajia, tilejä, maksuja ja tuotteita. Se voi lyhentää alkuperäistä toteutusaikaa. Se ei kuitenkaan poista integraation monimutkaisuutta, ja sen olettaminen sellaiseksi on yleinen virhe.

Kysy ennen sitoutumista: Mitä palveluntarjoajia ja toimintoja tuetaan? Toimivatko kirjoitukset vai pelkät luvut? Ovatko kirjoitukset synkronisia vai jonoihin asetettuja? Ovatko palveluntarjoajakohtaiset kentät saatavilla läpiviennin (passthrough) kautta? Onko data välimuistissa ja kuinka tuoretta se on? Kuka vastaa palveluntarjoajien käyttökatkoista ja rajapintamuutoksista? Onko hinnoittelu kutsua, linkitettyä tiliä, tietuetta vai alustamaksua kohden? Voitko viedä täsmäytyksesi ja katkaista yhteyden siististi? "Yhtenäinen" harvemmin tarkoittaa "ominaisuuksiltaan identtinen palveluntarjoajien välillä".

Sulautettu tase

Jos alustasi ydinongelma on käyttäjien kirjanpidon pyörittäminen eikä sen heijastaminen heidän omiin kirjoihinsa, sulautettu tase muuttaa laskelmaa. Markkinapaikka, jolla on tuhansia myyjiä, tai SaaS-tuote, joka tarvitsee sisäänrakennetun auditointivalmiin EU:n alv-käsittely ja maakohtaisen vaatimustenmukaisuuden, hyötyy enemmän kirjanpito-ohjelmiston omistamisesta kuin N kappaleen ulkoisten liitinten johdottamisesta. Tämä on Nordletin asemoituminen: todellinen kirjanpito rajapintana, muuttumaton kahdenkertainen kirjanpito, maakohtainen arvonlisävero VIES-varmennuksella ja i.SAF-rekisterin luonnilla, SEPA-vienti sekä raporttiviennit XLSX-, PDF- tai JSON-muodossa suoraan tuotteesi sisällä kolmannen osapuolen kassaprosessin sijaan.

Käyttämäni päätössääntö:

Tilanne	Sopivin ratvaisu
Yksi kirjanpitopalveluntarjoaja hallitsee asiakaskuntaasi; palveluntarjoajakohtainen toiminta on keskiössä	Suora liitin
Laaja palveluntarjoajien kattavuus ja markkinoille tulon nopeus ovat tärkeämpiä kuin hallinta	Yhtenäinen rajapinta
Olet alusta tai markkinapaikka, jonka täytyy pyörittää ja omistaa kirjanpito, mukaan lukien EU:n alv ja auditointilokit	Sulautettu tase (Nordlet)
Sekatodellisuus	Hybridi: yhtenäinen perustoiminnoille, suorat liittimet strategisille palveluntarjoajille

Suositeltu integraatioarkkitehtuuri

Eristä integraatio ydinliiketoimintalogiikasta

Älä hajauta palveluntarjoajakutsuja laskutuksen, tilausten, tilausten hallinnan ja raportoinnin sekaan. Rakenna omistettu integraatiopalvelu, joka sisältää palveluntarjoajan sovittimet, OAuth-yhteyksien hallinnan, kanoniset mallit, tunnisteiden täsmäytykset, synkronointityöt ja -jonot, verkkokoukkujen päätepisteet, uudelleenyritys- ja kuolleen kirjeen käsittelyn (dead-letter handling), auditointilokit sekä täsmäytystyökalut. Tämä pitää Xeron tai QuickBooks-järjestelmän kenttä nimet poissa verkkotunnusmallistasi.

Määritä suppea kanoninen malli

Mallinna vain ne työnkulut, joita tuet. Tyypillisiä objekteja: asiakas, tuote- tai palvelunimike, lasku, laskurivi, maksu, hyvityslasku, toimittaja, tili, verokanta, valuutta, kirjanpitotosite.

Säilytä kirjanpitoon vaikuttavat erot. Älä litistä luonnosta hyväksyttyyn tai kirjattuun, verollista verottomaan määrään, hyvityslaskua negatiiviseen laskuun, maksun kohdistusta maksun olemassaoloon tai asiakasrajapinnan laskunumeroa palveluntarjoajan objekti-id:hen. Jokaisella tietueella tulisi olla SaaS-tunniste, palveluntarjoajan tunniste, palveluntarjoajan nimi ja rajapintaversio, totuuden lähteen ilmaisin, tila, aikaleimat, viimeisin synkronointiaika, ulkoinen viite sekä virhe- ja täsmäytystila.

Ylläpidä selkeitä täsmäytystauluja

Yhdistä SaaS-vuokralainen kirjanpito-organisaatioon, SaaS-asiakas palveluntarjoajan yhteyshenkilöön, SaaS-tuote palveluntarjoajan nimikkeeseen tai tiliin, SaaS-lasku palveluntarjoajan laskuun, SaaS-maksu palveluntarjoajan maksuun, veroluokka verokoodiin ja tuloluokka kirjanpitotiliin.

Älä koskaan käytä nimiä tai sähköposteja pysyvinä tunnisteina. Nimet muuttuvat, kaksoiskappaleita on olemassa, ja kaksi asiakasta voi jakaa saman sähköpostin. Tallenna palveluntarjoajan muuttumaton tunniste ja säilytä alkuperäinen SaaS-tunniste.

Lisää tila-automaatit (state machines)

Anna yhteydelle selkeät tilat: ei yhdistetty, valtuutus vireillä, yhdistetty, alustava synkronointi vireillä, synkronoidaan, terve, nopeusrajoitettu, uudelleenvaltuutus vaaditaan, palveluntarjoaja poissa käytöstä, katkaistu, pysyvästi epäonnistunut. Anna tietueille omat tilansa: vireillä, lähetetty, vahvistettu, epäonnistunut-uudelleenyritettävissä, epäonnistunut-vaatii-käyttäjän-toimia, täsmäytetty, ristiriita havaittu. Binaarinen "yhdistetty/ei yhdistetty" -lippu ei kerro tukitiimillesi mitään hyödyllistä.

OAuth ja yhteyden käyttöönotto (onboarding)

Käytä valtuutuskoodivuota (authorization code flow). Asiakakas napsauttaa Yhdistä, palvelimesi luo lyhytikäisen valtuutustapahtuman, asiakas tunnistautuu palveluntarjoajalla ja myöntää käyttöoikeudet, vaihdat koodin tunnisteisiin, löydät valtuutetun organisaation, tallennat yhteyden oikeaa vuokralaista vasten ja asetat alustavan synkronoinnin jonoon.

Validoi paluukutsu huolellisesti: state-parametri palvelimenpuolista tapahtumaa vasten, tarkka uudelleenohjaus-URI (redirect URI), palveluntarjoajan myöntäjä ja vuokralaiskonteksti. RFC 9700, OAuth 2.0 Security Best Current Practice virallistaa nykyiset ohjeet: käytä PKCE-varmennetta valtuutuskoodivuon kanssa, vältä implisiittisiä ja salasanapohjaisia myöntöjä ja käytä tarkkaa uudelleenohjaus-URI:n täsmäytystä.

Pyydä vain tarvittavat vähimmäisoikeudet (least-privilege scopes). Käytä vain luku-oikeuksia silloin, kun et tarvitse kirjoitusoikeutta. Käyttöoikeusmallit muuttuvat, joten älä kopioi vanhoja esimerkkejä. Xeron OAuth-dokumentaatio huomauttaa, että laajoja kirjanpito-oikeuksia korvataan rakeisemmilla, ja uusiin sovelluksiin on määritetty rakeiset oikeudet maaliskuusta 2026 alkaen laaja-alaisten oikeuksien pysyessä saatavilla syyskuuhun 2027 saakka.

Tallenna tunnisteet vain palvelinpuolelle. Älä koskaan altista niitä selaimen JavaScriptille, mobiiliasiakkaille, käyttöliittymän lokeille, analytiikalle tai asiakkaille näytettäville virheilmoituksille. Salaa levossa, peitä lokeista ja säilytä yhteyskohtaista metatietoa: salatut käyttö- ja päivitystunnisteet, vanhenemisaika, palveluntarjoajan organisaatiotunniste, myönnetyt oikeudet, myöntöaika, viimeisin onnistunut päivitys, kumoamistila.

Käyttövaltuustunnisteen kierrätys on kohta, jossa tuotanto hajoaa

Päivitysvastaus saattaa palauttaa uuden käyttövaltuustunnisteen. Uusin arvo on tallennettava atomisesti, tai muuten lukitset asiakkaan ulos. Xeron kehittäjien UKK:n mukaan jokainen päivitys tuottaa uuden päivitystunnisteen, päivitystunnisteet kestävät jopa 60 päivää, ja tarjolla on 30 minuutin armonaika yrittää uudelleen olemassa olevalla tunnisteella, jos vastaus katoaa. QuickBooks Online kehottaa kehittäjiä tallentamaan uusimman päivitystunnisteen tuoreimmasta vastauksesta: päivitystunnisteet kestävät jopa 100 päivää, ja arvo voi kierrättää jopa 24 tunnin välein.

Käytännössä: käytä yhteytykohtaista päivityslukkoa, korvaa päivitystunniste atomisesti, käsittele tilapäiset tunnisteen päätepisteen virheet uudelleenyrityksillä, tuo esiin selkeä uudelleenvaltuutustila äläkä koskaan päivitä jokaisella rajapintakutsulla niin kauan kuin voimassa oleva käyttötunniste on jäljellä.

Alustava synkronointi

Suorita alustava synkronointi taustatyönä. Älä estä OAuth-paluukutsua tai käyttöliittymää sen vuoksi.

Vankka järjestys: hae organisaation metatiedot, hae tilit, verokannat, valuutat, yhteystiedot ja nimikkeet, tallenna palveluntarjoajan tunnisteet ja täsmäytykset, tuo vain tuotteen tarvitsema historiallinen ikkuna, aseta riippuvaiset tietueet jonoon riippuvuusjärjestyksessä, kirjaa tarkistuspiste (checkpoint) ja merkitse yhteys terveeksi vasta validoinnin jälkeen.

Riippuvuusjärjestyksellä on väliä. Lasku saattaa vaatia yhteystiedon, nimikkeen, tulotilin, verokoodin ja valuutan olemassaoloa ensin. Älä luo kaksoiskappaleita sokeasti. Täsmää tallennetun ulkoisen tunnisteen, asiakkaan toimittaman viitteen, määritetyn täsmäytyssäännön tai epäselvissä tapauksissa selkeän käyttäjän valintavaiheen perusteella.

Inkrementaalinen synkronointi

Käsittele verkkokoukkuja signaaleina, älä virallisina tietueina

Verkkokoukku kertoo yleensä, että jokin muuttui. Varmista allekirjoitus, tallenna raakatapahtuma, palauta vaadittu onnistumasta nopeasti, poista kaksoiskappaleet, aseta seurantahaku jonoon, hae nykyinen objekti palveluntarjoajalta, sovella päivitystapahtuma transaktiomuotoisesti, päivitä tarkistuspiste ja ohjaa epäonnistumiset uudelleenyritykseen tai täsmäytykseen. Tämä käsittelee epätäydelliset tietokuormat ja väärässä järjestyksessä saapuvat tapahtumat.

Palveluntarjoajien säännöt vaihtelevat, joten älä lupaa yhtä yleistä toimintatapaa. Xeron verkkokoukut sisältävät HMAC-SHA256-allekirjoituksen x-xero-signature-otsakkeessa, vaativat HTTPS-yhteyttä, yrittävät uudelleen laskevalla tiheydellä jopa 24 tunnin ajan, voidaan poistaa käytöstä toistuvien epäonnistumisten jälkeen ja voivat tallentaa tapahtumia jopa 31 päivän ajan toistoa varten palautumisen jälkeen. QuickBooks Online varmistaa allekirjoituksen HMAC-SHA256:lla ja varmentajamerkkijonolla, odottaa HTTP 200 -vastausta kolmen sekunnin kuluessa ja yrittää uudelleen kiinteällä aikataululla, joka lopulta tasaantuu kuuden tunnin välein Intuitin suositellessa asynkronista käsittelyä.

Kaksoiskappaleiden poisto ja idempotenssi

Vähintään kerran toteutuva toimitus (at-least-once delivery) on normaalia. Odota kaksoiskappaleisia verkkokoukkuja, uudelleenyrityksiä aikakatkaisun jälkeen, jolloin kirjoitus itse asiassa onnistui, uudelleenjärjestettyjä tapahtumia ja käyttäjien kaksoisnapsautuksia. Käytä palveluntarjoajan tapahtumatunnistetta, jos sellainen on saatavilla, ainutlaatuista tapahtuma avainta kestävässä tallennustilassa, ennen jokaista kirjoitusta luotua operaatiotunnistetta, tietokannan ainutlaatuisuusrajoitteita, upsert-semantiikkaa ja täsmäytyskyselyä epävarmojen aikakatkaisujen jälkeen.

Älä oleta, että jokainen kirjanpitorajapinta tarjoaa natiivit idempotenssiavaimet. Jos palveluntarjoaja ei tarjoa sitä, tallenna sisäinen operaatioavain ja tarkista, onko odotettu etäobjekti jo olemassa ennen uudelleenyritystä. Mallit Stripen idempotenteista pyynnöistä ja yleinen verkkokoukkujen idempotenssiohjeistus siirtyvät tänne hyvin.

Pollaus ja muutosten havaitseminen

Yhdistä verkkokoukut säännölliseen pollaukseen (polling). Verkkokoukut poistetaan käytöstä, ne viivästyvät, katoavat väärän määrityksen vuoksi tai rajoittuvat tiettyihin objekteihin. Xero tukee If-Modified-Since-otsaketta UTC-aikaleiman jälkeisille muutoksille, mutta sen dokumentaatio varoittaa, että kaikki muutokset eivät päivitä UpdatedDateUTC-arvoa, joten jotkut osittain maksetut tapahtumat ja yhteystietokentät eivät näy kyseisen suodattimen kautta. QuickBooks Onlinen Change Data Capture -muutosten seuranta seuraa edellisen 30 päivän muutoksia, rajoittaa vastaukset 1 000 objektiin, palauttaa poistetut entiteetit Deleted-tilassa ja toimii parhaiten lyhyemmiltä pollausikkunoilta.

Tallenna palveluntarjoaja- ja vuokralaiskohtainen tarkistuspiste ja käytä limittäisiä ikkunoita (overlap windows). Pyydä muutoksia hieman ennen viimeistä tarkistuspistettä ja poista sen jälkeen kaksoiskappaleet palveluntarjoajan tunnisteen ja muutosversion perusteella. Tämä suojaa kellonvääristymältä (clock skew) ja osittaisilta epäonnistumisilta.

Kirjanpitospesifi datan eheys

Tämä on se osa, joka erottaa toimivan integraation luotettavasta.

Verokäyttäytyminen ei ole keskenään vaihtokelpoista. Xeron dokumentaatio huomauttaa, että laskut, hyvityslaskut ja ostotilaukset ovat oletusarvoisesti verottomia, kun LineAmountTypes on asettamaton, kuitit ja pankkitapahtumat ovat oletusarvoisesti verollisia, ja manuaaliset tositteet ovat oletusarvoisesti verottomia. Käytä TaxType-kenttää, älä verokannan nimeä. Älä koskaan oleta, että "20 % alv" yksilöi verokoodin; se voi vaihdella maittain, tapahtumatyypin, voimaantulopäivän ja organisaation asetusten mukaan. Tässä kohtaa EU:n monen maan arvonlisävero tulee kalliiksi toteuttaa käsin, ja tässä kohtaa sisäänrakennettu tase sisäänrakennetulla maakohtaisella vaatimustenmukaisuudella ansaitsee paikkansa.

Käytä desimaali- tai kiinteän tarkkuuden aritmetiikkaa rahalle, älä koskaan binääristä liukulukua. Tallenna valuuttakoodi ja tarkkuus, yksikkösumma, määrä, alennus, verosumma, netto, brutto ja vaihtokurssi. Päätä selkeästi, lähetätkö rivitason summat ja annatko palveluntarjoajan laskea kokonaissummat, vai lähetätkö ennalta lasketun kokonaissumman. Näiden kahden sekoittaminen luo pyöristyseroja, jotka kirjanpitäjäsi tulee löytämään.

Viittaa kirjanpitotileihin palveluntarjoajan tunnisteella tai koodilla, älä näyttönimellä. Varmista ennen kirjoitusta, että tilit, verokoodit, asiakkaat, nimikkeet ja valuutta ovat aktiivisia ja tuettuja. Epäonnistunut laskun kirjoitus on yleensä täsmäytys- tai määritysongelma eikä ohimenevä rajapintavirhe, joten käyttöliittymän tulisi selittää korjaus sen sijaan, että se näyttää "synkronointi epäonnistui".

Älä oleta objektien vastaavuutta. "Maksu" voi tarkoittaa kuittia, kohdistusta, talletusta, pankkitapahtumaa tai kirjanpitotositetta. SaaS-tilaus ei välttämättä vastaa puhtaasti kirjanpidon laskua. Määritä se kirjanpitotapahtuma, jonka haluat esittää, ennen kuin valitset rajapintaobjektin. Katso Xeron maksujen dokumentaatiosta, kuinka yksi palveluntarjoaja mallintaa tämän.

Nopeusrajoitukset ja versionhallinta

Rajoitukset rajataan yleensä vuokralaisen, organisaation, sovelluksen tai näiden yhdistelmän perusteella. Xeron rajoituksien UKK:n mukaan: viisi samanaikaista pyyntöä vuokralaista kohden, 60 minuutissa vuokralaista kohden, 5 000 päivässä vuokralaista kohden ja 10 000 minuutissa sovelluksen yli, sekä jäljellä olevan rajan otsakkeet ja Retry-After 429-vastauksissa. QuickBooks Online kirjaa 500 pyyntöä minuutissa ja 10 sekunnissa realm-tunnistetta kohden eräpisteen tukien jopa 30 operaatiota pyyntöä kohden.

Rakenna vuokralaiskohtainen nopeusrajoitus, globaali kuristus (throttling), eksponentiaalinen takaisinveto satunnaistuksella (jitter), Retry-After-otsakkeen kunnioitus, rajattu samanaikaisuus, sivutus ja metriikat 429-vastauksista ja jäljellä olevasta kiintiöstä. Älä käytä rajoittamatonta rinnakkaisuutta tuonneissa; yksi suuri asiakas voi näivettää kaikki muut kyseisen vuokralaisen työt.

Kiinnitä tai hallitse rajapintaversioita erikseen. QuickBooks Online käyttää oletusarvoisesti aliversiota 75, kun mitään ei ole määritetty. Keskitä versiot määrityksiin, suorita sopimustestejä hiekkalaatikoissa, seuraa julkaisutietoja ja käsittele tuntemattomia vastauskenttiä eteenpäin yhteensopivina. Hiekkalaatikot eivät toista kaikkia tuotanto-olosuhteita, joten testaa yhteyden katkaisu, uudelleenyhdistys, peruutettu suostumus, vanhentuneet tunnisteet, nopeusrajoitukset ja palveluntarjoajan puoleiset muokkaukset ennen julkaisua.

Mitä rakentaisin ensin

Jos aloittaisin tämän huomenna, järjestyksessä:

Määritä tarkka kirjanpitotyönkulku: mitkä tapahtumat ja objektit luet tai kirjoitat.
Valitse palveluntarjoajastrategia: suora, yhtenäinen, sulautettu tai hybridi.
Rakenna vuokralaisrajattu yhteyspohjainen malli palveluntarjoajan organisaatiotunnisteilla, käyttöoikeuksilla, tilalla ja tunnisteen metatiedoilla.
Toteuta OAuth valtuutuskoodivuolla, PKCE-varmennuksella, tilan validoinnilla, vähimmäisoikeuksilla ja palvelinpuolen tunnisteiden tallennuksella.
Rakenna yksi palveluntarjoajan sovitin vakaan sisäisen rajapinnan taakse.
Luo tunnisteiden täsmäytykset palveluntarjoajan muuttumattomille tunnisteille.
Toteuta luvut ensin; tuo viitetiedot ennen mitään kirjoitusta.
Lisää alustava synkronointityö sivutuksella, nopeusrajoituksella, tarkistuspisteillä ja riippuvuusjärjestyksellä.
Toteuta yksi suppea kirjoitus (luo lasku) vasta kun asiakkaan, nimikkeen, veron ja tilin täsmäytykset on validoitu.
Tee kirjoituksista uudelleenyritysturvallisia sisäisillä operaatiotunnisteilla, ainutlaatuisuusrajoitteilla ja etätilan tarkistuksilla.
Lisää allekirjoitetut verkkokoukut, jotka kuittaavat nopeasti ja prosessoivat asynkronisesti.
Lisää pollaus ja täsmäytys, jotta verkkokoukut ovat kiihdytys eivätkä ainoa totuuden lähde.
Testaa virhetiloja tarkoituksella.
Lisää tuki- ja auditointityökalut, jotka tekevät virheistä selitettäviä ja korjattavia.
Laajenna objektikattavuutta asteittain.

FAQ

Pitäisikö minun käyttää yhtenäistä rajapintaa vai rakentaa suorat liittimet?

Käytä suoraa liitintä, kun yksi palveluntarjoaja hallitsee asiakkaitasi tai palveluntarjoajakohtainen toiminta on keskiössä. Harkitse yhtenäistä rajapintaa, kun laaja kattavuus ja nopeus ovat tärkeämpiä kuin hallinta. Jos todellinen tarpeesi on pyörittää kirjoja itse sen sijaan, että synkronoit asiakkaan järjestelmään, kumpikaan ei vastaa kysymykseen; tarkastele sen sijaan sulautettua tasetta, kuten Nordletia.

Riittävätkö verkkokoukut synkronassa pysymiseen?

Ei. Verkkokoukut poistetaan käytöstä, ne viivästyvät tai katoavat, ja tietokuormat voivat olla epätäydellisiä tai väärässä järjestyksessä. Käsittele niitä muutossignaaleina, hae nykyinen objekti jälkikäteen ja tue niitä säännöllisellä pollauksella ja täsmäytyksellä.

Miten estän käyttövaltuustunnisteen epäonnistumisia lukitsemasta asiakkaita ulos?

Tallenna uusin päivitystunniste atomisesti jokaisen päivityksen yhteydessä, käytä yhteytökohtaista lukkoa, yritä tilapäiset tunnisteen päätepisteen virheet uudelleen ja tuo esiin selkeä uudelleenvaltuutustila. Xeron 30 minuutin armonaika auttaa, mutta atominen tallennus on se, mikä pelastaa sinut.

Voinko täsmätä tietueita asiakkaan nimen tai sähköpostin perusteella?

Ei pysyvänä tunnisteena. Nimet muuttuvat, kaksoiskappaleita esiintyy, ja kaksi asiakasta voi jakaa saman sähköpostin. Tallenna palveluntarjoajan muuttumaton tunniste ja säilytä oma SaaS-tunnisteesi sen rinnalla.