ITU/UTT for kredittopplysningsforetak

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 vil forekomme over tid, ettersom tjenesten oppdateres fortløpende.

API-referanse

Denne tjenesten tilbyr opplysninger om:

  • Intet til utlegg og utleggstrekk for fødselsnummer/d-nummer
  • Endringslogg for utleggsdata
  • Totalbestand for utleggsdata

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

HTTP-metodeURLBeskrivelse
GEThttps://{domene}/utlegg/personer-utvidet/{fnr/dnr}Hent detaljerte opplysninger om intet til utlegg og utleggstrekk for et fødselsnummer/d-nummer.
GEThttps://{domene}/utlegg/endringslogg/{timestamp}Hent endringslogg (alle endringer i intet til utlegg og utleggstrekk) for alle fødselsnummer/d-nummer og organisasjonsnummer
GEThttps://{domene}/utlegg/endringslogg/enheter/{timestamp}Hent endringslogg (alle endringer i intet til utlegg) for alle organisasjonsnummer etter timestamp.
GEThttps://{domene}/utlegg/totalbestand/{timestamp}Hent totalbestand (alle aktive intet til utlegg og utleggstrekk) for alle fødselsnummer/d-nummer og organisasjonsnummer
GEThttps://{domene}/utlegg/totalbestand/enheter/{timestamp}Hent totalbestand (alle aktive intet til utlegg) for alle organisasjonsnummer

Domener:

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

Oppslag på fødselsnummer eller 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.

Validering

  • Maskinport-tokenet som blir sendt inn er knyttet til avtalepart sitt 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.

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. Der aktør er person vil responsen inneholde navn på vedkommende.

Eksempelrespons for oppslag på fødselsnummer eller d-nummer
{
  "utleggResponseKredittforetak": {
    "antallITU": 1,
    "antallUTT": 1,
    "utlegg": [
      {
        "ubnr": 20202000000006,
        "ubmeldnr": 1,
        "utleggstype": "ITU",
        "avholdtForretning": "2020-01-10",
        "innfortILosoreregisteret": "2020-01-16",
        "aktorer": [
          {
            "rolletype": "Saksøkt",
            "personidentifikator": "52125501648",
            "fornavn": "GRETE",
            "etternavn": "KASPERSEN"
          },
          {
            "rolletype": "Namsmyndighet",
            "organisasjonsnummer": "810304642",
            "saksnummer": "1"
          },
          {
            "rolletype": "Saksøker",
            "organisasjonsnummer": "810305282"
          },
          {
            "rolletype": "Prosessfullmektig",
            "organisasjonsnummer": "810305002",
            "referansenummer": "1"
          }
        ]
      },
      {
        "ubnr": 20202000000256,
        "ubmeldnr": 1,
        "utleggstype": "UTT",
        "avholdtForretning": "2021-08-25",
        "innfortILosoreregisteret": "2021-08-31",
        "trekkbelop": 43022.00,
        "trekkvaluta": "NOK",
        "periodeStart": "2021-08-25",
        "periodeSlutt": "2023-08-25",
        "aktorer": [
          {
            "rolletype": "Saksøkt",
            "personidentifikator": "52125501648",
            "fornavn": "GRETE",
            "etternavn": "KASPERSEN"
          },
          {
            "rolletype": "Namsmyndighet",
            "organisasjonsnummer": "810304642",
            "saksnummer": "1"
          },
          {
            "rolletype": "Saksøker",
            "organisasjonsnummer": "810305282"
          },
          {
            "rolletype": "Prosessfullmektig",
            "organisasjonsnummer": "810305002",
            "referansenummer": "1"
          }
        ]
      }
    ],
    "meldinger": [],
    "tilleggsinfo": ""
  }
}

Endringslogg: Oppslag på endringer for alle fødselsnummer/d-nummer og organisasjonsnummer

Beskrivelse

Tjenesten tar imot en forespørsel hvor det er oppgitt et timestamp (yyyy-MM-dd'T'HH:mm:ss.SSS), og returnerer alle endringer som er registrert kronologisk etter oppgitt timestamp.

Responsen er paginert, og inneholder metadata om bl.a. timestamp for siste element i responsen, slik at man kan bruke dette som input til å hente neste side med resultater ved å bruke verdien fra feltet datoSistEndret fra forrige respons som spørreparameter.

Maksimalt antall meldinger som returneres per forespørsel er 1000, og dette regnes som én side med resultater. Dette vil ofte ikke gi alle endringer på en dag, men lenke til neste side leveres i responsen så lenge det er flere sider.

Dersom timestamp i forespørselen er eldre enn 45 dager, returneres det en feilmelding.

Request

Tar i mot en forespørsel hvor det er oppgitt et timestamp som del av URL.

Response

Dersom kallet lykkes får man HTTP-status 200 og data fra tjenesten på JSON-format. Tjenesten tilbyr to endepunkt som inneholder opplysninger om henholdsvis:

  1. Intet til utlegg og utleggstrekk for fødselsnummer/d-nummer og organisasjonsnummer
  2. Intet til utlegg for organisasjonsnummer.

Siste timestamp returneres som en del av responsen, slik at dette kan benyttes for å kontrollere om man har fått alt, samt som input i neste forespørsel.

Eksempelrespons for Endringslogg: Oppslag på endringer for alle fødselsnummer/d-nummer og organisasjonsnummer
{
  "endringsloggResponseKredittforetak": {
    "antallITU": 3,
    "antallUTT": 3,
    "datoSistEndret": "2022-04-08T15:10:16.277149",
    "endringslogg": [
      {
        "ubnr": 20293000009140,
        "ubmeldnr": 19,
        "utleggstype": "UTT",
        "avholdtForretning": "2020-03-30",
        "innfortILosoreregisteret": "2022-04-08",
        "trekkbelop": 2500.00,
        "trekkvaluta": "NOK",
        "periodeStart": "2020-03-31",
        "periodeSlutt": "2024-07-13",
        "aktorer": [
          {
            "rolletype": "Saksøkt",
            "personidentifikator": "04021850530"
          },
          {
            "rolletype": "Namsmyndighet",
            "organisasjonsnummer": "810843012",
            "saksnummer": "1"
          },
          {
            "rolletype": "Saksøker",
            "organisasjonsnummer": "810844442"
          },
          {
            "rolletype": "Prosessfullmektig",
            "organisasjonsnummer": "810843942",
            "referansenummer": "2"
          }
        ]
      },
      {
        "ubnr": 20293000009139,
        "ubmeldnr": 19,
        "utleggstype": "ITU",
        "avholdtForretning": "2020-03-30",
        "innfortILosoreregisteret": "2022-04-08",
        "aktorer": [
          {
            "rolletype": "Saksøkt",
            "personidentifikator": "04021850530"
          },
          {
            "rolletype": "Namsmyndighet",
            "organisasjonsnummer": "810843012",
            "saksnummer": "1"
          },
          {
            "rolletype": "Saksøker",
            "organisasjonsnummer": "810844442"
          },
          {
            "rolletype": "Prosessfullmektig",
            "organisasjonsnummer": "810843942",
            "referansenummer": "1"
          }
        ]
      },
      {
        "ubnr": 20293000009139,
        "ubmeldnr": 20,
        "utleggstype": "ITU",
        "avholdtForretning": "2020-03-30",
        "innfortILosoreregisteret": "2022-04-08",
        "aktorer": [
          {
            "rolletype": "Saksøkt",
            "personidentifikator": "04021850530"
          },
          {
            "rolletype": "Namsmyndighet",
            "organisasjonsnummer": "810843012",
            "saksnummer": "1"
          },
          {
            "rolletype": "Saksøker",
            "organisasjonsnummer": "810844442"
          },
          {
            "rolletype": "Prosessfullmektig",
            "organisasjonsnummer": "810843942",
            "referansenummer": "1"
          }
        ]
      },
      {
        "ubnr": 20293000009140,
        "ubmeldnr": 20,
        "utleggstype": "UTT",
        "avholdtForretning": "2020-03-30",
        "innfortILosoreregisteret": "2022-04-08",
        "trekkbelop": 2500.00,
        "trekkvaluta": "NOK",
        "periodeStart": "2020-03-31",
        "periodeSlutt": "2024-07-13",
        "aktorer": [
          {
            "rolletype": "Saksøkt",
            "personidentifikator": "04021850530"
          },
          {
            "rolletype": "Namsmyndighet",
            "organisasjonsnummer": "810843012",
            "saksnummer": "1"
          },
          {
            "rolletype": "Saksøker",
            "organisasjonsnummer": "810844442"
          },
          {
            "rolletype": "Prosessfullmektig",
            "organisasjonsnummer": "810843942",
            "referansenummer": "2"
          }
        ]
      },
      {
        "ubnr": 20293000009139,
        "ubmeldnr": 21,
        "utleggstype": "ITU",
        "avholdtForretning": "2020-03-30",
        "innfortILosoreregisteret": "2022-04-08",
        "aktorer": [
          {
            "rolletype": "Saksøkt",
            "personidentifikator": "04021850530"
          },
          {
            "rolletype": "Namsmyndighet",
            "organisasjonsnummer": "810843012",
            "saksnummer": "1"
          },
          {
            "rolletype": "Saksøker",
            "organisasjonsnummer": "810844442"
          },
          {
            "rolletype": "Prosessfullmektig",
            "organisasjonsnummer": "810843942",
            "referansenummer": "1"
          }
        ]
      },
      {
        "ubnr": 20293000009140,
        "ubmeldnr": 21,
        "utleggstype": "UTT",
        "avholdtForretning": "2020-03-30",
        "innfortILosoreregisteret": "2022-04-08",
        "trekkbelop": 2500.00,
        "trekkvaluta": "NOK",
        "periodeStart": "2020-03-31",
        "periodeSlutt": "2024-07-13",
        "aktorer": [
          {
            "rolletype": "Saksøkt",
            "personidentifikator": "04021850530"
          },
          {
            "rolletype": "Namsmyndighet",
            "organisasjonsnummer": "810843012",
            "saksnummer": "1"
          },
          {
            "rolletype": "Saksøker",
            "organisasjonsnummer": "810844442"
          },
          {
            "rolletype": "Prosessfullmektig",
            "organisasjonsnummer": "810843942",
            "referansenummer": "2"
          }
        ]
      }
    ],
    "meldinger": [],
    "tilleggsinfo": ""
  }
}

Totalbestand: Oppslag på alle aktive utlegg for fødselsnummer/d-nummer og organisasjonsnummer

Beskrivelse

Tjenesten tar imot en forespørsel hvor det er oppgitt et timestamp (yyyy-MM-dd'T'HH:mm:ss.SSS), og returnerer alle aktive utlegg som er registrert kronologisk etter oppgitt timestamp, som er eldre enn to dager gamle. Responsen er paginert, og inneholder metadata om bl.a. timestamp for siste element i responsen, slik at man kan bruke dette som input til å hente neste side med resultater, eller ved overgang til å konsumere endringslogg-endepunktet for å få de nyeste elementene.

Maksimalt antall meldinger som returneres per forespørsel er 1000, og dette regnes som én side med resultater. Dette vil ikke være hele totalbestanden, men lenke til neste side leveres i responsen så lenge det er flere sider.

Request

Tar i mot en forespørsel hvor det oppgis et timestamp som del av URL.

Tjenesten kalles initielt uten timestamp for å få de første 1000 elementene, og for å iterativt hente neste side med resultater bruker man verdien fra feltet datoSistEndret fra forrige respons som spørreparameter. Alternativt kan man benytte lenken til neste side som returneres som eget felt.

Response

Dersom kallet lykkes får man HTTP-status 200 og data fra tjenesten på JSON-format. Tjenesten tilbyr to endepunkt som inneholder opplysninger om henholdsvis:

  1. Intet til utlegg og utleggstrekk for fødselsnummer/d-nummer og organisasjonsnummer,
  2. Intet til utlegg for organisasjonsnummer.

Siste timestamp er en del av responsen.

Eksempelrespons for Totalbestand: Oppslag på alle aktive utlegg for fødselsnummer/d-nummer og organisasjonsnummer
{
  "totalbestandResponseKredittforetak": {
    "antallITU": 1,
    "antallUTT": 1,
    "datoSistEndret": "2022-04-08T15:10:16.277149",
    "totalbestand": [
      {
        "ubnr": 20293000009139,
        "ubmeldnr": 21,
        "utleggstype": "ITU",
        "avholdtForretning": "2020-03-30",
        "innfortILosoreregisteret": "2022-04-08",
        "aktorer": [
          {
            "rolletype": "Saksøkt",
            "personidentifikator": "04021850530"
          },
          {
            "rolletype": "Namsmyndighet",
            "organisasjonsnummer": "810843012",
            "saksnummer": "1"
          },
          {
            "rolletype": "Saksøker",
            "organisasjonsnummer": "810844442"
          },
          {
            "rolletype": "Prosessfullmektig",
            "organisasjonsnummer": "810843942",
            "referansenummer": "1"
          }
        ]
      },
      {
        "ubnr": 20293000009140,
        "ubmeldnr": 21,
        "utleggstype": "UTT",
        "avholdtForretning": "2020-03-30",
        "innfortILosoreregisteret": "2022-04-08",
        "trekkbelop": 2500.00,
        "trekkvaluta": "NOK",
        "periodeStart": "2020-03-31",
        "periodeSlutt": "2024-07-13",
        "aktorer": [
          {
            "rolletype": "Saksøkt",
            "personidentifikator": "04021850530"
          },
          {
            "rolletype": "Namsmyndighet",
            "organisasjonsnummer": "810843012",
            "saksnummer": "1"
          },
          {
            "rolletype": "Saksøker",
            "organisasjonsnummer": "810844442"
          },
          {
            "rolletype": "Prosessfullmektig",
            "organisasjonsnummer": "810843942",
            "referansenummer": "2"
          }
        ]
      }
    ],
    "meldinger": [],
    "tilleggsinfo": ""
  }
}

Timestamp rundt sommer/vintertid

Warning Sign Timestamps som lagres i databasen er omgjort fra tidssonen man er i når det lagres til UTC, og så omgjort tilbake til tidssonen man er i under uthenting på veien ut igjen. Dette vil føre til noen gotchas rundt overgangen sommer(UTC +2) og vinter(UTC +1) tid, begge veier.

NB: Dette gjelder ikke kun i de tilfellene der man spør rett rundt overgangen (minuttet før og så minuttet etter), men i alle tilfeller der man har hentet ut data før overgangen og neste query blir gjort etter overgangen. Uavhengig av hvor lenge før og etter.

Det man må gjøre er å “huske” hvilken tidssone man gjorde forrige request i og så justere basert på hvilken tidssone man er i når man gjør neste request. Og generelt holde seg unna å gjøre request rundt en time før/etter overgangen, for å hindre at den justeringen man gjør treffer på feil side av overgangen.

F.eks:

Man gjør et oppslag rett før overgangen sommer til vintertid. Dette gir f.eks. ut et resultset hvor neste page har timestamp 2020-10-25T02:59:00.000 (Som er lagret som 2020-10-25T00:59:00.000 og så justert til sommertid på veien opp). Så gjør man neste query rett etter overgangen til vintertid. Da vil 2020-10-25T02:59:00.000 justeres til UTC basert på vintertid og man leter i databasen etter timestamp 2020-10-25T01:59:00.000 Dette vil derfor føre til at man går glipp av alle innslag som er registrert mellom 2020-10-25T00:59:00.000 og 2020-10-25T01:59:00.000 i databasen.

Eksempler:

OvergangLagret i databasen (UTC)Det man får utBlir justert til i neste søk etter overgang (UTC)FeilTimestamp-justering man må bruke
Sommer til vinter2020-10-25T00:59:00.0002020-10-25T02:59:00.000 (UTC +2)2020-10-25T01:59:00.000 (Trekker fra 1 time pga nå UTC +1)Hopper over en time med innslag2020-10-25T01:59:00.000
Vinter til sommer2020-03-29T00:59:00.0002020-03-29T01:59:00.000 (UTC +1)2020-03-28T23:59:00.000 (Trekker fra 2 timer pga nå UTC +2)Får med innslag man allerede har hentet ut2020-03-29T02:59:00.000

Feilmeldinger

Dersom det ikke finnes noen ITU/UTT, 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-kodeFeilmelding
400Ugyldig fødselsnummer/d-nummer
400Ugyldig timestamp oppgitt
403Forespørsel inneholder ingen gyldig bearer token
404Fødselsnummer/d-nummer mangler
404Timestamp-parameter til Endringslogg er eldre enn 45 dager
404Fant ingen meldinger som er eldre enn oppgitt timestamp

HTTP-statuskoder

Oversikt over HTTP-statuskoder i APIet.

HTTP-kodeBeskrivelse
200 OKHenting av data gikk bra
400 Bad RequestFeil i spørring. Applikasjonen vil gi en detaljert feilmelding for hva som er feil med spørring
403 ForbiddenFeil ved autentisering eller autorisering. Bearer tokenet som ble sendt inn er ikke gyldig eller har ikke en gyldig avtale om utlegg
404 Not FoundApplikasjonen vil gi en detaljert feilmelding for hva som ikke ble funnet. Kan også bety at man bruker feil adresse for tjenesten (i så fall vil man få en standard “404 NOT FOUND” og ikke et svar fra applikasjonen)
500 Internal Server ErrorFeil på server side, for eksempel at en underliggende datakilde ikke svarer

Ordliste

Definisjoner på begrep som er brukt i denne dokumentasjonen.

BegrepDefinisjon
APIProgrammeringsgrensesnitt
HTTPDatakommunikasjonsstandard
HTTP-statuskoderStatuskoder for datakommunikasjonsstandard
RESTDatakommunikasjonmønster
JSONÅpen standard for dataformat
D-nummerIdentifikasjonsnummer tildeles personer med midlertidig tilknytning til Norge, det vil si som ikke er bosatt i Norge. Består av en modifisert sekssifret fødselsdato og et femsifret personnummer. Fødselsdatoen modifiseres ved at det legges til 4 på det første sifferet.
FødselsnummerIdentifikasjonsnummer fra folkeregistret og består av 11 siffer
PersonidentifikatorFødselsnummer eller d-nummer
OrganisasjonsnummerIdentifikasjonsnummer for organisasjon
UtleggIntet til utlegg og utleggstrekk
ITUIntet til utlegg
UTTUtleggstrekk
AktiveMed aktive menes de utleggstrekkene eller intet til utlegg som har status GO (godkjent)
EndringsloggEndringsinformasjon (nye/slettede/endrede) om intet til utlegg og utleggstrekk. Det er bare kredittopplysningsforetak som kan abonnere på endringslogg. De har hjemmel for abonnement i utleggsregisterforskriftens § 3, jf tinglysningslovens § 34 a.
TotalbestandAlle aktive saker (utleggstrekkene/intet til utlegg som har status GO) om intet til utlegg og utleggstrekk. Det er bare kredittopplysningsforetak som kan be om å få hente totalbestand. De har hjemmel for abonnement i utleggsregisterforskriftens § 3, jf tinglysningslovens § 34 a.