Denne siden er ment for å gir en oversikt over de viktigste API-ene som bør eller kan være nyttig å bruke i et søknadssystem.

Oversikt og forklaring på variabler brukt på denne siden:

Instanser

En instans er en potensiell innsending av tjenesten. Instanser vil være tilgjengelig for instanseier fra de blir opprettet og helt til de eventuelt blir slettet.

PartyId

Hver bruker har en unik identifikator i altinn - instanceOwner.partyId

Denne kan man finne ved å kalle endepunktety /parties med aktuelt ID-porten token.

GET {miljø}/dibk/{app}/api/v1/parties
Headers: {Authorization: bearer [Exchanged ID-porten]}

 PartyId er en del av instans.id og tilgjengelig i instans objektet

Se aktive instanser

Dette endepunktet kan benyttes for å avgjøre om en ny instans av en app skal opprettes eller om det er mer hensiktsmessig å fortsette utfylling av en eksisterende instans.

https://docs.altinn.studio/nb/api/apps/instances/#get-active-instances

GET {miljø}/dibk/{app}/instances/{instanceOwner.PartyId}/active
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

Opprett instans

Hver innsending er en instans av en altinn 3 app.

https://docs.altinn.studio/api/apps/instances/

POST {miljø}/dibk/{app}/instances
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

Body:
{
    "appId": "dibk/{app}",
    "instanceOwner": {
        //"organisationNumber": "{organisationNumber}"
        //"personNumber": "{personNumber}"
    }
}

Multipart Request

Instanser kan og opprettes som multipart request der man laster opp data samtidig som man oppretter instansen

Body:
{
    "appId": "dibk/{app}",
    "instanceOwner": {
        //"organisationNumber": "{organisationNumber}"
        //"personNumber": "{personNumber}"
    }
    "{DataType.Id}": File
    "{DataType.Id}": File 
}

Se instans

Se informasjon om den aktuelle instansen.

GET {miljø}/dibk/{app}/instances/{instance.id}
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

Slett instans

https://docs.altinn.studio/nb/api/apps/instances/#delete-instance

Med tanke på sikkerhet bør data ikke lagres lenger enn nødvendig. Vi anbefaler derfor å rydde opp og slette instanser som ikke lenger er i bruk, enten fordi de er fullført eller ikke skal brukes mer. Sletting av instanser kan utføres både av instanseier og tjenesteeier. Dersom DiBK etablerer rutiner for sletting av instanser som tilsynelatende ikke er i bruk, vil dette bli dokumentert på de aktuelle tjenestenes egne sider.

DELETE {miljø}/dibk/{app}/instances/{instance.id}
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

Data elementer

Hver tjeneste har et sett med tillatte datatyper som kan være konfigurert på ulike måter.

Hvilke datatyper som finnes på den aktuelle appen, og hvordan de er konfigurert, finner man ved å kalle appen sitt API endepunkt:

GET {miljø}/dibk/{app}/applicationMetadata 

https://docs.altinn.studio/nb/api/models/app-metadata/#datatype

Når en instans blir validert, enten ved å kalle valideringsendepunktet på appen eller som en del av prosessen ved "process next", vil appen sjekke om innholdet i instansen samsvarer med konfigurasjonen. I tillegg vil enkelte ting sjekkes allerede ved opplasting av dataelementer.

Last opp data

https://docs.altinn.studio/api/apps/data-elements/#upload-data

PUT {miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}
Headers: {
          Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken],
          Content-Disposition: attachment; filename=data.xml,
          Content-Type: application/xml
         }
Binary File: data.xml 

Oppdater data

PUT {miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}
Headers: {
          Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken],
          Content-Disposition: attachment; filename=oppdatert.xml,
          Content-Type: application/xml
         }
Binary File: oppdatert.xml 

Se data

GET {miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

Slett data

DELETE {miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

Legg til metadata om vedlegg

PUT {miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}/user-defined-metadata
Headers: {Authorization: bearer [Exchanged ID-porten eller Maskinportentoken]}

Body: 
{
  "userDefinedMetadata": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

Se metadata på vedlegg

Du kan hente kun “User-defined-metadata”, men det vil og være synlig på dataelementet om man gjør en GET på instans

GET {miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}/user-defined-metadata
Headers: {Authorization: bearer [Exchanged ID-porten eller Maskinportentoken]}

Respons: 
{
  "userDefinedMetadata": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

PDF

Det blir produsert en PDF av både hovedskjemaet og eventuelle underskjemaer. Brukerne skal kunne hente en forhåndsvisning av PDF-en før signering, samt en signert versjon når søknaden er sendt inn og signert av brukeren.

Målet er å benytte Altinn3 sin løsning for PDF-generering, men da denne mangler noen nødvendige komponenter, oppfyller den ikke alle våre krav til PDF-produksjon.

Vi har derfor valgt å utvikle en egen PDF-løsning utenfor Altinn3 appen inntil videre, med planer om å migrere til Altinn sin løsning på et senere tidspunkt. Informasjon om hva som gjelder for den aktuelle tjenesten skal stå på egne dokumentasjonssider for tjenesten Altinn 3 Tjenester

Forskjellen på de to løsningene er i hovedsak hvilke endepunkt man bruker for å hente ut forhåndsvisning, og datatype man bruker for å hente den signert versjon

PDF produsert av Altinn3 appen

PDF-generering av hovedskjemaet er en innebygd funksjon i Altnn3-rammeverket, og vi ønsker å benytte denne funksjonaliteten. Om det er i bruk på den aktuelle tjenesten ser man dersom en datatype er konfigurert med "enablePdfCreation": true. Appen skal og være konfigurert med en datatype med id
ref-data-as-pdf.

 Eksempel: enablePdfCreation: true

 Eksempel ref-data-as-pdf

Forhåndsvisning

GET {miljø}/dibk/{app}/instances/{instance.id}/pdf/preview
Headers: {
          Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]
         }

Signert PDF

Den signerte PDF-en blir tilgjengelig som et dataelement på instansen, på datatypen ref-data-as-pdf

Den signerte PDF-en blir produsert etter at det er gjort en Altinn-signatur og appen har gått videre til prosessens slutt (process end). Den signerte PDF-en vil deretter være tilgjengelig på den aktuelle datatypen, og man kan gjøre en GET-forespørsel på dataelementet for å hente den.

GET {miljø}/dibk/{app}/instances/{instance.id}/data/{data.id} // Signert pdf
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

PDF produsert utenfor Altinn3 appen

Hver app konfigureres med hvilke datatyper det produseres PDF av, men denne informasjonen er ikke tilgjengelig i appens metadata da dette ikke er en del av Altinn-løsningen. Informasjonen skal i stedet være tilgjengelig på egne dokumentasjonssider for den aktuelle tjenesten.

Forhåndsvisning

Man kan få en forhåndsvisning av PDF-en ved å kalle pdfpreview på enten instansen eller på det aktuelle dataelementet.

Forhåndsvisning på instansen:

Ved å kalle pdfpreview på instansen, vil du få en PDF-forhåndsvisning med data på den datatypen som er konfigurert som hovedskjemaet for appen.

GET {miljø}/dibk/{app}/instances/{instance.id}/pdfpreview
Headers: {
          Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]
         }

Forhåndsvisning på dataelement: Ved å kalle pdfpreview på et dataelement, vil du få en PDF-forhåndsvisning med data på det aktuelle dataelementet, dersom datatypen er konfigurert for PDF-generering.

GET {miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}/pdfpreview
Headers: {
          Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]
         }

Signert PDF

Den signerte PDF-en blir tilgjengelig som et dataelement på instansen. Datatypen som brukes vil være konfigurert forskjellig i de ulike appene, så informasjon om dette vil være tilgjengelig på egne dokumentasjonssider for den aktuelle tjenesten.

Den signerte PDF-en blir produsert etter at det er gjort en Altinn-signatur og appen har gått videre til prosessens slutt (process end). Den signerte PDF-en vil deretter være tilgjengelig på den aktuelle datatypen, og man kan gjøre en GET-forespørsel på dataelementet for å hente den.

GET {miljø}/dibk/{app}/instances/{instance.id}/data/{data.id} // Signert pdf
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

Altinn-signering

Signering er en prosessoppgave i Altinn https://docs.altinn.studio//nb/altinn-studio/reference/process/actions/process-actions/#sign.

Signering utføres på følgende måte:

PUT {miljø}/dibk/{app}/instances/{instance.id}/process/next
Headers: {Authorization: bearer [Exchanged ID-porten]}

Body: { "action":"sign" }

Validering

https://docs.altinn.studio/nb/api/apps/validation/

Validering skjer som en del av prosessflyten i Altinn-appen, men kan også kalles direkte på instansen eller på dataelementer.

• Instansvalidering: Denne valideringen sjekker at instansen samsvarer med konfigurasjonen av datatyper i appen og kjører ekstra valideringer som er lagt til på enkelte datatyper.

• Dataelementvalidering: For dataelementer som er av datatypene for hovedskjema og underskjema, har vi koblet på validering fra FtPB valideringstjeneste. Dette betyr at de samme valideringene som er tilgjengelige for pre-validering også blir kjørt her.

Responsen fra Altinn-appen vil være forskjellig fra responsen fra FtPB valideringstjeneste . Derfor lagrer vi responsen fra FtPB valideringstjenesten i en datatype som vi kaller Valideringsrapport, som kan hentes ved behov. Denne rapporten vil også bli sendt videre ved innsending av søknaden.

Vi anser ikke responsen fra Altinn som mangelfull, så det er fullt mulig å bruke denne responsen i stedet.

Pre-validering til FtPB valideringstjenesten er et tilbud som kan benyttes hvis det passer best inn i prosessflyten for det aktuelle søknadssystemet. Den samme pre-valideringen kan utføres ved å kalle appens valideringsendepunkter etter man har opprettet en instans og lastet opp data.

Dataelementvalidering

https://docs.altinn.studio//nb/api/apps/validation/#validate-stored-data

GET {miljø}/dibk/{app}/instances/{instance.id}/data/{data.id}/validate
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

Endepunktet returnerer en liste med ValidationIssues, og det vil bli lagret en valideringsrapport på datatypen Valideringsrapport.

Filnavnet vil være Valideringsrapport-{datatype.id}-{dataElement.Id}.xml. Hvis det gjøres flere valideringer på samme dataelement, vil rapporten bli overskrevet.

Ved validering av et nytt dataelement av samme datatype, genereres en ny valideringsrapport.

Instansvalidering

https://docs.altinn.studio//nb/api/apps/validation/#validate-stored-instance

GET {miljø}/dibk/{app}/instances/{instance.id}/validate
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

Endepunktet returnerer en liste med ValidationIssues basert på appen og dens konfigurasjon. I tillegg utføres alle relevante valideringer på alle dataelementer som er konfigurert for validering.

Mapping fra FtPB til Altinn sitt valideringsresultat

Fullfør innsending

https://docs.altinn.studio/nb/api/apps/process/#complete-the-process

Når instansen er satt til "process complete", blir data hentet og videresendt av FtPB arbeidsflyt.

Dette kan gjøres ved å kalle completeProcess eller process next når man står på siste steg.

PUT {miljø}/dibk/{app}/instances/{instance.id}/process/completeProcess
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

Hvilke steg en app er i, ser man ved å gjøre en GET på instansen og se på innholdet i Process

GET {miljø}/dibk/{app}/instances/{instance.id}
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}

Instance complete

Når tjenesteeier (DiBK) har hentet data og data er levert, setter de kaller de "complete" . Det betyr at tjenesteeier er ferdig og ikke lenger har bruk for dataene i instansen. Det samme kan instanseier (sluttbruker) gjøre når de er ferdig. Når både tjenesteeier og instanseier har gjort dette, vil altinn slette instansen og alle data knyttet til den.

POST {basePath}/{instanceOwnerPartyId}/{instanceGuid}/complete 
Headers: {Authorization: bearer [Exchanged ID-porten- eller Maskinportentoken]}