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 (QUOTED til REQUESTED).
  • Leverandøren kan sende et tilbud uten forespørsel først (DRAFT rett til QUOTED).
  • Kunden kan sende et tilbud tilbake med ønsket endring (QUOTED tilbake til DRAFT). Tilbudet beholdes som leverandørens private utkast.
  • Kunden kan be om utbedringer i stedet for å godkjenne (COMPLETED tilbake til IN_PROGRESS).
  • Ved et internt flytt kan leverandøren planlegge direkte fra DRAFT til PLANNED.
  • Leverandøren kan registrere en aksept som kunden ga utenfor systemet (QUOTED til ACCEPTED), og en utbedringsforespørsel som kunden ga utenfor systemet (COMPLETED tilbake til IN_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å:

  1. En lenke som finnes, kan alltid følges. API-et filtrerer på tilstand, rolle og rettigheter før den legger lenken i svaret.
  2. En lenke med method og targetState er en tilstandsovergang. Vis den som en knapp. Lenker uten, som change-history, er underressurser.
  3. En lenke kan være midlertidig sperret. Da har den disabled: true og en stabil kode i disabledReason, for eksempel QUOTE_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.

LenkeFra → tilSti etter /transitions/
request-quoteDRAFT → REQUESTEDrequest
quoteREQUESTED → QUOTEDquote
send-offerDRAFT → QUOTEDsend-offer
withdraw-offerQUOTED → REQUESTEDwithdraw-offer
request-changesQUOTED → DRAFTrequest-changes
acceptQUOTED → ACCEPTEDaccept
accept-on-behalfQUOTED → ACCEPTEDaccept-on-behalf
planACCEPTED → PLANNED (internt flytt: DRAFT → PLANNED)plan
startPLANNED → IN_PROGRESSstart
completeIN_PROGRESS → COMPLETEDcomplete
approveCOMPLETED → APPROVEDapprove
request-revisionsCOMPLETED → IN_PROGRESSrequest-revisions
reopen-on-behalfCOMPLETED → IN_PROGRESSreopen-on-behalf
cancelÅpen, ikke COMPLETED → CANCELLEDcancel

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:

  • cancel og request-revisions krever feltet reason. Mangler det, svarer API-et 400. notes kan komme i tillegg.
  • request-changes krever feltet notes: si hva som skal endres.
  • accept-on-behalf krever channel (PHONE, EMAIL eller OTHER) og reference. reopen-on-behalf krever i tillegg reason.
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