Tilbud og ordre
Ordre-API-et fører en tjenesteordre fra første forespørsel til godkjent leveranse. API-et er bygget etter HATEOAS-prinsippet: hvert svar forteller deg hva du kan gjøre videre. Du trenger ikke hardkode flyten i klienten din.
Hva er HATEOAS?
HATEOAS står for Hypermedia as the Engine of Application State. Det er en del av REST-arkitekturen, beskrevet av Roy Fielding. Les mer på Wikipedia.
Ideen er enkel. Klienten kjenner bare inngangspunktet. Alt videre navigerer den via lenker i svarene, slik du gjør i en nettleser. Serveren eier tilstandsmaskinen. Klienten leser den.
For tilbud-ordre-flyten gir det tre konkrete fordeler:
- Ingen duplisert forretningslogikk. Klienten slipper å vite når en ordre
kan aksepteres. Finnes
accept-lenken, kan den det. - Rettigheter er innebygd. Lenkene filtreres på rolle og tilgang. Kunden ser aldri leverandørens handlinger, og omvendt.
- Flyten kan utvikles trygt. Serveren kan legge til nye tilstander og overganger. Gamle klienter viser bare lenkene de kjenner, og fortsetter å virke.
Lenkene ligger i feltet _links og følger
HAL-konvensjonen:
nøkkelen er relasjonen (accept, cancel), verdien er lenken.
Tilstandene
En ordre er alltid i én tilstand:
DRAFT → REQUESTED → QUOTED → ACCEPTED → PLANNED → IN_PROGRESS → COMPLETED → APPROVED- DRAFT: kunden setter opp ordren.
- REQUESTED: kunden har bedt om tilbud.
- QUOTED: leverandøren har sendt tilbud med pris og datoer.
- ACCEPTED: kunden har akseptert tilbudet.
- PLANNED: leverandøren har planlagt arbeidet.
- IN_PROGRESS: arbeidet pågår.
- COMPLETED: leverandøren har meldt arbeidet ferdig.
- APPROVED: kunden har godkjent leveransen. Ordren er lukket.
Noen sideveier finnes i tillegg:
- Leverandøren kan trekke et tilbud tilbake for å revidere det (
QUOTEDtilREQUESTED). - Leverandøren kan sende et tilbud uten forespørsel først (
DRAFTrett tilQUOTED). - Kunden kan sende et tilbud tilbake med ønsket endring (
QUOTEDtilbake tilDRAFT). Tilbudet beholdes som leverandørens private utkast. - Kunden kan be om utbedringer i stedet for å godkjenne (
COMPLETEDtilbake tilIN_PROGRESS). - Ved et internt flytt kan leverandøren planlegge direkte fra
DRAFTtilPLANNED. - Leverandøren kan registrere en aksept som kunden ga utenfor systemet
(
QUOTEDtilACCEPTED), og en utbedringsforespørsel som kunden ga utenfor systemet (COMPLETEDtilbake tilIN_PROGRESS).
En ordre kan kanselleres så lenge den er åpen, men ikke når den er
COMPLETED. Da svarer API-et 409, og veien videre er å godkjenne eller be om
utbedringer. Om du kan kansellere, avhenger av tilstanden og hvilken part du
er. Lenken cancel finnes bare når du kan.
Lenkene viser veien
Hvert svar har et _links-objekt. Det inneholder bare handlingene som er
lovlige akkurat nå, for akkurat deg. Slik ser en ordre i tilstand QUOTED ut
for kunden:
{
"id": 42,
"name": "Omtrekk av 12 kontorstoler",
"state": "QUOTED",
"quoteDetails": {
"quotedPrice": 48000.00,
"quotedCurrency": "NOK",
"estimatedStartDate": "2026-10-01",
"estimatedCompletionDate": "2026-10-20",
"quoteValidUntil": "2026-09-30"
},
"_links": {
"self": { "href": "/services/v1/orders/42" },
"accept": {
"href": "/services/v1/orders/42/transitions/accept",
"title": "Accept quote and approve service order",
"method": "POST",
"targetState": "ACCEPTED"
},
"cancel": {
"href": "/services/v1/orders/42/transitions/cancel",
"method": "POST",
"targetState": "CANCELLED"
},
"change-history": { "href": "/services/v1/orders/42/change-history" }
}
}Tre regler gjør lenkene trygge å bygge på:
- En lenke som finnes, kan alltid følges. API-et filtrerer på tilstand, rolle og rettigheter før den legger lenken i svaret.
- En lenke med
methodogtargetStateer en tilstandsovergang. Vis den som en knapp. Lenker uten, somchange-history, er underressurser. - En lenke kan være midlertidig sperret. Da har den
disabled: trueog en stabil kode idisabledReason, for eksempelQUOTE_PRICE_REQUIRED.
Klienten din trenger altså aldri regne ut hva som er lov. Les lenkene, vis dem, følg dem.
Overgangene
Alle overganger er POST mot /services/v1/orders/{id}/transitions/…. Følg
href i _links, ikke bygg URL-en fra lenkenavnet. De to er ikke alltid like:
request-quote ligger på /transitions/request.
| Lenke | Fra → til | Sti etter /transitions/ |
|---|---|---|
request-quote | DRAFT → REQUESTED | request |
quote | REQUESTED → QUOTED | quote |
send-offer | DRAFT → QUOTED | send-offer |
withdraw-offer | QUOTED → REQUESTED | withdraw-offer |
request-changes | QUOTED → DRAFT | request-changes |
accept | QUOTED → ACCEPTED | accept |
accept-on-behalf | QUOTED → ACCEPTED | accept-on-behalf |
plan | ACCEPTED → PLANNED (internt flytt: DRAFT → PLANNED) | plan |
start | PLANNED → IN_PROGRESS | start |
complete | IN_PROGRESS → COMPLETED | complete |
approve | COMPLETED → APPROVED | approve |
request-revisions | COMPLETED → IN_PROGRESS | request-revisions |
reopen-on-behalf | COMPLETED → IN_PROGRESS | reopen-on-behalf |
cancel | Åpen, ikke COMPLETED → CANCELLED | cancel |
Kallene krever Authorization: Bearer … og X-auth-owner med organisasjons-ID-en
din. API-et finner ut om du er kunde eller leverandør på ordren fra den. Se
Autentisering.
request, withdraw-offer, accept, start, complete og approve tar en
valgfri kropp med notat:
curl -X POST /services/v1/orders/42/transitions/accept \
-H "Authorization: Bearer DITT_TOKEN" \
-H "X-auth-owner: DIN_ORGANISASJONS_ID" \
-H "Content-Type: application/json" \
-d '{"notes": "Godkjent av innkjøp."}'En tom kropp {} er gyldig for disse. Disse overgangene krever felt i kroppen:
cancelogrequest-revisionskrever feltetreason. Mangler det, svarer API-et400.noteskan komme i tillegg.request-changeskrever feltetnotes: si hva som skal endres.accept-on-behalfkreverchannel(PHONE,EMAILellerOTHER) ogreference.reopen-on-behalfkrever i tilleggreason.
curl -X POST /services/v1/orders/42/transitions/cancel \
-H "Authorization: Bearer DITT_TOKEN" \
-H "X-auth-owner: DIN_ORGANISASJONS_ID" \
-H "Content-Type: application/json" \
-d '{"reason": "Behovet er falt bort."}'quote, send-offer og plan har egne kropper. Tilbudskroppen står under.
Tilbudet
Leverandøren sender tilbud med quote. Kroppen bærer pris og datoer:
{
"quotedPrice": 48000.00,
"quotedCurrency": "NOK",
"estimatedStartDate": "2026-10-01",
"estimatedCompletionDate": "2026-10-20",
"quoteValidUntil": "2026-09-30",
"quoteNotes": "Prisen gjelder tekstil i standardsortimentet."
}Leverandøren kan også lagre et utkast underveis med
PUT /services/v1/orders/{id}/quote-details. Utkastet er privat til tilbudet
sendes. Kunden ser aldri et halvferdig tilbud.
Ordrelinjene peker på katalogen
En ordrelinje refererer tjenesten og kategorien fra
tjenestesøket: solutionId sier hvilken tjeneste,
categoryId sier hvilken kategori. Slik henger taksonomien, tjenestekatalogen
og ordren sammen i én kjede.
Historikk
GET /services/v1/orders/{id}/history viser tilstandshistorikken: hvem som
gjorde hvilken overgang, og når. change-history viser feltendringene.
Videre
- Autentisering. Token og headere.
- Tjenestesøk. Finn tjenesten linjen skal peke på.