Veiledning for avsender

Denne utviklerguiden hjelper deg med å komme i gang med å sende filer ved hjelp av Altinn Formidling.

Her finner du detaljerte API-operasjoner og hendelser som brukes ved filoverføring, inkludert operasjoner som initialisering av filoverføring, opplasting av filer og innhenting av filoverføringsstatus.

For mer informasjon, se vår swagger-side og GitHub-repo, som også inneholder en Bruno-pakke med eksempler.

Operasjon: Initialiser Filoverføring

Endepunkt: POST /broker/api/v1/filetransfer/

Denne operasjonen initialiserer en filoverføring, inkludert validering av grunnleggende metadata og autorisasjon hvis mottaker(e) spesifisert er gyldige.

Forespørsel: En instans av FileInitializeExt serialisert som JSON.

Return: HTTP 200 med GUID-en FileTransferID som er den unike ID-en brukt til å identifisere denne filoverføringen.

Utløste hendelser:

• Når fullført, blir hendelsen filetransferinitialized publisert til avsenderen, noe som indikerer at filoverføringen har blitt vellykket initialisert.

Eksempel: ‘File Transfer\Initialize’ i vår Bruno-pakke

Operasjon: Initialiser og last opp filoverføring

Endepunkt: POST /broker/api/v1/filetransfer/upload

Denne operasjonen initialiserer en filoverføring og laster opp filen i en og samme form-data operasjon. Merk at denne operasjonen er begrenset til 2GB filstørrelse, og ytelsen er dårligere enn om man initialiserer og laster opp i to forskjellige operasjoner via strømme-endepunktet.

Forespørsel: En instans av FileInitializeExt serialisert som form-data med filen i formfeltet “FileTransfer”.

Return: HTTP 200 med GUID-en FileTransferID som er den unike ID-en brukt til å identifisere denne filoverføringen.

Utløste hendelser:

• Når fullført, blir hendelsen filetransferinitialized publisert til avsenderen, noe som indikerer at filoverføringen har blitt vellykket initialisert.

Eksempel: ‘File Transfer\Initialize and upload (form-data)’ i vår Bruno-pakke

Operasjon: Last opp strømmet

Endepunkt: POST /broker/api/v1/filetransfer/{fileTransferId}/Upload

Last opp fildataene som en strøm ved hjelp av FileTransferId mottatt i InitialiserFileTransfer.

Forespørsel: FileTransferID spesifisert i URLen, og dataene som en strøm.

Return: HTTP 200 hvis vellykket fullført.

Utløste hendelser:

• Ved fullføring blir hendelsen uploadprocessing publisert, og en asynkron jobb vil kjøre for å sjekke fildataene for skadelig programvare.
• Når opplastingsbehandlingen har blitt vellykket fullført, blir hendelsen published publisert, og filen er tilgjengelig for nedlasting.
  • Hvis skadelig programvare ble oppdaget, blir hendelsen uploadfailed i stedet publisert.

Eksempel: ‘File Transfer{fileTransferId}\Upload’ i vår Bruno-pakke

Operasjon: Hent Filoverføringsoversikt

Endepunkt: GET /broker/api/v1/filetransfer/{fileTransferId}

Få en enkel oversikt over filoverføringen med gjeldende status og mottakerstatus.

Respons: En JSON-seralisert versjon av FileTransferOverviewExt

Utløste hendelser: ingen.

Eksempel: ‘File Transfer{fileTransferId}\Overview’ i vår Bruno-pakke

Operasjon: Hent Filoverføringsdetaljer

Endepunkt: GET /broker/api/v1/filetransfer/{fileTransferId}/details

Få en detaljert visning av filoverføringen, inkludert detaljerte filoverførings- og mottakerstatuser. Nyttig for feilsøking, men bør brukes sparsomt.

Forespørsel: FiletransferId spesifisert i URLen.

Respons: En JSON-seralisert versjon av FileTransferStatusDetailsExt

Utløste hendelser: ingen.

Eksempel: ‘File Transfer{fileTransferId}\Details’ i vår Bruno-pakke

Hendelse: no.altinn.broker.filetransferinitialized

Denne hendelsen utløses når initialiseringsoperasjonen har blitt fullført vellykket. Som Avsender kan du nå laste opp fildataene dine.

Hendelse: no.altinn.broker.uploadprocessing

Denne hendelsen utløses når opplastingsoperasjonen har blitt fullført vellykket, og fildataene venter på opplastingsbehandling. Frem til du mottar enten uploadfailed eller published, trenger ingen handlinger å utføres.

Hendelse: no.altinn.broker.uploadfailed

Denne hendelsen utløses hvis enten opplastings- eller opplastingsbehandlingsstegene mislykkes. Vi anbefaler deg å kalle get overview for å sjekke hvilke feilmeldinger som ble gitt.

Hendelse: no.altinn.broker.published

Denne hendelsen utløses når den asynkrone opplastingsprosessen har blitt fullført vellykket. Som avsender trenger du ikke å utføre noen ekstra handlinger.

Hendelse: no.altinn.broker.downloadconfirmed

Denne hendelsen utløses når en mottaker har bekreftet at nedlastingen har blitt fullført vellykket.

Hendelse: no.altinn.broker.allconfirmeddownloaded

Denne hendelsen utløses når alle mottakerne har bekreftet at nedlastingen har blitt fullført. Hvis FileTransfer har en enkelt mottaker, vil dette bli publisert samtidig som downloadconfirmed. Avhengig av innstillingene for formidlingstjenesten kan dette føre til at filen blir automatisk slettet.

Hendelse: no.altinn.broker.fileneverconfirmeddownloaded

Denne hendelsen utløses ved ExpiryTime for FileTransfer i tilfelle en eller flere mottakere ikke har bekreftet nedlastingen av filen. Dette kan indikere at enten mottakeren ikke var klar over FileTransfer eller at de har lastet ned, men unnlot å kalle ConfirmDownload. Denne hendelsen sendes også til mottaker(ne) som ikke har bekreftet nedlastingen.

Vi foreslår å bruke dataene som leveres i hent filoverførings detaljer for å undersøke hvilke handlinger mottakerne har utført på filoverføringen.

Hendelse: no.altinn.broker.filedpurged

Denne hendelsen utløses av filopprydningsprosessen ved Expiry av filen eller når alle mottakerne har bekreftet nedlastingen.

Etter dette punktet er fildataene ikke lenger tilgjengelige for nedlasting, selv om metadataene forblir.