For utviklere¶
Denne seksjonen er for tredjeparts-utviklere og systemintegratorer som skal koble eksterne systemer mot ePortal. Hvis du er sluttbruker, finner du raskere svar i de andre rolle-inngangene.
Tilgang: Kontakt Konti for å få utstedt credentials (API-nøkkel for v1, eller Azure AD client credentials for v2).
Hva er ePortal Integration API?¶
ePortal eksponerer et REST-basert integration API for å lese og skrive tid, arbeidsordre, prosjekt, regnskap, CRM og andre kjernedata. API-et er en separat .NET 8-løsning som driftes som https://connect.elportal.no og deler datamodell med hoved-ePortal.
- Basis-URL:
https://connect.elportal.no - To versjoner aktive samtidig:
- v2 — Azure AD OAuth 2.0 (anbefalt for nye integrasjoner)
- v1 — API-nøkkel via
X-API-Key-header (legacy, vedlikeholdes) - URL-mønster:
/api/v1/{Controller}og/api/v2/{Controller}(URL-segment-versjonering) - Format: JSON, OpenAPI 3.0 (generert av Swashbuckle 9)
- Support: hjelp@konti.no | https://hjelp.konti.no
Hvilken versjon skal jeg bruke? Ny integrasjon: v2 med OAuth. Eksisterende integrasjon på X-API-Key: kjør v1 inntil videre, planlegg migrering til v2 ved naturlig oppgradering.
Hovedkategorier¶
Tallene er antall HTTP-endepunkter ([HttpGet/Post/Put/Delete]) per controller. Hver kategori har én controller i v1 og én i v2 (parallelle implementasjoner).
| Kategori | Hva | v1 | v2 |
|---|---|---|---|
| Accounting | Ansvarlige enheter, voucher-typer, lager, kontoplan, business units, leverandører | 21 | 22 |
| Actor | Aktører — kunder, leverandører, ansatte | 13 | 12 |
| Configuration | System-oppsett og helsesjekker | 5 | 5 |
| Deal | CRM-avtaler med pipelines og stages | 8 | 8 |
| NisAssets | NIS-aktiva (anleggsmidler) | 3 | 3 |
| Product | Produkter / artikler | 5 | 5 |
| ProjectTask | Prosjektoppgaver | 7 | 7 |
| Time | Wagetypes og daglige/månedlige registreringer | 14 | 15 |
| WorkOrder | Arbeidsordre, linjer og kostnadssporing | 7 | 7 |
| Totalt | 83 | 84 |
Fullstendig liste over endepunkter, request-/response-skjema og prøvekall finner du i interaktiv referanse. For ende-til-ende-flyten, tenantvalg og databaseeffekter, se Integration API — prosesskart.
Kom i gang¶
- Få credentials — kontakt Konti support:
- For v2: tenant-ID, client-ID og client secret for Azure AD-app, samt API-resource-ID (audience)
- For v1: API-nøkkel (sendes i
X-API-Key-header) - Les API-referansen — interaktiv Swagger-utforsker lar deg prøve endepunkter direkte
- Test mot sandkasse-tenant — produksjonsdata skal aldri brukes til utvikling
- Implementer mot v2 — anbefalt for nye integrasjoner
Auth-eksempler¶
v2 — OAuth 2.0 (anbefalt)¶
v2-endepunkter ligger under /api/v2/... og krever JWT Bearer-token utstedt av Azure AD. Token validering konfigureres med både v1- og v2-issuer (sts.windows.net/{tenant}/ og login.microsoftonline.com/{tenant}/v2.0), så begge token-formater fungerer.
Steg 1: Hent access token via client credentials flow.
$tenantId = "<din-tenant-id>"
$clientId = "<din-client-id>"
$clientSecret = "<din-client-secret>"
$apiClientId = "<api-client-id>" # API resource-ID fra Konti
$tokenResponse = Invoke-RestMethod -Method Post `
-Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" `
-Body @{
grant_type = "client_credentials"
client_id = $clientId
client_secret = $clientSecret
scope = "api://$apiClientId/.default"
}
$accessToken = $tokenResponse.access_token
Steg 2: Bruk token i Authorization-header.
$headers = @{ "Authorization" = "Bearer $accessToken" }
Invoke-RestMethod `
-Uri "https://connect.elportal.no/api/v2/Time/timesheet/day?EmployeeNo=123&Date=20260610" `
-Headers $headers
curl-eksempel:
# 1. Hent token
TOKEN=$(curl -s -X POST \
"https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token" \
-d "grant_type=client_credentials" \
-d "client_id=<client-id>" \
-d "client_secret=<client-secret>" \
-d "scope=api://<api-client-id>/.default" \
| jq -r .access_token)
# 2. Kall API
curl -H "Authorization: Bearer $TOKEN" \
"https://connect.elportal.no/api/v2/Time/timesheet/day?EmployeeNo=123&Date=20260610"
Token-caching
Access tokens fra Azure AD varer ca. 1 time. Cache token i applikasjonen og fornye når den utløper — ikke hent ny token per request.
v1 — X-API-Key (legacy)¶
Alle requests mot /api/v1/... må inneholde X-API-Key-header. Middlewaren validerer nøkkelen mot tenant-databasen og avviser:
- Manglende eller tom header →
401 Unauthorizedmed"API Key is missing." - Ugyldig nøkkel →
403 Forbiddenmed"Invalid API Key."
GET /api/v1/Time/timesheet/day?EmployeeNo=123&Date=20260610 HTTP/1.1
Host: connect.elportal.no
X-API-Key: <din-nøkkel>
Accept: application/json
PowerShell:
$headers = @{ "X-API-Key" = "<din-nøkkel>" }
Invoke-RestMethod `
-Uri "https://connect.elportal.no/api/v1/Time/timesheet/day?EmployeeNo=123&Date=20260610" `
-Headers $headers
curl:
curl -H "X-API-Key: <din-nøkkel>" \
"https://connect.elportal.no/api/v1/Time/timesheet/day?EmployeeNo=123&Date=20260610"
Generelle prinsipper¶
| Tema | Detalj |
|---|---|
| Versjonering | URL-segment (/api/v{version}/...). Default-versjon er v1 hvis ingen er spesifisert |
| HTTPS | UseHttpsRedirection() er aktivert — HTTP-trafikk omdirigeres |
| Tidsstempel | ISO 8601, dato-felt på yyyyMMdd-form der det er eksplisitt definert (f.eks. timeregistrering) |
| String-trimming | Alle innkomne strenger blir auto-trimmet via TrimStringJsonConverter |
| Versjonsheader i respons | API-en setter api-supported-versions-header (ReportApiVersions = true) |
| Healthcheck | GET /health er definert, men dagens API-key middleware krever i praksis X-API-Key fordi bare /api/v2 er unntatt |
Feilformat¶
API-en bruker et eget JSON-respons-format ApiResponse<T> — ikke RFC 7807 Problem Details. Uhåndterte unntak fanges av ExceptionHandlingMiddleware og oversettes til:
| Unntak | Status | message |
|---|---|---|
ArgumentException |
400 | unntakets melding |
InvalidOperationException |
400 | unntakets melding |
UnauthorizedAccessException |
401 | "Unauthorized access" |
| Andre | 500 | "Internal server error" |
Uhåndterte feil fra exception-middlewaren ser slik ut:
{
"success": false,
"message": "An error occurred while processing your request",
"data": null,
"timestamp": "2026-06-07T10:15:00Z",
"errorCode": null
}
errorCode settes ved enkelte feil for korrelering mot Konti servicedesk.
Vanlige controller-responser beholder PascalCase (Success, Message, ...),
mens exception-middlewaren bruker camelCase. Bruk case-insensitiv
deserialisering.
Sikkerhet og personvern¶
- Credentials skal aldri commitres — bruk Azure Key Vault, miljøvariabler eller en secrets manager
- Roter nøkler regelmessig — minst hver 12. måned, og umiddelbart ved mistenkt kompromittering
- Bare minimum scope — be om credentials med snevrest mulig tilgang
- HTTPS er obligatorisk —
https://connect.elportal.noredirecter HTTP-trafikk - GDPR-ansvar — du som integrator har ansvar for at data du henter behandles iht. databehandleravtale med kunden
Vanlige integrasjonsmønstre¶
| Du vil... | Endepunktgruppe |
|---|---|
| Synke ansatte fra HR-system | Actor |
| Eksportere timer til lønnssystem | Time (daily / monthly) |
| Importere arbeidsordre fra ERP | WorkOrder |
| Synke kundeliste fra CRM | Actor |
| Bygge bookkeeping/voucher | Accounting |
| Synke produkter / artikler | Product |
| Bygge dashboard på prosjekt-oppgaver | ProjectTask |
| Synke salgsmuligheter | Deal |
Slik kommer du i gang med en ny integrasjon¶
- Kontakt Konti og avtal hvilke datatyper du skal lese/skrive og om du trenger v1- eller v2-credentials.
- Konti utsteder credentials og oppretter sandkasse-tenant.
- Åpne Connect API — interaktiv referanse og let opp aktuelle endepunkter under riktig controller-gruppe.
- Trykk Authorize i Swagger UI og lim inn enten API-nøkkel (v1) eller Bearer-token (v2).
- Prøv et
GET-kall mot sandkasse — verifiser at responsen er{ "success": true, ... }. - Implementer og testkjør mot sandkasse før du flyttes til produksjon.
Vanlige problemer¶
| Symptom | Sannsynlig årsak | Tiltak |
|---|---|---|
401 Unauthorized med "API Key is missing." på v1 |
X-API-Key-header ikke sendt eller tom |
Verifiser at headeren legges på alle requests (sjekk middleware-kjeden i klienten) |
403 Forbidden med "Invalid API Key." på v1 |
Nøkkelen er feil, deaktivert eller hører til en annen tenant | Be Konti om verifisering — ikke gjenbruk nøkler på tvers av tenants |
401 Unauthorized på v2 uten JSON-kropp |
JWT mangler, er utløpt, har feil audience, eller feil issuer | Hent ny token, sjekk at scope=api://{api-client-id}/.default matcher API-resource-ID |
500 Internal server error med generisk melding |
Uhåndtert unntak på serveren — er logget med Serilog | Kontakt Konti med tidspunkt + errorCode hvis satt i responsen |
Tom respons eller 404 på /v1/... eller /v2/... |
Mangler /api/-prefiks i URL |
URL-mønsteret er /api/v1/... og /api/v2/... — ikke bare /v1/... |
Relaterte sider¶
- Connect API — interaktiv referanse — Swagger UI for både v1 og v2
- Integration API — prosesskart — autentisering, tenant, dataeffekter og drift
- Integrasjoner — oversikt over ferdige adaptere i ePortal