Forberedelse er ikke bogføring
POST /journal/prepare kontrollerer partnerinput og de relevante referencer uden at oprette en hovedbogspostering. Et godkendt resultat er et øjebliksbillede af, at input kunne valideres i denne kontekst. Det reserverer ikke en regnskabsperiode, et bilagsnummer eller en fremtidig rettighed.
POST /journal er den endelige operation. Den kræver et andet scope og et særskilt mandat i kundens grant. Hvis kunden kun har tilladt forberedelse, skal appen stoppe dér. Der er ingen parameter, der kan ændre et prepare-kald til en bogføring uden den nødvendige serveradgang.
Vælg kontoreferencer med kunden
Kunden vælger, hvilke konti integrationen må bruge. Appen henter dette begrænsede konfigurationssæt, ikke hele virksomhedens hovedbog. Gem en mapping mellem dit systems kontobegreber og de konkrete Hours-referencer for den autoriserede organisation.
En sådan mapping skal have miljø og grant med i sin kontekst. Genbrug ikke referencer fra en tidligere sandboxgeneration eller en anden kunde. Når en grant erstattes, skal appen sikre sig, at mappingen stadig er gyldig, før den sender nye posteringer.
Byg en balanceret postering
Angiv en bogføringsdato, DKK og mindst to linjer. Alle beløb er hele øre. En omkostning på 125,00 kr. kan eksempelvis repræsenteres med 12.500 øre i debet og 12.500 øre i kredit på en korrekt valgt modkonto. Dette eksempel forklarer balancen; det er ikke rådgivning om, hvilke konti en konkret virksomhed skal bruge.
Moms skal håndteres efter det faglige input og kundens opsætning. En balanceret postering kan stadig være forkert konteret. Det er derfor ikke nok at kontrollere, at summen af debet er lig summen af kredit. Datoer, momsgrundlag, dokumentation og kontoformål skal også være rigtige.
Partneren må ikke selv sætte intern kilde, aktør eller organisation. Gatewayen registrerer appen som aktør og kalder Hours' regnskabskerne med serverafledt kontekst. Rå bankkoblinger og kundevalgte provenance-stempler accepteres ikke som input.
Genbrug af Hours' regnskabskerne
Gatewayen bruger Hours' eksisterende bogføringsfunktion i sin transaktion, samme autoritative funktion som resten af Hours bogfører gennem. Den opretter ikke hovedbogslinjer gennem et parallelt insert-forløb.
Det er vigtigt, fordi nummerallokering, header, linjer, kontrolspor og perioderegler skal hænge sammen. En fejl halvvejs efterlader ikke en bogført header uden linjer eller en kvittering, som siger "gennemført", selv om regnskabet blev rullet tilbage.
Periodelåse og tidsforskelle
En periode kan være åben under prepare og blive lukket, inden appen sender det endelige kald. Den endelige operation genkontrollerer derfor den aktuelle tilstand. Cache ikke et prepare-resultat som en permanent godkendelse.
Ved en låst periode må appen ikke automatisk flytte datoen til i dag. Det ændrer regnskabets betydning. Vis en forklaring og lad den autoriserede arbejdsgang afgøre, hvordan posteringen skal håndteres. Samme princip gælder en tilbagekaldt grant eller en konto, der ikke længere er gyldig.
Timeout og genforsøg
Send en stabil Idempotency-Key, som identificerer den samme forretningsoperation. Ved et timeout ved du ikke nødvendigvis, om serveren nåede at committe. Gentag derfor med samme nøgle og samme normaliserede input. Skift ikke nøgle, bare fordi klienten ikke modtog svaret.
Gem kvitterings-ID'et, når du modtager det. Et senere opslag skal ske med aktuel adgang og kan kun vise appens egne resultater. Brug ikke en liste over hele kundens hovedbog til at gætte, om et bestemt integrationskald lykkedes.
Korrektion og dokumentation
Partner-API'et har ikke et eksternt endpoint til fri ændring eller sletning af bogførte posteringer. Endelige regnskabshandlinger skal korrigeres gennem den relevante kontrollerede proces, ikke ved at redigere en historisk linje i databasen.
Partner-API'et tilbyder heller ikke vilkårlig bilagsupload eller dokumentkobling. Det er en vigtig funktionsafgrænsning: en integration, hvis bogføring kræver et bestemt dokumentkontrolspor, skal sikre dette på anden vis. Et tekstfelt med et filnavn er ikke en erstatning for en kontrolleret dokumentrelation.
Acceptprøver for en bogføringsintegration
Test den korrekte bogføring og prøv derefter bevidst ubalance, decimalører, ukendt konto, anden organisations konto, lukket regnskabsår, afregnet momsperiode og gentagne samtidige requests. Test også tabt svar efter commit og tilbagekaldelse mellem klargøring og bogføring.
Resultatet skal måles i regnskabskernen: én forventet postering, de korrekte linjer, en passende revisionshændelse og en kvittering, der stemmer med det faktiske udfald. En grøn frontendtest eller en mock, der returnerer 201, dækker ikke disse krav.