Migrering til REST v2/v3
SOAP og REST v1 avvikles
SOAP-API-ene (V4–V11) slås av 1.1.2027. REST v1 slås av 31.7.2027. Nye integrasjoner skal bruke REST v2/v3.
Bruker dere SOAP eller REST v1 i dag, kan dere opprette en ny integrasjon automatisk. Se Migrering til REST v2/v3 og kunngjøringen på ksdigital.no.
Denne siden er for dere som sender med SOAP eller REST v1 i dag. Den viser hvordan dere får tilgang til REST v2/v3 uten å sette opp alt fra bunnen, og hva hver gammel operasjon heter i de nye API-ene.
Slik migrerer dere
- Maskinporten. Leverandøren må ha en Maskinporten-klient med scopet
ks:fiks. Se Maskinporten. - Systemkatalogen. Leverandøren må være registrert i Systemkatalogen til KS Digital. Se Systemkatalogen.
- Opprett integrasjon. Kall migreringsendepunktet med brukernavnet og passordet dere bruker i dag. Da får dere en Fiks-integrasjon som har tilgang til å sende fra den samme SvarUt-kontoen.
- Bytt kall. Bytt ut operasjonene, se Fra gamle til nye operasjoner.
- Test. Test i testmiljøet før dere tar det i bruk i produksjon.
Migreringsendepunktet
POST /svarut-konfigurasjon/api/v1/migrering/integrasjoner (spesifikasjon)
| Miljø | Base-URL |
|---|---|
| Test | https://api.fiks.test.ks.no |
| Produksjon | https://api.fiks.ks.no |
Endepunktet ligger på Fiks-plattformen, ikke på svarut.ks.no som de andre SvarUt-API-ene.
Kallet krever to ting:
- HTTP Basic med brukernavnet og passordet til SvarUt-kontoen, slik dere bruker for SOAP og REST v1. Det viser at dere har tilgang til kontoen.
maskinportenTokeni body. Et gyldig token fra Maskinporten. Organisasjonsnummeret i tokenet blir autorisert organisasjon på den nye integrasjonen.
Svaret:
Bruk id i headeren IntegrasjonId, passord i IntegrasjonPassord og kontoId i URL-en. Se Sende post.
Det blir bare én integrasjon per SvarUt-konto. Kaller dere endepunktet på nytt, får dere et nytt passord, og det gamle slutter å virke.
Systemkatalogen
Systemkatalogen er KS Digital sin oversikt over leverandører, fag- og arkivsystemer og hvilke integrasjoner de bruker. Med den kan KS Digital for eksempel varsle riktig leverandør direkte hvis en integrasjon får autorisasjonsfeil.
Organisasjonsnummeret i maskinportenToken må være registrert som leverandør i Systemkatalogen. Ellers blir kallet avvist.
Dere kan også knytte integrasjonen til et bestemt system ved å sende med systemkatalogProduktId. Det er ikke påkrevd, men anbefalt. Produktet må høre til leverandøren med organisasjonsnummeret i tokenet.
Inntil videre er det brukerstøtte som registrerer leverandører og produkter. Send en e-post til fiks@ksdigital.no for å bli registrert, og be om at fag- eller arkivsystemet registreres som produkt hvis dere vil bruke systemkatalogProduktId.
Fra gamle til nye operasjoner
Noen ting er annerledes i v3:
- Det er ett send-endepunkt per type mottaker. Feltene er litt ulike for hver type.
- Statusene er flere og mer presise. Se Fra status v2 til v3.
krevNiva4Innloggingheter nåsikkerhetsnivaog har verdieneBETYDELIGogHOYESTE.svarPaForsendelseLinkheter nåkanSvareViaEdialog.
| SOAP | REST v1 | REST v2/v3 |
|---|---|---|
sendForsendelse |
POST /sendForsendelse |
POST /v3/kontoer/{kontoId}/forsendelser/person, /organisasjon, /nhn eller /print |
startNyForsendelse, sendForsendelseMedId |
POST /startNyForsendelse, POST /{id}/sendForsendelse |
Finnes ikke. Id-en kommer i svaret når du sender. |
retrieveForsendelsesStatus, retrieveForsendelsesStatuser |
GET /{id}/status, POST /statuser |
POST /v3/kontoer/{kontoId}/forsendelser/status/sok |
retrieveForsendelsesHistorikk |
GET /{id}/historikk |
GET /v2/forsendelser/{id}/hendelser |
retrieveSigneringsHistorikk |
GET /{id}/signeringhistorikk |
GET /v2/forsendelser/{id}/signeringshendelser |
retrieveDokumentMetadata |
GET /{id}/dokumentMetadata |
GET /v2/forsendelser/{id}/metadata |
setForsendelseLestAvEksterntSystem |
POST /{id}/settLest |
POST /v2/forsendelser/{id}/lest |
retrieveForsendelsesIderByEksternRef |
GET /eksternref/{eksternref} |
GET /v2/kontoer/{kontoId}/forsendelser?eksternRef=... |
retreiveForsendelsesTyper |
GET /forsendelseTyper |
GET /v2/forsendelsestyper |
retrieveMottakerSystemForOrgnr |
GET /mottakersystem/{orgnr} |
GET /v2/mottakersystem |
Få hjelp
📞 Få hjelp
- E-post: fiks@ksdigital.no
- Support-kanaler: Se oversikt over alle kanaler