Hvad Hours' kontraktmodel indeholder
Hours' kontraktmodel rummer blandt andet leverandør, kategori, pris, status, udløbsdato, organisationsrelation og et JSON-datafelt. At en oplysning findes i modellen, fortæller ikke, hvilke felter en partner må læse eller skrive.
Et JSON-felt kan rumme et varierende sæt oplysninger fra analyse eller andre kilder. En generisk udlevering af dette felt ville gøre det vanskeligt at love et stabilt, minimeret og bankfrit output. Derfor er en oplysnings eksistens i modellen ikke ensbetydende med, at den kan hentes eksternt.
Hvilken operation er der behov for?
Et kontraktflow kan handle om at registrere en ny aftale, opdatere et kontaktpunkt, hente en udløbsdato, starte en forhandling eller afslutte en aftale. Det er forskellige operationer med forskellige risici. Et enkelt contracts:write med vilkårligt JSON er for bredt til at beskrive dem forsvarligt.
Beskriv først den konkrete trigger, nødvendige input, autoriserende rolle og forventede sideeffekt. Et økonomisk udkast kan have et andet kontrolkrav end en opsigelse eller en underskrift. Partnerprofilen giver ingen automatisk ret til disse sidste handlinger.
Kildedokument og afledte felter
Kontraktens original, et udtrukket vilkår og et AI-genereret forslag er forskellige datatyper. En integrationsmodtager skal kunne vide, om en dato kommer fra dokumentet, fra en manuel korrektion eller fra en antagelse i analysen.
En fremtidig kontraktkontrakt skal give kildehenvisning, version, valideringsstatus og usikkerhed en eksplicit betydning. En app må ikke ændre en analyseversion og derefter fremstille gamle udtræk som gældende aftalevilkår.
Ændringer og samtidighed
Kontraktdata kan blive ændret både af kunden og en integration. Et fremtidigt update-flow skal derfor håndtere revisionskonflikter og ikke blot lade den sidste request overskrive den første. Det skal også være klart, om en opdatering påvirker et aktivt godkendelses- eller forhandlingsflow.
Disse krav opfyldes ikke ved at pege partneren direkte på interne data. Partner-API'et har derfor ingen kontraktrute, som udgiverne kan bruge til at omgå den nødvendige produkt- og adgangsafklaring.
Nuværende vej videre
Brug kontraktvejledningen til at beskrive processen, og brug App Console til at dokumentere integrationsbehovet. Når et kontrakt-API udvides, publiceres feltlisten, handlingerne, fejlkoderne og sikkerhedskravene sammen med det.
Et forsøg på en ukendt /contracts-route i partnergatewayen giver en afvisning. Det er den korrekte adfærd og ikke et signal om at finde en skjult intern adresse.