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? link

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 link

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.

Tre sideveier finnes. 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). Og kunden kan be om utbedringer i stedet for å godkjenne (COMPLETED tilbake til IN_PROGRESS).

En ordre som ikke er avsluttet, kan alltid kanselleres.

Lenkene viser veien link

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 link

Alle overganger er POST mot /services/v1/orders/{id}/transitions/…:

De enkle overgangene tar en valgfri kropp med notat:

  curl -X POST /services/v1/orders/42/transitions/accept \
  -H "Authorization: Bearer DITT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Godkjent av innkjøp."}'
  

En tom kropp {} er også gyldig.

Tilbudet link

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 link

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 link

GET /services/v1/orders/{id}/history viser tilstandshistorikken: hvem som gjorde hvilken overgang, og når. change-history viser feltendringene.

Videre link

• Autentisering. Token og headere.
• Tjenestesøk. Finn tjenesten linjen skal peke på.