ITU/UTT for distributører

Innledning

Brønnøysundregistrene tilbyr en begrenset, standardisert maskin-til-maskin-tjeneste (API) som kan benyttes av eksterne partnere for innsyn i utleggsdata fra Løsøregisteret.

Denne dokumentasjonen viser hvordan eksterne systemer kan integrere seg mot APIet, og hvordan man benytter seg av tjenesten for å hente data.

Syntetiske testdata

Vi har en Excel-fil med syntetiske testdata for personer/virksomheter som det er registrert saker på i tjenestens testmiljø. Alt er oppkonstruert, både personer, virksomheter og saker. Merk at avvik mellom filen og respons fra tjenesten kan forekomme over tid, ettersom tjenesten oppdateres fortløpende.

API-referanse

Denne tjenesten tilbyr opplysninger om:

• Intet til utlegg og utleggstrekk på fødselsnummer/d-nummer
• Intet til utlegg på organisasjonsnummer

Swagger-dokumentasjon (last ned Swagger-UI og utforsk linken)

Sikkerhetsmekanismer

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

For å kunne få tilgang til våre begrensede API er det tre forutsetninger.

1. Virksomhetssertifikat
2. Registrert klient hos Maskinporten.
3. JWT-token fra Maskinporten mot scopet brreg:losore/utlegg

Tokenet som hentes fra Maskinporten må bli sendt som autorisasjonstoken (Bearer token) når et kall mot Løsøreregisteret blir utført.

Se veiledning for integrasjon mot Maskinporten.

Regelverk: Hjemler for tilgjengeliggjøring av data fra Brønnøysundregistrene.

Grensesnittbeskrivelse

Domener:

• For testmiljø (ppe): https://losoreregisteret.ppe.brreg.no
• For prod: https://losoreregisteret.brreg.no

Oppslag på fødselsnummer/d-nummer

Beskrivelse

Tjenesten tar imot en forespørsel om oppslag på et fødselsnummer eller d-nummer, forespørselen valideres før utførelsen og returnerer opplysninger om kun aktive intet til utlegg og utleggstrekk på fødselsnummer eller d-nummer.

Request

Tar i mot et fødselsnummer eller d-nummer som del av URL, med obligatorisk path-parameter sokers_orgnummer som inneholder organisasjonsnummeret til sluttbruker som oppslaget gjøres på vegne av.

Validering

• Maskinport-tokenet som blir sendt inn er knyttet til avtalepartens orgnummer, og dette orgnummeret skal være gyldig samt ha en gyldig avtale om å kunne hente ut utlegg.
• Forespørselen skal alltid inneholde fødselsnummer eller d-nummer på den det gjøres oppslag på.
• Dersom forespørselen inneholder et fødselsnummer eller d-nummer som ikke er lovlig oppbygd, returneres det en feilmelding.
• Forespørselen skal alltid inneholde organisasjonsnummeret til sluttbruker/den som gjør oppslag.
• Det sjekkes at sluttbrukers organisasjonsnummer er registrert og ikke slettet i Enhetsregisteret. Dersom det ikke er registrert, eller er slettet, returneres det en feilmelding.

Response

Dersom kallet lykkes får man HTTP-status 200 og data fra tjenesten på JSON-format, i form av et JSON-objekt som inneholder opplysninger om intet til utlegg og utleggstrekk.

Eksempelrespons for oppslag på fødselsnummer/d-nummer

{
    "utleggResponseDistributor": {
        "antallITU": 1,
        "antallUTT": 2,
        "utlegg": [
            {
                "utleggstype": "ITU",
                "avholdtForretning": "2018-09-04",
                "innfortILosoreregisteret": "2018-09-04"
            },
            {
                "utleggstype": "UTT",
                "avholdtForretning": "2018-07-30",
                "innfortILosoreregisteret": "2018-08-01",
                "trekkbelop": 500.00,
                "trekkvaluta": "NOK",
                "periodeStart": "2018-08-01",
                "periodeSlutt": "2020-08-10"
            },
            {
                "utleggstype": "UTT",
                "avholdtForretning": "2018-06-10",
                "innfortILosoreregisteret": "2018-08-08",
                "trekkprosent": 17.0,
                "periodeStart": "2018-07-13",
                "periodeSlutt": "2020-07-13"
            }
        ],
        "meldinger": [],
        "tilleggsinfo": ""
    }
}

Oppslag på organisasjonsnummer

Beskrivelse

Tjenesten tar imot en forespørsel om oppslag på et organisasjonsnummer, forespørselen valideres før utførelsen og returnerer opplysninger om kun aktive intet til utlegg på organisasjonsnummeret.

Request

Tar i mot et organisasjonsnummer som del av URL, med obligatorisk path-parameter sokers_orgnummer som inneholder organisasjonsnummeret til sluttbruker som oppslaget gjøres på vegne av.

Validering

• Maskinport-tokenet som blir sendt inn er knyttet til avtalepartens orgnummer, skal være gyldig, samt ha en gyldig avtale om å kunne hente ut utlegg.
• Forespørselen skal alltid inneholde organisasjonsnummer på det foretaket det gjøres oppslag mot.
• Dersom forespørselen inneholder et organisasjonsnummer som ikke er lovlig oppbygd, returneres det en feilmelding.
• Forespørselen skal alltid inneholde organisasjonsnummeret til sluttbruker/den som gjør oppslag.
• Det sjekkes at sluttbrukers organisasjonsnummer er registrert og ikke slettet i Enhetsregisteret. Dersom det ikke er registrert, eller er slettet, returneres det en feilmelding.

Response

Dersom kallet lykkes får man HTTP-status 200 og data fra tjenesten på JSON-format, i form av et JSON-objekt som inneholder opplysninger om intet til utlegg.

Eksempelrespons for oppslag på organisasjonsnummer

{
  "utleggResponseDistributor": {
    "antallITU": 1,
    "antallUTT": 1,
    "utlegg": [
      {
        "utleggstype": "ITU",
        "avholdtForretning": "2020-01-10",
        "innfortILosoreregisteret": "2020-01-16"
      },
      {
        "utleggstype": "UTT",
        "avholdtForretning": "2021-08-25",
        "innfortILosoreregisteret": "2021-08-31",
        "trekkbelop": 43022.00,
        "trekkvaluta": "NOK",
        "periodeStart": "2021-08-25",
        "periodeSlutt": "2023-08-25"
      }
    ],
    "meldinger": [],
    "tilleggsinfo": ""
  }
}

Eksempelrespons for oppslag på slettet organisasjonsnummer

{
  "utleggResponseDistributor": {
    "antallITU": 1,
    "antallUTT": 0,
    "utlegg": [
      {
        "utleggstype": "ITU",
        "avholdtForretning": "2019-09-02",
        "innfortILosoreregisteret": "2020-08-13"
      }
    ],
    "meldinger": [],
    "tilleggsinfo": "Organisasjonsnummer er slettet"
  }
}

Feilmeldinger

Dersom det ikke finnes noen utlegg, eller ved ugyldig input, vil det gis melding om dette i JSON-responsen. Dette ligger i form av en array meldinger.

Eksempelrespons uten utlegg

{
  "antallITU": 0,
  "antallUTT": 0,
  "utlegg": [],
  "meldinger": [
    "Det er ikke registrert opplysninger om intet til utlegg på dette fødselsnummeret/d-nummeret",
    "Det er ikke registrert opplysninger om utleggstrekk på dette fødselsnummeret/d-nummeret"
  ],
  "tilleggsinfo": ""
}

Eksempelrespons feilmelding

{
    "feilId": "7d10f7d9-e2a3-4ab6-9ee2-90ccbf12eeef",
    "feilkode": "UAE_002",
    "feiltype": "VALIDERING",
    "beskrivelse": "Feil innhold i request",
    "detaljer": "Ugyldig fødselsnummer/d-nummer"
}

Dersom man ikke får HTTP-status 200, så får man en melding fra tjenesten i JSON-format.

HTTP-statuskoder

Oversikt over HTTP-statuskoder i APIet.

Ordliste

Definisjoner på begrep som er brukt i denne dokumentasjonen.