Uthenting av meldinger

Innledning

Brønnøysundregistrenes elektroniske mottak har et REST-grensesnitt som kan benyttes av eksterne parter for innsending av meldinger.

Sikkerhetsmekanismer

Siden dette er begrensede API så skal kallende parter autentiseres gjennom Maskinporten.

For å kunne få tilgang til våre begrensede APIer må man bruke et JWT-token fra Maskinporten med scopet brreg:mottak

Access-tokenet oppgis i headeren Authorization. Husk Bearer før tokenet.

HeaderVerdi
AuthorizationBearer

Bruksanvisning

For å kunne hente ut meldinger så skal man ta til bruk alle tre av endepunktene beskrevet på denne siden. Flyten er beskrevet under:

  1. Se tilgjengelig filer via outbound/available
    • Her ser man alle filene knyttet til bedriften. Dette finner vi gjennom orgnummer i tokenet som blir brukt.
  2. Last ned filene via outbound/download
    • Her bruker man opplysninger fra filene man fikk i responsen fra kallet mot outbound/available for å laste ned riktig.
  3. Godkjenn at filene er nedlastet via outbound/confirm når man har lastet ned filen.
    • Dette fjerner filen fra å dukke opp i outbound/available kallet.

Grensesnittbeskrivelse

Swagger

Tjenesten benytter seg av standard HTTP GET og POST.

HTTP-metodeURLContent-typeBeskrivelse
GEThttps://mottak.brreg.no/outbound/availableapplication/jsonLister ut tilgjengelige meldinger (med mottakId) for organisasjonsnummer oppgitt i JWT tokenet. Kan filtreres på tjeneste og dato
GEThttps://mottak.brreg.no/outbound/downloadapplication/octet-streamLaster ned forsendelse med oppgitt mottakId
PUThttps://mottak.brreg.no/outbound/confirmapplication/jsonBekrefter at forsendelse med oppgitt mottakId er lastet ned av klient

available

Eksempel /available?tjeneste={tjeneste}&fraDato={fraDato}&tilDato={tilDato}

Endepunktet returnerer tilgjengelige forsendelser for organisasjonsnummer som er oppgitt i JWT-tokenet.

Man kan filtrere resultatene på disse parametrene hvis man ønsker

parametertypepåkrevd
tjenestestringnei
fraDatoLocalDatenei
tilDatoLocalDatenei

Response

Ved 200 OK:

[
  {
  "mottakId":"be935814-c7a3-4a9f-8bbc-ac278cbe41d5",
  "status":"ready",
  "oppdatert":"2019-09-05T09:43:51.691"
  }
]

download

Eksempel /download?mottakId={mottakId}

Endepunktet returnerer ZIP-fil med Melding for angitt mottakId

Parametre

parametertypepåkrevd
mottakIdUUIDja

Response

Bytestream som APPLICATION_OCTET_STREAM

confirm

Eksempel /confirm?mottakId={mottakId}

Endepunktet bekrefter forsendelsen med angitt mottakId som nedlastet. Denne forsendelsen vil da ikke lenger fremkomme ved kall til /available-endepunktet.

Parametre

parametertypepåkrevd
mottakIdUUIDja

Response

200 OK ved success.

Feilmeldinger

HTTP-kodeApplikasjonsfeilkodeFeilmelding
500 Internal Server ErrorERROR-00005Optimistic lock exception. Hvis samme forsendelseinfo blir forsøkt confirmed nedlastet samtidig kan dette skje. I utgangspunktet kan man se bort i fra denne, men å forhindre dette er klientens ansvar.

Disse kommer på JSON-formatet:

{
  "feilId":"72577aa8-0ba1-4424-a310-fd9671547953",
  "mottakId":"fe7234ec-b51f-47d1-a414-5b17123118b3",
  "kilde":"maskinport-agent",
  "feilkode":"ERROR-00005",
  "beskrivelse": "Simultaneous attempt to confirm same file"
}

I tillegg kommer 401 - Unauthorized ved mangler på Bearer token.

HTTP-kodeheaderHeader-valueForklaring
401 - UnauthorizedWWW-AuthenticateBearer realm=“unspecified”, error=“unauthorized”, error_description=“Full authentication is required to access this resource”JWT access token ikke oppgitt i Authorization header i request.
401 - UnauthorizedWWW-AuthenticateBearer realm=“unspecified”, error=“invalid_token”, error_description=“invalid bearer token or wrong scope for bearer token”JWT access token er oppgitt, men det er enten ugyldig (utgått, korrupt eller gjeldende for et annet scope en tjenesten krever).

Testmiljø

URL mot PPE-testmiljø er https://mottak.ppe.brreg.no/outbound