Sammanfattning
Leara har en egen, berikad datamodell. Produktdata, varianter, produktgrupper och kundregister ägs av Leara och skrivs till Fortnox. Bokföring, fakturanummer och betalstatus ägs av Fortnox och speglas till Leara. Fält som Fortnox saknar stöd för finns kvar i Leara och skrivs aldrig över av inkommande Fortnox-data. Integrationen är byggd i Learas egen backend utan mellanliggande iPaaS eller tredjepartsconnector. Allt körs i AWS-regionen eu-north-1 (Stockholm).Arkitektur
Integrationen är en del av Learas backend och består av fyra delar: en skrivkö mot Fortnox, en realtidsklient mot Fortnox händelsetjänst, en schemalagd avstämning och en separat tokentjänst. Apparna pratar aldrig direkt med Fortnox.All Fortnox-trafik går via Learas backend i AWS Stockholm.
Anslutning och behörighet
Kunden ansluter Fortnox i Learas webbapp med OAuth 2.0 (authorization code, offline-åtkomst). En administratör loggar in hos Fortnox, godkänner behörigheterna och skickas tillbaka till Leara. Ett Leara-konto kopplas till exakt ett Fortnox-bolag; underanvändare i Leara använder kontots koppling och kan inte ansluta egna.
Leara begär inte
bookkeeping, companyinformation eller settings och har därmed ingen åtkomst till verifikationer, huvudbok eller bolagsinställningar.
Tokenhantering
- Access-token och refresh-token lagras per kundkonto i Learas databas.
- En separat tokentjänst förnyar access-token var 5:e minut i god tid före utgång. Huvudtjänsten har en reservväg om förnyelsen skulle vara sen.
- Fortnox roterar refresh-token vid varje användning. Skrivningar sker villkorat (optimistisk låsning) så att två samtidiga förnyelser inte kan förstöra kopplingen.
- Kunden kan när som helst återkalla åtkomsten i Fortnox. Då upphör synken tills kopplingen görs om.
Dataflöden
Varje dataobjekt har en bestämd ägare och en bestämd riktning. Ändringar i Leara skrivs till Fortnox via en kö, normalt inom sekunder; ändringar i Fortnox når Leara inom sekunder via händelseströmmen eller senast vid nästa avstämning.Använder kunden inte Fortnox lagermodul kan Leara i stället vara ägare av lagersaldot. Valet görs per konto.
Realtidssynk och avstämning
Fortnox-data når Leara i tre lager, så att ett tappat meddelande aldrig blir en bestående skillnad.1
Realtid
Leara håller en WebSocket-anslutning mot Fortnox händelsetjänst (
wss://ws.fortnox.se/topics-v1) och prenumererar på ämnena artiklar, ordrar, fakturor och kunder. En händelse innehåller bara vilket objekt som ändrats; Leara hämtar sedan objektet via REST-API:t och uppdaterar sin kopia. Position i strömmen sparas per konto och ämne, så att Leara vid återanslutning fortsätter där det slutade (Fortnox sparar händelser i cirka 14 dagar).2
Avstämning var 15:e minut
Ett schemalagt jobb frågar Fortnox efter allt som ändrats sedan förra körningen, med 10 minuters överlapp, för ordrar, fakturor och artiklar. Allt som hittas hämtas och skrivs om. Det gör inget om ett objekt redan är aktuellt, eftersom uppdateringen är idempotent. Startpunkten sparas i databasen och överlever omstarter.
3
Fulla svep
Kunder läses in i sin helhet var 24:e timme, lagersaldon varje natt och inköpsordrar var 30:e minut. En fullständig synk av artiklar, ordrar, fakturor och offerter körs vid första anslutningen och kan startas manuellt.
Skrivvägen till Fortnox
Leara håller sig under Fortnox anropsgräns med marginal och gör om misslyckade skrivningar automatiskt. Fortnox tillåter 25 anrop per 5 sekunder per bolag; Learas gemensamma anropsbudget är 3,5 anrop per sekund med en topp på 8; flöden utanför budgeten begränsar sig själva och hanterar 429-svar.- Varaktig skrivkö för artiklar och priser. Varje ändring läggs i en kö i databasen innan den skickas, så en omstart tappar ingenting. Flera ändringar på samma artikel slås ihop till en skrivning med artikelns aktuella värden. Ändringar från användare går före massimporter.
- Budget delad i två. Halva budgeten är reserverad för löpande synk och halva för tunga exporter (t.ex. inventering), så att en stor import inte stoppar vardagsflödet.
- Omförsök. Vid svar 429 (för många anrop) väntar Leara och försöker igen utan att det räknas som ett fel. Vid tillfälliga fel görs upp till 5 försök med växande väntetid (upp till 10 minuter). Därefter markeras posten som misslyckad och visas för användaren med möjlighet att försöka igen.
- Idempotens. Ordrar från e-handel bär en unik referens i Fortnox så att en order aldrig skapas två gånger vid omförsök. Lagerflyttar med okänt utfall stäms av i efterhand i stället för att skickas på nytt.
- Spärr för osynkade artiklar. En order, offert eller faktura kan inte skickas till Fortnox med en artikel som ännu inte finns där.
- Synlig status. Varje artikel visar om den är synkad, väntar eller misslyckades. Misslyckade ordrar och importrader visas med förklaring på svenska.
Beroenden
Integrationen beror på Fortnox publika API:er, AWS och MongoDB Atlas. Inga andra tredjepartstjänster ligger i dataflödet mellan Leara och Fortnox.
Backenden är skriven i Java 17 med Quarkus. Fortnox anropas med JDK:ns HTTP-klient utan Fortnox-SDK. Om Fortnox är otillgängligt fortsätter Leara att fungera; artikel- och prisändringar ligger kvar i kön, övriga skrivningar visas som misslyckade och kan göras om, och synken tar igen det som missats när Fortnox svarar igen.
Säkerhet, multi-tenant och dataskydd
Varje kunds data och Fortnox-koppling hålls isolerad per Leara-konto, och all trafik går krypterad.- Isolering. Alla speglade Fortnox-objekt lagras med kontots id som del av nyckeln, och token, synkstatus och köer hålls per konto.
- En koppling per konto. Token för ett Fortnox-bolag används bara för det kontots anrop. Realtidshändelser kommer märkta med Fortnox bolagsidentitet och sorteras till rätt konto.
- Minsta behörighet. Leara begär bara de scopes som integrationen använder (se ovan) och har ingen åtkomst till bokföringens verifikationer eller bolagsinställningar.
- Transport. Alla anrop till Fortnox går över HTTPS respektive WSS. Learas API nås via HTTPS på
api.leara.se. - Datalokalisering. Backend och tokentjänst körs i AWS eu-north-1 (Stockholm).
- Personuppgifter. Integrationen hanterar kunders namn, adresser, e-post och telefonnummer från kundkort, ordrar och fakturor. Uppgifterna används bara för att hålla Leara och Fortnox synkade.
- Återkallelse. Kunden kan när som helst återkalla Learas åtkomst i Fortnox.
Drift och övervakning
Synkens hälsa följs per kundkonto i Learas interna adminverktyg, och missade ändringar tas igen automatiskt av avstämningen.- En hälsokontroll rapporterar om realtidsanslutningen är uppe, när avstämningen senast lyckades och om anropsbudgeten tagit slut.
- Adminverktyget visar tokenstatus per konto (giltig, går snart ut, inaktuell, misslyckas, saknas) och skapar notiser var 15:e minut för konton som behöver åtgärdas.
- Loggar samlas i AWS CloudWatch.
Kända begränsningar
De flesta begränsningarna kommer från Fortnox egna API:er. Här är de och hur Leara hanterar dem.- Ändringar i Fortnox syns normalt inom sekunder, men i värsta fall efter upp till cirka 15 minuter, när avstämningen tar igen en missad händelse.
- Stora massimporter tar tid eftersom Fortnox begränsar antalet anrop. En artikel med flera prislistor kostar ett anrop per prislista.
- Refresh-token går ut efter 45 dagar utan användning, och kunden kan återkalla den i Fortnox. Då måste kopplingen göras om av en administratör.
- Ett Fortnox-bolag kan bara vara kopplat till en Leara-miljö åt gången, eftersom Fortnox roterar token vid varje förnyelse. En testmiljö behöver ett eget Fortnox-bolag, till exempel ett testbolag.
- Fortnox saknar realtidshändelser för offerter och inköpsordrar. Inköpsordrar stäms av var 30:e minut och offerter läses vid manuell synk.
- Fortnox saldo-API saknar lagerplatsnivå (hyllplats). Leara visar saldo per lagerställe från Fortnox.
- Fortnox ändringsfrågor listar inte raderade poster. Raderingar fångas via realtidshändelser.