SOAP V7

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.

Tjenester

Forsendelsesservicet tilbyr følgende funksjonalitet:

Operasjon Inndata Utdata Kort beskrivelse
sendForsendelse Forsendelse forsendelsesid Hovedtjeneste som sender inn forsendelse til ekspedering av KS-SvarUt.
retrieveForsendelseStatus forsendelsesid ForsendelseStatus Henter status for en forsendelse.
retrieveForsendelseStatuser List<forsendelsesid> List<StatusResult> Henter status for flere forsendelseer. Returnerer liste med status, når status oppstod og forsendelseid.
retrieveForsendelseHistorikk forsendelsesid ForsendelseHistorikk Henter historikk for en forsendelse, tilsvarer ekspederingsloggen i forsendelsesoversikten.
retrieveForsendelseIdByEksternRef eksternref List<forsendelsesid> Henter liste med forsendelseider som har denne eksternRef.
setForsendelseLestAvEksterntSystem forsendelsesid,
lestAvFodselsnummer,
navnPaEksterntSystem,
datoLest
(Ingen retur) Benyttes for å sette status til lest når dokumentet har blitt lest utenfor vårt system.

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

sendForsendelse

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.

Følgende metadata inkluderes:

Felt Beskrivelse Validering
Mottaker PrivatPerson eller Organisasjon, full adresse må være utfylt, for sending til Altinn må orgnr/fødselsnr være utfylt. Støtte for utenlandske adresser. Ved signeringsoppdrag må dette feltet være av type PrivatPerson.
Navn Navn på mottaker. Må være utfylt
Adresse1 Adresselinje1
Adresse2 Adresselinje2
Adresse3 Adresselinje3
Postnr Postnummer Må være utfylt, 4 tall for norske adresser
Poststed Poststed Må være utfylt
Land Land
Fødselsnr Hvis Privat, må være utfylt for å kunne levere til altinn. Ved signeringsoppdrag må dette feltet være utfylt.
Orgnr Hvis organisasjon, må være utfylt for å kunne levere til altinn.
Avgivende system 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](mailto:svarut@ks.no). Obligatorisk felt.
forsendelseType Fritekst felt for å kunne identifisere forsendelse type.
eksternref 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.
Tittel Tittel på forsendelsen. Tittel blir vist i tittelfeltet på melding til Altinn, og i listen over innkommende meldinger. Må være utfylt
Konteringskode 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}$
Printkonfigurasjon Konfigurasjon for hvordan dokumentet skal printes, dobbeltsidig, fargeprint, A-Post, B-Post
KunDigitalLevering Vi leverer kun 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 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](https://svarut.ks.no/forsendelse/publickey/hent), [Den offentlige nøkkelen for TEST](https://test.svarut.ks.no/forsendelse/publickey/hent)
krevNiva4Innlogging Forsendelsen krever nivå 4-innlogging for å kunne lastes ned eller signeres. Disse forsendelsene må være kryptert.
svarPaForsendelse Forsendelseid til forsendelse dette er et svar på.
svarPaForsendelseLink 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.
Liste med filer 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.
Filnavn 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.
Mimetype 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
Data Fildata
GiroarkSider Liste med sidetall som skal printes på gult giroark. Digital versjon vil få grått giroark. Første side er 1.
skalSigneres Angir om filen skal signeres Bare en fil kan signeres og skal være av type PDF
Liste med Lenker Rekkefølgen er samme som de vil komme i brevet. Kan være tom.
Url lenke Selve lenken til dokument/nettside Må være utfylt og være i gyldig lenke format, altså (http/https/ftp)://(nettside).(com/no/ etc)
Url tekst Må være utfylt
Ledetekst Teksten som kommer før lenken i brevet
Metadata fra avleverende system Noark5 metadata fra avleverende system, foreløbig oversikt
Saksekvensnummer
Saksaar
Journalaar
Journalseksvensnummer
Journalpostnummer
Journalposttype
Journalstatus
Journaldato
DokumentetsDato
Tittel
Saksbehandler
EkstraMetadata Liste med key,value for forskjellige behov. Keys må være unique.
Metadata i mottakende system Noark5 metadata som stemmer med mottakende system. Kan brukes til å legge dokumentet på rett sak. Samme som over.
Saksekvensnummer
Saksaar
Journalposttype
Journalstatus
DokumentetsDato
Tittel
SvarSendesTil PrivatPerson eller Organisasjon, full adresse må være utfylt. Dette er mottaker som en skal sende til om en vil svare på forsendelsen. Valgfritt å fylle ut. Dette blir brukt som avsender adresse i digital kommunikasjon og på print i posten. Vil overstyre avsender adresse i konfigurasjonen. Ved signeringsoppdrag må feltet være satt til Organisasjon
Navn Navn på mottaker. Må være utfylt
Adresse1 Adresselinje1
Adresse2 Adresselinje2
Adresse3 Adresselinje3
Postnr Postnummer Må være utfylt
Poststed Poststed Må være utfylt
Land Land
Fødselsnr Må være utfylt om en skal svare til privatperson.
Orgnr Må være utfylt om en skal svare til en organisasjon. Ved signeringsoppdrag må organisasjonsnummer må være fylt ut.
signeringUtloper Angi hvor lenge signeringsoppdraget er gyldig, minimum 1 dag. Må anngis ved signering
signaturtype Velge mellom autentisert eller avansert signering. Må anngis ved signering

retrieveForsendelseStatus

Henter status for en forsendelse. Denne bør bruker 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.

En forsendelse kan ha en av tilstandene beskrevet under:

Tilstander (normalløp):
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).
Tilstander (unntak):
Avvist
Forsendelsen er ikke validert pga. manglende/korrupt metadata, eller fordi forsendelsesfil ikke kunne dannes.
Manuelt håndtert
Forsendelsen er manuelt avsluttet, f.eks. pga en feilsituasjon.

retrieveForsendelseStatuser

Henter status for flere forsendelseer. Samme som retrieveForsendelseStatus bare for flere forsendelser i samme kall. Returnerer liste med status, når status oppstod og forsendelseid.

forsendelseid
Id på forsendelsen.
sisteStatusEndring
Når statusen endret seg sist
ForsendelseStatus
Siste forsendelse status

retrieveForsendelseHistorikk

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 ved en forsendelse.

Felt Beskrivelse Validering
Forsendelsesid Identifikator som unikt identifiserer en forsendelse. Må være utfylt

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.

Felt Beskrivelse Validering
Forsendelsesid Identifikator som unikt identifiserer en forsendelse. Må være utfylt
Fødselsnummer Fødselsnummer til brukeren som har lest forsendelsen. Ikke tomt og 11 siffer langt
navnPaEksterntSystem Navn til det eksterne systemet som håndterte lesingen av forsendelsen.
datoLest Dato og tidpunkt som forsendelsen ble lest på. Hvis blank settes den til nåtid.

retrieveForsendelseIdByEksternRef

Henter liste med forsendelseider som har denne eksternRef. Forsendelsene må være sendt av avsender som er innlogget.

Felt Beskrivelse Validering
EksternRef EksternRef, id som identifiserer forsendelsen hos avsender. Må være utfylt