En integrasjon på Fiks-plattformen er en maskin-til-maskin klient som benytter tjenestelaget for å utføre oppgaver på vegne av en fiks-organisasjon. Dette kan for eksempel være et arkivsystem som sender saker gjennom Fiks SvarInn, eller et fagsystem som oppdaterer meldinger i Fiks Innsyn.
Når en Fiks-organisasjon tar i bruk plattformen vil man se at det allerede finnes en del forhåndsdefinerte integrasjoner, for eksempel en SvarUt-integrasjon mot Fiks Innsyn. Dette er “globale integrasjoner” som blir tilgjengelig for alle Fiks-organisasjoner uten at hver organisasjon trenger å opprette dem. Ta kontakt med fiks-kundeservice om du på denne måten ønsker å gjøre en av dine integrasjoner tilgjengelig på hele plattformen. Dette er for det meste relevant for leverandører av skyløsninger for flere kommuner.
Hver Fiks-organisasjon kan også opprette sine egne “lokale” integrasjoner - dette gjøres gjennom Fiks Konfigurasjon. Her opprettes integrasjonen, og man definerer hvilken organisasjon som skal ha rett til å sende forespørseler til Fiks-plattformen på vegne av denne. Organisasjonen kan være Fiks-organisasjonen selv, eller en tredjepart som har driftsansvar. Se under for detaljer om opprettelse av integrasjoner.
Etter organisasjonen er opprettet må den autoriseres for å kunne handle på vegne av en Fiks-organisasjon. Om man for eksempel ønsker å autorisere en integrasjon for å indeksere meldinger Fiks Innsyn må det relevante privilegiet tildeles på konfigurasjonssiden for denne tjenesten. Dette gjelder også for globale integrasjoner.
Integrasjoner mot Fiks-plattformen vil hovedsakelig benytte grensesnitt basert på REST/json.
Vi publiserer OpenAPI-Specification for alle api’er. I dag benyttes versjon 3.0, noen tjenester kan være fortsatt være på 2.0. Disse spesifikasjonene er nyttige både som dokumentasjon for rest-grensesnittet og som grunnlag for automatisk generering av klienter og modell-objekter. Dette kan for eksempel gjøres ved bruk av Swagger Codegen.
En Fiks-organisasjon kan opprette egen integrasjoner gjennom Fiks konfigurasjon.
Integrasjoner autentiseres på to ulike måter: som “integrasjon” med OAuth 2.0, eller “integrasjon-person” m. Open Id Connect (OIDC). Fiks har laget klienter for å generere access token fra Maskinporten basert på et virksomhetssertifikat, en issuer (konto hos Difi) og ett eller flere scopes. Java-klient: https://github.com/ks-no/fiks-maskinporten, .net-klient: https://github.com/ks-no/fiks-maskinporten-client-dotnet.
Denne metoden benyttes for ren server til server integrasjon, for eksempel når et fagsystem skal laste opp meldinger til Fiks Innsyn. Organisasjonen henter et OAuth 2.0 access token med scope “ks:fiks” fra Maskinporten, basert på organisasjonens virksomhetssertifikat. Dokumentasjon for dette finnes her. Vi støtter i første omgang kun JWT access_tokens, dette må konfigureres hos ID-Porten. I tillegg til dette tokenet må man ha en header for integrasjonId og for integrasjonPassord.
Kallet mot Fiks-plattformtjenesten trenger dermed følgende HTTP headere:
Denne metoden benyttes hvis en innbygger er logget inn på en server i en kommune, og man ønsker å gjøre en forespørsel på vegne av denne innbyggeren. Man trenger fortsatt integrasjon-ID og integrasjonpassord, men i stedet for virksomhetens access token sender man brukerens, innhentet med “ks:fiks” scope via OIDC fra ID-Porten.
Kallet mot Fiks-plattformtjenesten trenger dermed følgende HTTP headere:
http POST https://api.fiks.test.ks.no/innsyn-sok/api/v1/sok \
"IntegrasjonId: <din integrasjon id>" \
"IntegrasjonPassord: <ditt integrasjon passord" \
"Authorization: Bearer <gyldig innbygger access token jwt fra id-porten>"I tillegg må integrasjonen autoriseres for tilgang til en spesifikk tjeneste. Hvis for eksempel et fagsystem skal kunne laste opp meldinger til Fiks Innsyn må en administrator i kommunen benytte Fiks-Konfigurasjon for å legge til denne tilgangen hos den relvante kommunen.
Dette gjelder også for integrasjoner som leveres som en del av Fiks-plattformen. Skal SvarUt kunne indeksere forsendelse i Fiks Innsyn må også her kommunen eksplisitt autorisere dette.
De fleste REST API-ene returnerer feilmeldinger på følgende format:
{
"timestamp": 1637218198035,
"status": 400,
"error": "Bad Request",
"errorId": "3389ad1b-afa4-42e1-b6f8-76f63e560ad5",
"path": "/tjeneste/api/v1/ressurs/123456",
"originalPath": "/tjeneste/api/v1/ressurs",
"message": "Beskrivelse av feilen",
"errorCode": "FEILKODE",
"errorJson": {"antall":13}
}
timestamp - Tidspunktet feilen oppstod i millisekunder siden epoch.status - HTTP-statuskode, f.eks. 400 eller 500.error - Beskrivelse av HTTP-statuskoden, f.eks. Bad Request eller Internal Server Error.errorId - Intern id som brukes til å finne informasjon relatert til feilen under feilsøking.path - Path requesten ble gjort mot.originalPath - Vil i sjeldne feilsituasjoner være noe annet enn det som er satt i path, og ellers ikke være satt.message - Menneskelig lesbar beskrivelse av feilen som oppstod.errorCode - Tjenestespesifikk feilkode for maskinell tolkning. Vil i de fleste situasjoner ikke være satt.errorJson - Detaljer knyttet til errorCode i JSON-format.