Konti Connect — eksterne kostnader¶

KontiExternalCostImportAdapter henter eksterne kostnader (typisk underleverandørfakturaer, materialinnkjøp og bilag) fra Konti Connect API (selv-driftet sentralt API på https://connect.elportal.no) og legger dem på arbeidsordrer i ePortal. Adapteren bruker felles OAuth2-credentials konfigurert sentralt (ikke per integrasjon).

Type: REST-import (pull), OAuth2 Client Credentials Modul i ePortal: Konfigureres i Konti Connect, oppdaterer Arbeidsordre-modulen (wv_WorkOrder_ExternalCost) Karakteristisk: Bruker delte Konti Connect-credentials (én konfigurasjon for hele tenant — ikke per integrasjon); auto-kategorisering basert på kontonummer; delta-synk med watermark

Hva integrasjonen synker¶

Retning	Entitet	Frekvens
Konti Connect API → ePortal	Eksterne kostnader → `wv_WorkOrder_ExternalCost`	Konfigurerbart (anbefales hyppig, f.eks. hver time, hvis delta-synk aktiv)

Implementasjon: KontiExternalCostImportAdapter.cs

Merk om navnet: TypeCode er KontiConnect. Adapteren importerer eksterne kostnader og er en av flere integrasjoner som bruker Konti Connect-API-et. Selve "Konti Connect" som modul er det interne admin-grensesnittet i ePortal for all integrasjons-konfigurasjon — se Konti Connect-modulen.

Tilgang¶

Hvem	Hva trengs
Hos kunden	Visma Business (klassisk eller NXT) der kostnadene oppstår. Datakilde mater Konti Connect API
Hos Konti	Administrator-tilgang til Konti Connect; konfigurerte sentrale Konti Connect-credentials

Forutsetninger¶

Konti Connect API er tilgjengelig og kunden har gyldig OAuth-tilgang via felles innstillinger
ePortal-arbeidsordre eksisterer med korrekt WoNo som matcher det Konti Connect leverer
Sentrale innstillinger for Konti Connect er fylt ut: Innstillinger → Konti Connect → "Globale innstillinger" (KontiConnect.ApiBaseUrl, KontiConnect.ClientId, KontiConnect.ClientSecret, KontiConnect.TokenUrl, KontiConnect.TenantId, KontiConnect.ApiClientId). Det finnes ingen KontiConnect.Scope-innstilling — scope genereres dynamisk som api://{ApiClientId}/.default

Konfigurasjon — feltforklaring¶

KontiExternalCostImportAdapter skiller seg fra de andre adapterne ved at OAuth2-credentials konfigureres sentralt, ikke per integrasjon. Per-integrasjon ConfigurationJson styrer kun synk-oppførsel.

Globale innstillinger (Konti Connect-modul → "Innstillinger")¶

Innstilling	Type	Påkrevd	Hva det betyr
`KontiConnect.ApiBaseUrl`	URL	Ja	Base for Konti Connect API, typisk `https://connect.elportal.no`
`KontiConnect.ClientId`	String	Ja	OAuth2 client_id
`KontiConnect.ClientSecret`	String (hemmelighet)	Ja	OAuth2 client_secret. Krypteres
`KontiConnect.TokenUrl`	URL	Ja	OAuth2-token-endepunktet
`KontiConnect.TenantId`	String	Ja	Azure AD tenant-id for token-endepunktet
`KontiConnect.ApiClientId`	String	Ja	App-id for API-et; scope genereres som `api://{ApiClientId}/.default`

Disse styres av IKontiConnectAuthService og caches på tvers av adapter-kjøringer.

Per-integrasjons `ConfigurationJson`¶

Felt	Type	Påkrevd	Hva det betyr
`TimeoutSeconds`	Integer	Nei (default `60`)	HTTP-timeout per API-kall
`DefaultMarkupPercent`	Decimal	Nei (default `0`)	Standard påslagsprosent (0–100) ved overføring til arbeidsordre. Kan endres manuelt per linje senere
`SyncIntervalMinutes`	Integer	Nei (default `60`)	Anbefalt minste intervall mellom synker (informativt; styres faktisk av scheduler)
`EnableDeltaSync`	Boolean	Nei (default `false`)	Hvis `true`: husker `LastSyncTimestamp` mellom kjøringer og sender `changedSince` til API-et. Første kjøring blir full synk
`DeltaFromDate`	String (`yyyy-MM-dd` eller `yyyyMMdd`)	Nei	Fast startdato for `changedSince` — overstyrer både `EnableDeltaSync` og scheduler-parameter `ChangedSince` hvis satt
`VoucherTypeFilter`	String (komma-separert)	Nei	Post-fetch filter på `VoucherType`. Tom = alle typer. Eksempel: `"100,200"`
`InvertAmount`	Boolean	Nei (default `false`)	Snur fortegnet på `Amount` (når kilde-bokføring har omvendt sign-konvensjon)
`DebugLogging`	Boolean	Nei (default `false`)	Detaljert logging av API-kall

Scheduler-parameter (ikke i ConfigurationJson):

Parameter	Format	Forklaring
`ChangedSince`	ISO-8601 (`yyyy-MM-ddTHH:mm:ss`)	Eksplisitt overstyring av `changedSince` per kjøring. Har høyest prioritet

Prioritetsrekkefølge for changedSince:

FilterCriteria.ChangedSince (per kjøring) — høyest prioritet
DeltaFromDate (fast dato i config)
EnableDeltaSync = true + LastSyncTimestamp (watermark) — kun hvis intet av over er satt
Ellers: full synk (ingen filter)

Eksempel ConfigurationJson:

{
  "TimeoutSeconds": 60,
  "DefaultMarkupPercent": 15.0,
  "SyncIntervalMinutes": 60,
  "EnableDeltaSync": true,
  "DeltaFromDate": "",
  "VoucherTypeFilter": "",
  "InvertAmount": false,
  "DebugLogging": false
}

Hemmelig håndtering: Adapteren bruker IKontiConnectAuthService.GetAccessTokenAsync() som henter dekrypterte credentials fra sentrale innstillinger. Tokenet caches og fornyes automatisk.

Slik gjør du — oppsett¶

1. Konfigurer globale Konti Connect-credentials (én gang per tenant)¶

I ePortal:

Innstillinger → Konti Connect → Innstillinger (globale)
Fyll inn ApiBaseUrl, ClientId, ClientSecret, TokenUrl, TenantId, ApiClientId
Klikk Test tilkobling

Disse brukes av alle integrasjoner som benytter Konti Connect API.

2. Opprett integrasjon i Konti Connect¶

I ePortal:

Innstillinger → Konti Connect → Ny integrasjon
Type: KontiConnect (eksterne kostnader)
Sett DefaultMarkupPercent etter hva som er normal margin
Vurder EnableDeltaSync = true for produksjon (hyppig synk med watermark)
Sett scheduler — typisk hvert 15.–60. minutt
Lagre

3. Test første kjøring¶

Bruk Kjør nå
Følg kjøringsloggen:
"Hentet N kostnader"
Per-rad: "Oppdatert" / "Opprettet" / "Hoppet over (arbeidsordre ikke funnet)"
Verifiser i Arbeidsordre-modulen at eksterne kostnader er knyttet til riktig WoNo

Mapping og kategorisering¶

Nøkkel: Konti Connect Id ↔ ePortal ExternalCostId (unik per kilde-bilag)
Arbeidsordre-matching: cost.WoNo ↔ wv_WorkOrder.WoNo. Hvis ingen match: kostnaden hoppes over (logges som skipped)
Auto-kategorisering basert på kontonummer fra Visma:
4000–4999 → Material
5000–5999 → Subcontractor (underleverandør)
6000–6999 → Transport
Ellers → Other
Sekundært justeres kategorien basert på fritekst i beskrivelsen
Påslag: DefaultMarkupPercent (kan overstyres manuelt per linje senere)
Fortegn: InvertAmount = true snur Amount (typisk hvis kilden bokfører kostnad negativt)
Idempotens: upsert basert på ExternalCostId — samme Id oppdateres, ingen duplikater

Watermark¶

Ved EnableDeltaSync = true og minst én vellykket rad:

LastSyncTimestamp = nåværende UTC-tidsstempel lagres i ConfigurationJson
Neste kjøring sender changedSince=<dato> til API-et — kun endrede poster returneres

Frekvens og volum¶

Token caches sentralt — ikke per kjøring
401-håndtering: cached token invalideres ved første 401 og et nytt forsøk gjøres med fersk token (samme attempt-teller)
3 retries med eksponentiell backoff på transient feil (5xx, timeouts)
Sidestørrelse: hele datasettet i én respons (paginering er ikke implementert — anbefales hyppig synk for store volumer)

Sikkerhet¶

OAuth2-credentials lagres kryptert (AES via EncryptionService) i wv_SystemConfiguration via SettingsService
Bearer-token logges aldri i fulltekst
Adapteren skriver kun til wv_WorkOrder_ExternalCost — ingen sletting eller massendringer av arbeidsordrer
Kun arbeidsordrer som finnes lokalt får kostnader importert (matching på WoNo) — ingen automatisk opprettelse av nye arbeidsordrer fra eksterne data

Vanlige problemer¶

`Konti Connect globale innstillinger mangler`¶

Sentrale innstillinger er ikke fylt ut. Gå til Innstillinger → Konti Connect → "Innstillinger" og fyll inn ApiBaseUrl, ClientId, ClientSecret, TokenUrl, Scope.

Kostnader importeres ikke selv om Konti Connect har data¶

Sjekk at WoNo på kostnaden faktisk finnes i ePortal (matching-nøkkel)
Sjekk VoucherTypeFilter — hvis satt, hopper alle andre typer over
Skru på DebugLogging for å se hva API-et returnerer
Verifiser delta-synk-tidsstemplet — LastSyncTimestamp kan ha "spist opp" perioden hvis tidligere kjøring var vellykket

Påslag stemmer ikke¶

DefaultMarkupPercent brukes som default. Endre per linje i Arbeidsordre-detaljen, eller juster default-en og kjør på nytt for nye linjer (eksisterende rør ikke).

Fortegn er omvendt¶

Sett InvertAmount = true hvis Visma bokfører kostnader som negative tall.

401 Unauthorized — token gyldig?¶

Adapteren håndterer 401 automatisk ved å invalidere cached token og hente fersk. Hvis det vedvarer: sjekk om ClientSecret er rotert hos Konti, eller om scope er endret.

Duplikater i `wv_WorkOrder_ExternalCost`¶

Adapteren upserter på ExternalCostId. Hvis du ser duplikater: sjekk at Konti Connect API leverer unike Id-verdier per bilag.

`LastSyncTimestamp` er feil — synk hopper over poster¶

Sett DeltaFromDate til ønsket startdato for å overstyre watermarket, eller sett EnableDeltaSync = false for en full synk og slå deretter på delta-synk igjen.