Parametrene
De tre domænelister for journal, produkter og fakturaer accepterer limit og after. limit er et heltal mellem 1 og 100, med 50 som standard. Ukendte parametre, gentagne parametre og ugyldige referencer afvises.
| Liste | after | Øvrige parametre |
|---|---|---|
GET /journal | Posteringsnummeret som cifre i en streng, ikke en UUID | from og to (YYYY-MM-DD) |
GET /products | UUID fra forrige side | Ingen |
GET /invoices | UUID fra forrige side | Ingen |
Svaret indeholder data, has_more og next_after. Der er ingen offset, fri sortering, expand eller organisationsparameter på partnerlisterne, og kun journallisten har datoafgrænsning. Du må ikke overføre en page/perPage- eller limit/offset-kontrakt fra andre dele af Hours til partnerlisten.
Sideforløbet
Begynd uden after, og behandl de returnerede poster. Fortsæt med next_after, når svaret angiver, at der findes mere. Gem ikke en cursor fra én app, organisation eller et miljø som en global synkroniseringsposition.
En cursor er en teknisk position, ikke et tidspunkt. Den må ikke oversættes til "alt efter klokken 14". Listen bruger en fast orden. Der er ikke et løfte om, at nye poster, som kommer til under en længere gennemlæsning, indgår i samme konsistente øjebliksbillede.
Ingen komplet realtime-synkronisering
En fakturakladde, som appen opretter, kan blive håndteret videre i Hours. Listen er en læsning på tidspunktet for kaldet og ikke en løbende kopi af alle ændringer. Brug den ikke til at konkludere, at noget aldrig er blevet ændret mellem to læsninger.
Et egentligt change-feed forudsætter blandt andet stabile sekvensnumre, retention for hændelser, slettemarkører, gendannelse efter et hul og en konsistent autorisationsmodel. Det opnås ikke ved blot at kalde den nuværende liste oftere, og partner-API'et tilbyder det ikke.
Når adgangen ændrer sig
Alle sider kræver aktuel adgang. Et tidligere vellykket første kald låser ikke adgangen til resten af listen. En tilbagekaldt grant, ændret apprevision eller udløbet token kan stoppe forløbet på en senere side.
Behandl det som et adgangsstop, ikke som en tom afslutning på datasættet. En tom liste og et 403-svar betyder forskellige ting. Slet ikke din lokale kopi af alle poster, fordi et rettighedsproblem blev fejlfortolket som "der findes ingen data".
Idempotent modtagelse
Modtageren skal kunne se samme post mere end én gang uden at oprette dubletter i sit eget system. Brug postens id (for journalen posteringsnummeret) som teknisk nøgle og gem kildeapp, miljø og den lokale mapping. En tekstbeskrivelse eller et beløb er ikke en unik identitet.
En retry af selve listekaldet må ikke føre til, at downstream-systemet udfører en finansiel handling igen. Hold læsning og videre handling adskilt. At en post findes på listen, er ikke et nyt mandat til at bogføre den i endnu et system.
Test din læseløkke
Test et tomt datasæt, én post, præcis en fuld side og flere sider. Test ugyldig cursor, cursor fra anden kontekst, tokenudløb på side to og et netværkstab efter klienten har behandlet en side. Kontrollér, at løkken stopper og ikke sidder fast på samme reference. Test også mod sandbox, mens der oprettes nye poster, da en liste under samtidige inserts ikke er et konsistent øjebliksbillede.