Identiteter må ikke blandes sammen
workspace_id identificerer udgiverens udviklerarbejdsrum. app_id identificerer integrationen. En apprevision er den gennemgåede udgave af appen. organization_id identificerer derimod en bestemt kundes juridiske enhed. En grant forbinder netop en apprevision med netop denne organisation.
Klientpayloads vælger ikke selv customer_id, organization_id eller created_by_actor. Serveren udleder dem fra den aktuelle autorisation. Et UUID er en reference, ikke en tilladelse: at kende et konto-ID fra en anden organisation giver ikke adgang til kontoen.
Hours' interne customer_id er flere steder knyttet til en brugerbaseret historisk model. At en intern ressource også har organization_id beviser ikke, at enhver læsesti håndhæver organisationsgrænsen. Derfor genbruges den eksisterende kundesession ikke som et generisk partnertoken.
Beløb: hele øre, ikke kroner
I partnerprofilen angives beløb som JSON-heltal i minor units. For DKK betyder 12500 125,00 kr., ikke 12.500 kr. Send ikke 125.00, "12500" eller en lokaliseret tekst som "125,00 kr.". Syntaktisk gyldig JSON er ikke nødvendigvis en gyldig økonomisk payload.
JavaScript kan ikke repræsentere alle vilkårligt store heltal præcist. Partner-API'et afviser beløb over 99 999 999 999 999 øre pr. linje. Debit og kredit summeres uden flydende afrunding. Foretag afrunding i dit kildesystem efter en fast regel, før du sender posteringen; brug ikke tolerance til at skjule en ubalance i hovedbogen.
En journalpostering har mindst to og højst 500 linjer. Hver linje har enten positiv debet eller positiv kredit. Den modsatte side er nul. Et negativt beløb eller en linje med begge sider udfyldt afvises. En korrektion skal udformes som en ny, autoriseret regnskabshandling, ikke som en negativ vilkårlig linje.
Datoer og valuta
Datoer bruger YYYY-MM-DD. posting_date er bogføringsdatoen, mens transaction_date og document_date kan beskrive hændelsen og dokumentets dato. En dato er ikke et tidsstempel og har ikke en tidszone. Undgå at konvertere den gennem en lokal midnat og derefter sende den som UTC-dato; det kan flytte datoen én dag.
Datoer kalenderkontrolleres. En streng, som ligner en dato, men angiver 31. februar, bliver ikke accepteret. Logs og udløbstider anvender tidsstempler, fordi de beskriver et tidspunkt, ikke en regnskabsdato.
Partnerprofilen er DKK-only. At en intern ressource har en valutakolonne, betyder ikke, at partner-API'et har en fuld kontrakt for valutakurser, kursdatoer, afrundinger og kursdifferencer. Send ikke EUR og antag, at en intern standardværdi løser resten.
Konto, moms og dimension
En account_id skal komme fra det afgrænsede konfigurationsvalg. Et kontonummer er et menneskeligt regnskabsbegreb, mens UUID'et identificerer den konkrete række i det konkrete miljø. Et produktionskonto-ID må ikke bruges i sandbox eller omvendt.
Valgfrie moms- og dimensionsreferencer er stadig referencer med ejerskab. De kontrolleres mod organisationen og den aktuelle aktør, før en operation må gennemføres. Dimensioner må ikke bruges som en vej til at knytte en postering til et andet arbejdsrums projekt. Der er højst 20 forskellige dimensionsreferencer på en partnerjournallinje.
Et momskode-ID er ikke selve momsberegningen. Integrationens beløb og kontering skal stadig være fagligt korrekte. Der tildeles ikke et standardscope til at ændre kundens momskoder eller kontoplan.
Produkter
Et produkt har en stabil kode, et navn, arten goods eller services, en understøttet enhed og en pris i hele øre. Produktkoden er højst 70 tegn, og præfikset LEGACY- er reserveret. Partner-API'et accepterer kun et afgrænset inputudsnit; det videresender ikke hele den interne produktmodel.
De understøttede enheder er stk, stk., time, timer, kg, liter og km. Det er en bevidst afgrænsning af gatewayen, ikke en påstand om, at disse er alle enheder, Hours internt kan oversætte. Ukendte enheder giver en fejl, ikke en tavs standardværdi, der ændrer fakturaens betydning.
Fakturakladder
En fakturakladde har fakturadato, eventuel forfaldsdato, valgfri leveringsdato (delivery_date), kundenavn, valgfri kundeadresse (customer_address) og linjer. Mængde kan have op til tre decimaler og er som standard 1, mens enhedsprisen angives som hele øre. En rabat angives i procent med højst tre decimaler og skal være mindst nul og mindre end 100.
En oprettet kladde har status draft, sent: false og posted: false, og total_incl_vat_minor er null, indtil fakturaen er bogført. Den har ikke automatisk et endeligt fakturanummer, en betalingsstatus eller et Stripe-link. Beskyttede felter som status, posted_entry_id, invoice_no, bankoplysninger og providerreferencer må ikke styres af partnerpayloaden. De udgør andre arbejdsprocesser og andre adgangsgrænser.
Kvittering og læsning
Operationskvitteringen beskriver resultatet af appens egen handling: operationens identitet, status og et minimalt resultat. Den skal kunne bruges til at afklare et ukendt udfald. Den er ikke en udvidet GET af hele den interne ressource.
Læseoperationerne returnerer en kontrolleret model uden bank- og betalingsfelter. GET /journal viser kun linjer på de konti, kunden har tildelt, og journalcursoren after er posteringsnummeret som en streng af cifre, ikke et UUID. Hold dit systems indsendelsesstatus adskilt fra påstanden om, at det kender kundens aktuelle samlede regnskabsstatus. Se pagination og skriveadgang.