API: Integrasjon med SOAP

SOAP APIene er deprecated, og det vil ikke komme noen ny versjon av eller ny funksjonalitet til disse. Vi anbefaler bruk av nyeste versjon av REST-APIet for nye integrasjoner.

Tilgang

For å benytte web-tjenesten må en bruke HTTP Basic autentication med brukernavn(avsendernavn) og service-passord. Avsender opprettes av KS-SvarUt administrator/organisasjons administrator. Service-passordet genereres av avsender-ansvarlig via konfigurasjon-siden.

Nytt i denne versjonen

  • EksponertFor: Gir tilgang til andre enn mottaker å laste ned filene.
  • Feltet kunDigitalLevering er fjernet og erstattet med feltet leveringsmetode som er av type Leveringsmetode. Feltet er påkrevd og Leveringsmetode har tre verdier: STANDARD_SVARUT_LEVERANSE, KUN_DIGITAL_UTEN_LEVERANSEGARANTI og KUN_DIGITAL_UTEN_LEVERANSEGARANTI_MASSEUTSENDELSE
  • SigneringsLogg returnerer nå dato og Signeringsstatus.

Tjenester

Forsendelsesservicet tilbyr følgende funksjonalitet:

Operasjon Inndata Utdata Kort beskrivelse
sendForsendelse Forsendelse ForsendelsesId Hovedtjeneste som sender inn forsendelse til ekspedering av KS-SvarUt.
sendForsendelseMedId Forsendelse, ForsendelsesId ForsendelsesId Se sendForsendelse.
startNyForsendelse ForsendelsesId Genererer forsendelsesid som brukes sammen med sendForsendelseMedId.
retrieveForsendelsesStatus ForsendelsesId ForsendelsesStatus Henter status for en forsendelse.
retrieveForsendelsesStatuser List<ForsendelsesId> List<ForsendelsesStatus> Henter status for flere forsendelser.
retrieveForsendelsesHistorikk ForsendelsesId ForsendelsesHistorikk Henter historikk for en forsendelse, tilsvarer ekspederingsloggen i forsendelsesoversikten.
retrieveSigneringsHistorikk ForsendelsesId SigneringsHistorikk Henter signeringshistorikk (logg) på en forsendelse som er markert for signering.
retrieveSigneringsHistorikkForFlereForsendelser List<ForsendelsesId> List<SigneringsHistorikk> Henter signeringshistorikk for opp til 10 forsendelser.
setForsendelseLestAvEksterntSystem LestAv Benyttes for å sette status til lest når dokumentet har blitt lest utenfor vårt system.
retreiveForsendelsesTyper Set<String> Henter alle forsendelsestyper som kan brukes i SvarInn.
retrieveMottakerSystemForOrgnr OrganisasjonsNummer List<MottakerForsendelsesTyper> Henter alle konfigurerte mottakersystem for orgnr.
retrieveForsendelsesIderByEksternRef String List<ForsendelsesId> Henter liste med forsendelseider som har denne eksternRef.
retrieveDokumentMetadata ForsendelsesId List<DokumentMetadata> Henter liste med informasjon om dokumentene til en forsendelse.

Definisjonsfil (WSDL) for tjenesten finnes her https://svarut.ks.no/tjenester/forsendelseservice/ForsendelsesServiceV11?wsdl

Operasjoner

sendForsendelse

Hovedtjeneste som sender inn forsendelse til ekspedering av KS-SvarUt.

SendForsendelse for ekspedering i SvarUt. Hvis du får HTTP 200 ok er forsendelsen er mottat og akseptert av SvarUt. Dette betyr at vi da vil garantere levering til mottaker (kunDigital har ikke garantert levering). Hvis det skulle oppstå problemer vil avsender bli kontaktet. Dette betyr at jobben til avleverende system nå er ferdig.

Feilmeldinger på tjeneste skal kunne presenteres for bruker. Det kan komme tekniske feilmeldinger, men da er disse greit å vise hvis de skal kontakte SvarUt for hjelp.

sendForsendelseMedId

Samme som sendForsendelse, men avsender setter forsendelsesid. Id må være av type UUID. Se sendForsendelse.

startNyForsendelse

Genererer forsendelsesid (UUID) som brukes sammen med sendForsendelseMedId.

retrieveForsendelsesStatus

Henter status for en forsendelse. Denne bør brukers når det er behov for å vise status. Tenkt brukt f.eks om saksbehandler lurer på hva som er status på forsendelsen. Status kan endre seg på kort varsel, vi anbefaler derfor å ikke mellomlagre disse verdiene i eget system, men heller hente de når de skal vises.

retrieveForsendelsesStatuser

Henter status for flere forsendelseer. Samme som retrieveForsendelseStatus bare for flere forsendelser i samme kall.

retrieveForsendelsesHistorikk

Henter historikk for en forsendelse. Returnerer en liste med beskrivelse av hva som har skjedd og når det inntraff. Listen tilsvarer ekspederingsloggen i forsendelsesoversikten. Tenkt brukt hvis saksbehandler eller kundestøtte trenger å vite detaljene om en forsendelse.

retrieveSigneringsHistorikk

Henter signeringshistorikk for en gitt forsendelse.

retrieveSigneringsHistorikkForFlereForsendelser

Samme som retrieveSigneringshistorikk bare for flere forsendelser i samme kall, opp til 10 forsendelser.

setForsendelseLestAvEksterntSystem

Setter status for en forsendelse til lest basert på forsendelsesId. Benyttes for å sette status til lest når dokumentet har blitt lest utenfor vårt system.

retreiveForsendelsesTyper

Henter alle forsendelsestyper som Svarinn-mottakersystem kan konfigureres til å bruke.

retrieveMottakerSystemForOrgnr

Henter mottakersystem som er konfigurert for orgnr. Kan brukes hvis en vil vite om mottaker har konfigurert SvarInn og til hvilket system det vil havne.

retrieveForsendelsesIderByEksternRef

Henter liste med forsendelseider som har denne eksternRef.

retrieveDokumentMetadata

Henter liste med informasjon om dokumentene til en forsendelse.

Modeller

ForsendelsesId

Felt Type Beskrivelse Validating
id UUID

Forsendelse

Felt Type Beskrivelse Validering
mottaker Adresse Addresse, full post adresse må være utfylt, for sending til Altinn må digitaladresse med orgnr/fødselsnr være utfylt. Støtte for utenlandske adresser. Ved signeringsoppdrag må PersonDigitalAdresse brukes.
avgivendeSystem String Identifikator som identifiserer systemet som gjør web-service kallet, vil blant annet kunne benyttes for statistikk og feilsøking. Bruk følgende for sak/arkivsystemene: Doculive, Ephorte, ESA, 360 og Websak. For andre fagsystemer avtales dette med KS KommIT på svarut@ks.no. Obligatorisk felt.
tittel String Tittel på forsendelsen. Tittel blir vist i tittelfeltet på melding til Altinn, og i listen over innkommende meldinger. Må være utfylt
konteringsKode String Kode som beskriver faktureringskonto for forsendelsen. Kan benyttes for å gruppere meldingsstatistikk gjennom forvaltningsløsningen, og sendes videre til print-leverandør. ^[a-zA-Z0-9-.øæåØÆÅ]{0,20}$
leveringsmetode Leveringsmetode Dersom leveringsmetode er satt til en “kunDigital”-verdi blir leveransen kun forsøkt levert digitalt, ingen print og postlegging. Hvis dokumentet ikke kan leveres digital blir det ikke levert. Hvis KunDigitalLevering er valgt må fødselsnr eller orgnr være utfylt.
kryptert boolean Settes til true dersom fil(ene) som sendes er kryptert. Dersom kryptering ikke er brukt må denne være satt til false. Se kodeeksempler for eksempel på kryptering. Det må være kryptert med CMS med svarut sin publickey. Den offentlige nøkkelen PROD, Den offentlige nøkkelen for TEST
utskriftsKonfigurasjon UtskriftsKonfigurasjon Konfigurasjon for hvordan dokumentet skal printes, dobbeltsidig, fargeprint
krevNiva4Innlogging boolean Forsendelsen krever nivå 4-innlogging for å kunne lastes ned eller signeres. Disse forsendelsene må være kryptert.
metadataFraAvleverendeSystem NoarkMetadataFraAvleverendeSaksSystem Noark5 metadata fra avleverende system
metadataForImport NoarkMetadataForImport Noark5 metadata som stemmer med mottakende system. Kan brukes til å legge dokumentet på rett sak.
svarSendesTil Adresse Dersom feltet settes må full postadresse være utfylt. Dette er adressen det skal sendes til dersom en ønsker å svare på forsendelsen. En eventuell adresse som fylles inn her vil overstyre adressen fra avsenderens forsidekonfigurasjon. Den vil også fremkomme på forsiden av brevet dersom forsendelsen sendes i posten.
svarPaForsendelse ForsendelsesId Forsendelsesid til forsendelse dette er et svar på.
dokumenter List Rekkefølgen er rekkefølgen de kommer i brevet. Total filstørrelse inntil 350MB er støttet når det skal printes. Ellers er det ikke begrensning.
lenker List Rekkefølgen er samme som de vil komme i brevet. Kan være tom.
forsendelsesType String Fritekst felt for å kunne identifisere forsendelse type.
eksternReferanse String Ekstern id for forsendelsen, ingen sjekk på innhold i SvarUt. Det vil komme mulighet for å hente ut forsendelser i søk og via api på eksternref.
svarPaForsendelseLink boolean Dersom dette feltet settes til true vil forsendelsen avvises om svarSendesTil ikke inneholder en gyldig adresse med organisasjonsnummer. Hvis forsendelsen aksepteres og sendes digitalt, vil det genereres en lenke hvor mottaker kan sende et svar tilbake til adressen spesifisert i svarSendesTil.
signeringUtloper Date Angi hvor lenge signeringsoppdraget er gyldig, minimum 1 dag. Må angis ved signeringsforsendelser
signaturType SignaturType Velge mellom autentisert eller avansert signering. Må angis ved signeringsforsendelser
eksponertFor List Orgnr og fødselsnr i liste får også log å laste ned forsendelse filene.

LestAv

Felt Type Beskrivelse Validering
forsendelsesId ForsendelsesId
lestAvFodselsNummer String
navnPaEksterntSystem String
datoLest Date

OrganisasjonsNummer

Felt Type Beskrivelse Validering
id String

ForsendelsesStatus

Felt Type Beskrivelse Validering
forsendelsesId ForsendelsesId
sisteStatusEndring Date
status Status

Status

Verdi Beskrivelse
MOTTATT Et kall mottatt på forsendelses-service. En id blir tildelt forsendelsen.
AKSEPTERT Meldingen er validert og forsendelsesfil dannet.
KLAR_FOR_MOTTAK Venter på at forsendelse skal bli lastet ned av mottaker.
VARSLET Et varsel om forsendelsen er sendt til varslingstjenesten.
LEST En forsendelse er lest når hele forsendelsesfilen er lastet ned av mottaker.
SENDT_PRINT Forsendelsen er blitt overført til printleverandør.
SENDT_DIGITALT Forsendelsen er motatt og sendt slik den skal. Ikke blitt lest enda. Forsendelser med denne status vil kun leveres digitalt, og vil aldri gå til print.
SENDT_SDP Forsendelsen er motatt og sendt til Sikker digital postkasse.
LEVERT_SDP Forsendelsen er motatt og sendt til Sikker digital postkasse. Vi har motatt Leveringskvittering fra SDP. Forsendelsen skal da være tilgjengelig for mottaker.
PRINTET Printkvittering mottatt fra printleverandør eller manuell print bekreftet(via webgrensesnitt).
AVVIST Forsendelsen er ikke validert pga. manglende/korrupt metadata, eller fordi forsendelsesfil ikke kunne dannes.
IKKE_LEVERT Kun digital leveranse hvor vi ikke har klart å levere forsendelsen.
MANUELT_HANDTERT Forsendelsen er manuelt avsluttet, f.eks. pga en feilsituasjon.

ForsendelsesHistorikk

Felt Type Beskrivelse Validering
hendelsesLogger List<HendelsesLogg>

SigneringsHistorikk

Felt Type Beskrivelse Validering
forsendelsesId ForsendelsesId
logg List<SigneringsLogg>

MottakerForsendelsesTyper

Felt Type Beskrivelse Validering
organisasjonsNummer OrganisasjonsNummer
forsendelsesType String
mottakerSystem String
mottakerId String
niva Integer

DokumentMetadata

Felt Type Beskrivelse Validering
mimeType String
filnavn String
kanSigneres Boolean Bare en fil kan signeres og skal være av type PDF Validerer at maks ett dokument pr forsendelse har flagget slått på
sizeInBytes Long
sha256hash String
dokumentType String
nedlasningsUrl String
signeringsUrl String
ekstraMetadata List<Entry>
inneholderPersonsensitivInformasjon Boolean

HendelsesLogg

Felt Type Beskrivelse Validering
tidspunkt String
hendelse String

SigneringsLogg

Felt Type Beskrivelse Validering
tidspunkt Date
type Signeringsstatus
hendelse String

Adresse

Felt Type Beskrivelse Validering
postAdresse PostAdresse Adressen forsendelsen sendes til dersom den går via brevpost Kan ikke være null
digitalAdresse DigitalAdresse Se OrganisasjonDigitalAdresse og PersonDigitalAdresse

PostAdresse

Felt Type Beskrivelse Validering
navn String Navn på mottaker Må være utfylt.
adresse1 String Adresselinje1
adresse2 String Adresselinje2
adresse3 String Adresselinje3
postSted String Poststed Må være utfylt dersom forsendelsen ikke er kun digital.
postNummer String Postnummer Må være utfylt dersom forsendelsen ikke er kun digital. Fire siffer for norske adresser.
land String Land Må være utfylt dersom forsendelsen ikke er kun digital.

DigitalAdresse

Se OrganisasjonDigitalAdresse og PersonDigitalAdresse

OrganisasjonDigitalAdresse

Felt Type Beskrivelse Validering
organisasjonsNummer OrganisasjonsNummer Må være utfylt for å kunne levere til altinn.

PersonDigitalAdresse

Felt Type Beskrivelse Validering
fodselsNummer String Må være utfylt for å kunne levere til altinn. Ved signeringsoppdrag må dette feltet være utfylt.

UtskriftsKonfigurasjon

Felt Type Beskrivelse Validering
utskriftMedFarger boolean
tosidig boolean

NoarkMetadataFraAvleverendeSaksSystem

Felt Type Beskrivelse Validering
saksSekvensNummer Integer
saksAar Integer
journalAar Integer
journalSekvensNummer Integer
journalPostNummer Integer
journalPostType String
journalStatus String
journalDato Date
dokumentetsDato Date
tittel String
saksBehandler String
ekstraMetadata List<Entry>

NoarkMetadataForImport

Felt Type Beskrivelse Validering
saksSekvensNummer Integer
saksAar Integer
journalPostType String
journalStatus String
dokumentetsDato Date
tittel String

Dokument

Felt Type Beskrivelse Validering
filnavn String Filnavn er for intern bruk, må være unikt i en forsendelse. Max 226 tegn. Må ikke inneholde mappe, kun filnavn. (ingen / eller ) Disse tegnene er også ugyldige " < > ? * | : De har andre funksjoner i windows og kan ikke brukes i filnavn på windows. Skiller ikke mellom store og små bokstaver i filnavnet.
mimeType String Mimetype på være application/pdf hvis den skal til print. Kun digital levering er valgt kan vi ta imot annet. Kun application/pdf hvis den skal til print
skalSigneres Boolean Angir om dokumentet skal signeres Bare et dokument kan signeres og må være av type PDF
dokumentType String Fritekstfelt som kan brukes til å fortelle noe om dokumentTypen til feltet. Kan brukes til noark4 dokumenttyper
data DataHandler Fildata
giroarkSider Set<\Integer> Liste med sidetall som skal printes på gult giroark. Digital versjon vil få grått giroark. Første side er 1.
ekskluderesFraUtskrift Boolean Dette dokumentet blir ikke med i utskrift av forsendelsen. Brukes til filer som kun er interessant for digital levering. F.eks xml, video eller lyd filer
ekstraMetadata List<Entry> Brukes til andre data som avsender vil ha med i forsendelsen
inneholderPersonsensitivInformasjon Boolean Brukes for å gjøre mottaker oppmerksom på at dokumentet kan inneholde sensitiv informasjon

Lenke

Felt Type Beskrivelse Validering
urlLenke String Selve lenken til dokument/nettside Må være utfylt og være i gyldig lenke format, altså (http/https/ftp)://(nettside).(com/no/ etc)
urlTekst String Må være utfylt
ledeTekst String Teksten som kommer før lenken i brevet

SignaturType

Verdi Beskrivelse
AUTENTISERT_SIGNATUR
AVANSERT_SIGNATUR

Entry

Felt Type Beskrivelse Validering
key String
value String

Leveringsmetode

Verdi Beskrivelse
STANDARD_SVARUT_LEVERANSE Standard leveringsmetode og vil oppføre seg på samme måte som om feltet kunDigitalLevering var satt til usann
KUN_DIGITAL_UTEN_LEVERANSEGARANTI Vil avvise forsendelser til privatpersoner dersom KRR ikke finner vedkommende eller vedkommende har reservert seg
KUN_DIGITAL_UTEN_LEVERANSEGARANTI_MASSEUTSENDELSE Vil oppføre seg på samme måte som om feltet kunDigitalLevering var satt til sann

Signeringsstatus

Verdi Beskrivelse
AVVIST_AV_SVARUT
VENTER_SIGNERING
SIGNERT_AV_MOTTAKER
AVVIST_AV_MOTTAKER
UTLOPT