Start med en stabil enhed
Vælg, hvad der er én økonomisk operation: en afsluttet ordre, en konkret fakturakladde eller en balanceret postering. En batchfil er en transportbeholder og behøver ikke være én atomisk regnskabshandling.
Hver operation skal have egen kildeidentitet, idempotensnøgle og status. Hvis en fil med 200 poster stopper ved nummer 87, skal systemet kunne afklare de første 86 uden at oprette dem igen under nye nøgler.
Klientens kø
Brug et begrænset antal workers og gem køens tilstand i et vedvarende system. En browserfane eller en modelkonversation er ikke et tilstrækkeligt kølager. En procesgenstart skal ikke få alle poster til at fremstå som nye.
Respektér rate limits og stop ved adgangsfejl. Ved 429 eller et midlertidigt netværksproblem anvendes kontrolleret backoff. Ved ugyldig reference eller lukket periode skal den konkrete post til afklaring; en retry-løkke ændrer ikke årsagen.
Delvis succes
En serie af separate requests er ikke atomisk på tværs af hele serien. Nogle operationer kan være gennemført, mens andre er afvist eller stadig har ukendt udfald. Vis disse tilstande hver for sig og bevar kvitteringerne.
Partner-API'et lover ikke "alt eller intet" for en hel batch. Opret ikke en kompensationspost automatisk, blot fordi en senere operation fejlede. En regnskabsmæssig korrektion skal have et afklaret formål og den nødvendige autorisation.
Størrelse og linjer
En journalrequest må have højst 500 linjer, en fakturakladde højst 500 linjer, og hele body må være højst 256 KiB. Det er ikke en opfordring til at sammenlægge alle forretningsoperationer til én stor request; det ville gøre idempotens, fejlfinding og faglig afstemning vanskeligere.
Store vedhæftede filer understøttes ikke af domæneoperationerne. Brug ikke base64 i et ukendt felt for at omgå, at Partner-API'et ikke har et dokumentupload-endpoint.
Webhooks og kvitteringer
Den minimale webhook kan fortælle om en gennemført gatewayoperation. Den er ikke en fuld batchrapport og leverer ikke alle regnskabsdata. Din egen kø skal gemme forbindelsen mellem kildeopgaven og den modtagne operationsidentitet.
Webhookleveringer kan gentages. Modtageren skal derfor deduplikere eventidentiteten og ikke starte den samme downstream-handling igen. Se webhooks.
Krav til et server-Batch API
Et asynkront API skal blandt andet definere job-ID, uploadformat, validering, delvise resultater, annullering, retention, statusopslag og adgang efter revocation. Det må ikke beskrives som eksisterende, blot fordi klienten kan sende flere normale requests efter hinanden.