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.
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. |
| retreiveForsendelseTyper | List<String> | Henter alle forsendelseTyper som kan brukes i SvarInn. | |
| retrieveMottakerSystemForOrgnr | organisasjonsnr | Liste med orgnr, forsendelseType, nivå, mottakersystem, mottakersystemid |
Henter alle konfigurerte mottakersystem for orgnr |
| 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. |
Definisjonsfil (WSDL) for tjenesten finnes her https://svarut.ks.no/tjenester/forsendelseservice/ForsendelsesServiceV9?wsdl
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 | 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. | |
| PostAdresse: | |||
| 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 | ||
| DigitalAdresse: | |||
| 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 | |
| DokumentType | Fritekstfelt som kan brukes til å fortelle noe om dokumentTypen til feltet. Kan brukes til noark4 dokumenttyper | ||
| EkskluderesFraPrint | Dette dokumentet blir ikke med i print av forsendelsen. Brukes til filer som kun er interesange ved digital levering. F.eks xml, video eller lyd filer | ||
| 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 | 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. | ||
| PostAdresse: | |||
| 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 | ||
| DigitalAdresse: | |||
| 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. | ||
| 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 | |
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:
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.
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 | |
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. | ||
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 | |
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.
| Felt | Beskrivelse | Validering | |
|---|---|---|---|
| Organisasjonsnr | Organisasjonsnr. | Må være utfylt | |
Du vil få tilbake en liste med:, orgnr, forsendelseType, nivå, mottakersystem, og mottakersystemid.
| Felt | Beskrivelse | |
|---|---|---|
| Orgnr | Organisasjonsnr. | |
| ForsendelseType | Forsendelsetypen dette systemet vil motta for, hvis null eller tom vil den kunne motta alle forsendelseTyper. | |
| Nivå | Hvilket forsendelsenivå dette mottakersystemet støtter. | |
| Mottakersystem | Navn på mottakersystem | |
| Mottakersystemid | Id for å identifiserere mottakersystem | |
Henter alle forsnedelseTyper som Svarinn mottakersystem kan konfigureres til å bruke.
Henter signeringshistorikk for en gitt forsendelse.
| Felt | Type | Beskrivelse | Validering |
|---|---|---|---|
| forsendelseid | String | Identifikator som unikt identifiserer en forsendelse. | Må være utfylt |
| Felt | Type | Beskrivelse | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| forsendelseid | String | Identifikator som unikt identifiserer en forsendelse. | ||||||||
| logg | List<Signeringslogg>
| Liste med logg-elementer | ||||||||
Samme som retrieveSigneringshistorikk bare for flere forsendelser i samme kall, opp til 10 forsendelser. Returnerer liste med signeringshistorikk.