Integration API — request og dataflyt¶

Request-pipelinen¶

flowchart TD
  request["HTTP-request"] --> exception["Exception middleware"]
  exception --> logging["Request/response-logging"]
  logging --> apiKey["API-key middleware"]
  apiKey --> https["HTTPS-redirect"]
  https --> jwt["JWT authentication og authorization"]
  jwt --> oauth["OAuth tenant-middleware for /api/v2"]
  oauth --> controller["Controller og ModelState"]
  controller --> service["Fagtjeneste"]
  service --> database["DatabaseService"]
  database --> response["ApiResponse eller HTTP-feil"]

API-key middlewaren slipper /api/v2 videre uten nøkkel. JWT og OAuth-middlewaren behandler deretter v2. Andre API-kall bruker v1-oppslaget.

Leseflyt¶

sequenceDiagram
  participant Client as Klient
  participant Controller as Controller
  participant Service as Fagtjeneste
  participant DB as Kundedatabase/ERP
  Client->>Controller: GET med filtre
  Controller->>Service: Typet request
  Service->>DB: SQL eller lagret prosedyre
  DB-->>Service: DataSet/DataTable
  Service->>Service: Map legacy-felt til API-modell
  Service-->>Controller: ApiResponse<T>
  Controller-->>Client: 200, 400 eller 404

Lesekall kan ha sideeffekter når kontrakten sier det. Et viktig eksempel er GET /api/v2/WorkOrder/costs: med softMarkOnRead=true markeres returnerte ERP-poster som hentet. Les derfor query-parametrene før et kall brukes i test.

Skriveflyt¶

sequenceDiagram
  participant Client as Klient
  participant Controller as Controller
  participant Service as Fagtjeneste
  participant DB as Kundedatabase
  Client->>Controller: POST/PUT/DELETE med JSON
  Controller->>Controller: ModelState og rutekontroll
  alt Ugyldig input
    Controller-->>Client: 400 + ApiResponse
  else Gyldig input
    Controller->>Service: Lagre eller slette
    Service->>DB: SP eller parameterisert SQL
    DB-->>Service: ID, antall eller resultatsett
    Service-->>Controller: Success + resultat per element
    Controller-->>Client: 200 eller 400
  end

Kontroller alltid hele responsen:

Felt	Betydning
`Success`	Om operasjonen samlet ble vurdert som vellykket
`Message`	Kort resultat eller sikker feilmelding
`Data`	Objekt, liste eller resultat per element
`Timestamp`	Serverens tidspunkt
`ErrorCode`	Referanse for servicedesk når tjenesten genererer en slik kode

Normal controller-serialisering beholder C#-feltnavnene (Success, Message, ...). Uhåndterte feil fra exception-middlewaren serialiseres med camelCase. Klienter bør derfor bruke en case-insensitiv JSON-deserializer.

Batch og delvis resultat¶

Flere skriveoperasjoner behandler lister element for element:

Actor returnerer ActorBatchResult per aktør.
Time returnerer resultat per timelinje, eksportmarkering, sletting eller kvittering.
WorkOrder-linjer returnerer WorkOrderLineSaveResult per linje.

Ikke bruk bare HTTP-status som kvittering. Kontroller hvert resultatelement før checkpoint flyttes eller kildedata markeres som ferdig.

Eksport- og kvitteringsmønstre¶

flowchart LR
  source["Les ventende data"] --> external["Send til eksternt system"]
  external --> ok{"Eksternt resultat"}
  ok -- "Feil" --> retry["Behold som ventende<br/>og logg feil"]
  ok -- "OK" --> confirm["Kall exported/confirm/ok"]
  confirm --> marked["Lagre ekstern ID<br/>eller kvitteringsflagg"]

Flyt	Lesing	Kvittering
Timer	Hent periode eller ventende registreringer	`POST timesheet/exported` lagrer ekstern ID
Slettede timer	`GET timesheet/deleted`	`POST timesheet/deleted/ok` bekrefter behandling
Arbeidsordrekostnader	`GET WorkOrder/costs`	`POST WorkOrder/costs/confirm` oppdaterer ERP-markering

Retry skal baseres på resultat per element. Et nytt batchkall må tåle at noen elementer allerede er lagret eller kvittert.

Databasegrenser¶

Fagtjenestene velger connection string fra request-konteksten.
DatabaseService bruker parameterisert SQL eller lagrede prosedyrer og setter QUOTED_IDENTIFIER ON.
WorkOrder-kostnader kan lese og oppdatere ERP-databasen via connection string i kundekonfigurasjonen.
WorkOrder-linjer kan også opprette eller reversere lagertransaksjoner når kundens innstilling CreateStockTxFromApi er aktiv.

Kildepunkter¶

ePortalIntegrationApi/Program.cs
ePortalIntegrationApi/Services/DatabaseService.cs
ePortalIntegrationApi/Services/TimeService.cs
ePortalIntegrationApi/Services/WorkOrderService.cs
ePortalIntegrationApi/Models/TimeModels.cs
ePortalIntegrationApi/Models/WorkOrderModels.cs