Hastighetsgränser och paginering i Fortnox API

Fortnox räknar anrop i ett glidande femsekundersfönster. Det betyder att kvoten inte nollställs vid fasta klockslag. En kort trafikspik kan därför fortsätta utlösa 429 tills tillräckligt många äldre anrop har lämnat fönstret. Fortnox beskriver också gränsen som 300 anrop per minut per client-id och tenant. I praktiken bör klienten planera efter den strängare korta gränsen: högst 25 starter inom varje rullande femsekundersperiod.

Gränsen följer access-token, inte IP-adressen. Varje Fortnox-bolag har en egen token och därmed en egen kvot, medan parallella processer för samma bolag delar på samma utrymme. En webbserver, ett köjobb och en nattlig synk kan alltså tillsammans nå taket även om varje process ser försiktig ut. Samordna därför hastighetsbegränsningen centralt per bolag och token, och lämna gärna marginal för interaktiva anrop.

HTTP 429 är en signal att sakta ned, inte ett skäl att skicka samma begäran direkt igen. Lägg återförsök i en gemensam klient och använd exponentiell backoff med jitter, så att samtidiga workers inte vaknar och skapar en ny trafikspik samtidigt. Sätt också ett tak på väntetiden och antalet försök. När försöken är slut ska jobbet kunna läggas tillbaka i en kö eller markeras för kontrollerad uppföljning.

Produktionsintegrationer behöver både retry och circuit breaking. Vår produktionsklient använder retry med backoff och circuit breaker: tre återförsök, exponentiell väntan från 1 upp till 30 sekunder, en krets som öppnas efter fem sammanhängande fel och en kö med högst 100 väntande anrop. Kretsen hindrar ett redan pressat beroende från att bombarderas, medan kön ger ett tydligt mottryck när inkommande arbete överstiger kapaciteten.

1. Begränsa anrop per access-token innan de skickas, och dela samma limiter mellan alla jobb för företaget.
2. Vid 429: vänta med exponentiell backoff och slumpmässig jitter; återför aldrig i en tät loop.
3. Öppna circuit breaker efter upprepade fel, mät ködjup och larma innan backloggen blir ett kundproblem.

Fortnox listresurser använder frågeparametern page för sidnummer och limit för antal poster. Standardvärdet för limit är 100; det tillåtna intervallet är 1–500. Ett konkret anrop mot fakturor kan hämta den första sidan med 100 obetalda fakturor, sorterade på dokumentnummer. Parametrarna skrivs med gemener och kombineras med &. Börja med en rimlig sidstorlek i stället för att alltid välja 500: stora svar tar längre tid och blir dyrare att behandla om jobbet måste göras om.

GET https://api.fortnox.se/3/invoices?filter=unpaid&page=1&limit=100&sortby=documentnumber&sortorder=ascending

Många klassiska Fortnox-listsvar innehåller MetaInformation med @CurrentPage, @TotalPages och @TotalResources. Läs dessa fält när resursens svar exponerar dem och fortsätt medan CurrentPage är mindre än TotalPages. Gör inga antaganden utifrån att en sida råkar innehålla färre poster än limit om kontraktet erbjuder sidmetadata. Spara först resultatet och därefter checkpointen, så att ett avbrott inte hoppar över en sida.

Den bundlade OpenAPI-specifikationen bekräftar /3/invoices och dess resursparametrar men listar inte alla globala parametrar direkt på operationen. page, limit och sortorder är globala parametrar i Fortnox officiella parameterguide. Specifikationen visar samtidigt att äldre svarstyper kan skilja sig: kontrollera därför den faktiska responsmodellen för just resursen och bygg inte en generell paginerare som kräver MetaInformation överallt.

För fakturor är ?filter=unpaid ett dokumenterat sätt att bara hämta obetalda poster. Den bundlade OpenAPI-specifikationen anger även cancelled, fullypaid, unpaidoverdue och unbooked som tillåtna filtervärden. Ett resursfilter är bättre än att hämta hela registret och kasta bort poster lokalt: svaret blir mindre, färre sidor behöver läsas och du förbrukar mindre av kvoten.

Sortering styrs med sortby och sortorder. För /3/invoices tillåter OpenAPI bland annat documentnumber, customername, customernumber, invoicedate, ocr och total som sortby. Fortnox officiella exempel använder sortorder=ascending. Välj en stabil sortering när du paginerar, men kom ihåg att poster kan ändras medan en lång hämtning pågår. Om fullständig konsistens krävs bör synken kunna överlappa tidsintervall och avduplicera på resursens identitet.

Parametern lastmodified hämtar poster som ändrats sedan en given tidsstämpel och är grunden för inkrementell synk. Den kan kombineras med en resursspecifik sökparameter enligt Fortnox guide, men bara en resursspecifik sökning åt gången stöds. Spara senaste lyckade vattenstämpel per bolag och resurstyp. Använd en liten överlappning vid nästa körning och uppdatera poster idempotent, så fångar du sena ändringar utan att skapa dubletter.

En robust inkrementell synk börjar med en sparad lastmodified-checkpoint, läser alla sidor i bestämd ordning och flyttar checkpointen först när hela intervallet är klart. Vid fel återupptar du från föregående säkra läge. Lägg till en tidsöverlappning och gör upsert på Fortnox-id eller dokumentnummer. Då blir jobbet tolerant mot både nätverksfel och poster som ändras nära gränsen mellan två körningar.

Batcha läsningar genom att hämta listsidor i stället för en detaljbegäran per post. Håll ändå samtidigheten låg per token; tio parallella workers ger inte högre tillåten kapacitet. Låt en schemaläggare väga bakgrundssynk mot användarstyrda anrop och sprid nattjobb över tid. Mät anrop, 429-svar, återförsök, svarstid och ködjup per bolag för att se kapacitetsproblem innan användarna gör det.

När data läses ofta men ändras sällan är cache den billigaste optimeringen. Cacha oföränderliga uppslag och kortlivade listresultat, invalidiera efter egna ändringar och använd lastmodified för att fräscha upp bara det som ändrats. Cache ska inte dölja fel eller ersätta korrekt paginering, men den minskar duplicerade anrop och lämnar kvot åt arbetsflöden som verkligen behöver färska data.