*Tjenesten er under utvikling, og endring i dokumentasjon på denne siden kan forekomme uten varsel. DSOP Forvaltning vil kontakte alle relevante kontaktpersoner når dokumentasjonen er ferdigstilt.*

BlockFund - Håndtering av sperringer på en konto

Tjenesten FI-Utlegg Notifikasjon håndterer bestilling, endring og sletting av sperringer av beløp på en gitt konto for en gitt person eller virksomhet. Sperringene besluttes av namsmyndighetene, henholdsvis Innkrevingsmyndigheten (IM) hos Skatteetaten og alminnelig namsmann (AN) hos politiet. Tjenesten FI-Utlegg Notifikasjon sørger for at finansforetak mottar og behandler bestillinger om sperring av beløp på en gitt konto samt endring og sletting av eksisterende sperringer.

FI-Utlegg Notifikasjon benytter BlockFund API-et for gjennomføring av bestillinger knyttet til sperring på konto. BlockFund API-et støtter både synkron og asynkron metode for gjennomføring av bestillinger, herunder sperring på konto samt oppdatering og sletting av eksisterende sperringer. Dette innebærer at finansforetakene står fritt for å implementere bestillinger fra namsmyndighetene enten synkront eller asynkront, avhengig av deres bakenforliggende systemer. Finansforetakene vil også kunne støtte begge metodene avhengig av hvilke kontoer beløp skal sperres på.

alt text

Tjenesten støtter at finansforetakene gjennomfører bestillinger i sanntid eller i ettertid.

Sperring av beløp på en konto, samt oppdatering eller sletting av eksiterende sperring, igangsettes i namsmyndighetenes saksbehandlingsflater, henholdsvis Innfri for IM i Skatteetaten og SIRO for AN i politiet.

  1. Bestilling av en ny sperring på en konto og bestilling av en endring eller sletting av en eksisterende sperring på en konto.
    Finansforetak kan enten gjennomføre bestillingen i sanntid (synkront) eller informere etat at bestillingen blir gjort i ettertid (asynkront).
  2. Dersom finansforetak har informert etat at bestillingen vil bli gjennomført asynkront i trinn 1, henter etat status av gjennomføring av bestillingen i ettertid.

Informasjonsflyt - BlockFund

Figuren nedenfor illustrerer informasjonsflyten i forbindelse med en forespørsel via tjeneste FI-Utlegg Notifikasjon til BlockFund API-et. Trinnene i prosessen er beskrevet nedenfor.

alt text

  1. Datakonsumenten (etat) ber om tekniske endepunkter for finansforetakene som tilbyr tjenesten FI-Utlegg Notifikasjon i Fellesdatakatalog (Common API-registry) hos Digdir. Siden det sjelden gjøres endringer i disse endepunktene, anbefales det å mellomlagre svaret for å sikre at løsningen kjører effektivt (caching). Datakonsumenten skal benytte endepunktet Utleggspant for tjenesten FI-Utlegg Notifikasjon.
    • Utleggspant: Den vanligste tjenesten som returnerer gjeldende endepunktadresser og API-versjoner for finansforetak som tilbyr BlockFund API-et.
  2. Datakonsumenten (etat) ber om et tilgangstoken fra Maskinporten (autorisasjonsserver hos Digdir) for å få tilgang til finansforetakenes API (BlockFund).
    • Scopet for denne tjenesten er «bits:blockfund-IM» for Innkrevingsmyndighetene og «bits:blockfund-AN» for alminnelig namsmann.


Synkron flyt – Datatilbyder (finansforetak) gjennomfører kommandoen i sanntid.

  1. Datakonsumenten (etat) sender en kommando for sperring av beløp på en konto eller for endring/sletting av en eksisterende sperring hos finansforetak fra API-endepunkter (POST/PATCH/DELETE) med et tilgangstoken (se punkt 2). Datakonsument kan også sende en PING for å be om en bekreftelse at tjenesten hos finansforetak fungerer.
    • 3.1 Datatilbyder (finansforetak) validerer det mottatte tilgangstoken (krav og signaturer). Det anbefales at valideringen gjøres lokalt. En servernøkkel for autorisasjon (verifisering av Digdirs signatur) må hentes fra Digdir hvis den ikke allerede er lagret i den lokale hurtigbufferen (cache).
    • 3.2 Datatilbyder (finansforetak) validerer forespørsel iht. til datavalidering for tjenesten FI-Utlegg Notifikasjon. Idempotens-tilfeller vil bli håndtert ved dette punktet.
    • 3.3 Datatilbyder (finansforetak) gjennomfører kommandoen POST/PATCH/DELETE synkront i sitt fagsystem i samsvar med Tjenesten.
    • 3.4 Datatilbyder (finansforetak) sender status knyttet til pkt. 3.3 (med orderStatus = COMPLETED) samt nødvendig informasjon og status knyttet til kommandoen POST/PATCH/DELETE.


Asynkron flyt – Datatilbyder (finansforetak) gjennomfører kommandoen i separat prosess

  1. Datakonsumenten (etat) sender en kommando for sperring av beløp på en konto eller for endring/sletting av en eksisterende sperring hos finansforetak fra API-endepunkter (POST/PATCH/DELETE) med et tilgangstoken (se punkt 2).
    • 4.1 Datatilbyder (finansforetak) validerer det mottatte tilgangstoken (krav og signaturer). Det anbefales at valideringen gjøres lokalt. En servernøkkel for autorisasjon (verifisering av Digdirs signatur) må hentes fra Digdir hvis den ikke allerede er lagret i den lokale hurtigbufferen (cache).
    • 4.2 Datatilbyder (finansforetak) validerer forespørsel iht. til datavalidering for tjenesten FI-Utlegg Notifikasjon. Idempotens-tilfeller vil bli håndtert ved dette punktet.
    • 4.3 Datatilbyder (finansforetak) bekrefter mottatte kommando POST/PATCH/DELETE synkront og gjennomfører den asynkront i sitt fagsystem i samsvar med Tjenesten.
    • 4.4 Datatilbyder (finansforetak) sender status knyttet til pkt. 4.3 (med orderStatus = PENDING) samt nødvendig referansen til bestilling orderUUId knyttet til kommandoen POST/PATCH/DELETE.
  2. Datakonsumenten (etat) ber om et tilgangstoken fra Maskinporten (autorisasjonsserver hos Digdir) for å få tilgang til finansforetakenes API (BlockFund).
    • Scopet for denne tjenesten er «bits:blockfund-IM» for Innkrevingsmyndighetene og «bits:blockfund-AN» for alminnelig namsmann


Datakonsument ber om status for kommandoen

  1. Datakonsumenten (etat) sender en GET kommando for henting av status fra en tidligere sendt kommando (POST/PATCH/DELETE) til finansforetak API-et med et tilgangstoken (se punkt 5).
    • 6.1 Datatilbyder (finansforetak) validerer det mottatte tilgangstoken (krav og signaturer). Det anbefales at valideringen gjøres lokalt. En servernøkkel for autorisasjon (verifisering av Digdirs signatur) må hentes fra Digdir hvis den ikke allerede er lagret i den lokale hurtigbufferen (cache).
    • 6.2 Datatilbyder (finansforetak) validerer forespørsel iht. til datavalidering for tjenesten FI-Utlegg Notifikasjon.
    • 6.3 Datatilbyder (finansforetak) gjennomfører kommandoen GET synkront i samsvar med Tjenesten.
    • 6.4 Datatilbyder (finansforetak) sender status knyttet til pkt. 4.3
      • med orderStatus = COMPLETED samt nødvendig informasjon og status knyttet til kommandoen POST/PATCH/DELETE
      • med orderStatus = PENDING. I dette tilfelle vil datakonsument gjennomføre pkt. 5 og 6 inntil orderStatus = COMPLETED

Generell informasjon

Informasjon om Beskrivelse Lenke
Informasjon om volum og responstider Responstidene kan variere mellom finansinstitusjoner. Ved synkron gjennomføring vil datakonsument motta direkte tilbakemelding. Ved asynkron gjennomføring vil SLA definert i Tjenestebeskrivelsen gjelde.

Volum for tjenesten FI-Utlegg Notifikasjon
- Det forventes følgende volum fra Namsmyndighetene per år for forespørsel om kontoliste og kontodetaljer: 60 000 forespørsler 		-
Sikkerhetsdokumentasjon Sikkerhetsdokumentasjon for DSOP Kontrollinformasjon fellesstandard gjelder for tjenesten FI-Utlegg Notifikasjon. Sikkerhetsdokumentasjon
API-spesifikasjon Følgende endepunkter inngår i tjenesten FI-Utlegg Notifikasjon:
- BlockFund

Det er minimum versjon 1.0 av DSOP BlockFund API-et som skal benyttes for tjenesten. 		Dokumentasjon på engelsk: API-specification


Tilgangskontroll for å benytte tjenesten

Det felles tekniske saksbehandlingssystemet for utleggsprosessen i Skatteetaten gjennomfører de tekniske forespørsler og vil kunne identifisere seg med riktig org.nr. Identifiseringen benytter Maskinporten hos Digdir.

For å benytte tjenesten FI-Utlegg Notifikasjon og få tilgang til BlockFund API-et skal følgende scope benyttes i Maskinporten (ref. punkt 2 og 5 i informasjonsflyten).

alt text


API Scope fra Maskinporten Minimum nødvendig versjon av API
/blockfund
For POST, PATCH, DELETE, GET og PING		 For Innkrevingsmyndighetene (IM) – Skatteetaten:
bits:blockfund-IM der "consumer.ID" = "0192:974761076".

For Alminnelig Namsmann (AN) – Politiet:
Delegert bits:blockfund-AN der "consumer.ID" = "0192:915429785" og "supplier.ID" = "0192:974761076".

Viktig: “consumer.ID” skal brukes for å validere datakonsumenten, ikke “supplier.ID”.

Se FAQ: Access token from Maskinporten 		V.1.0


HTTP-forespørselsmetoder (HTTP Request Methods) i API-et

BlockFund API-et støtter følgende HTTP-forespørselsmetoder:

  • POST – Bestilling av en sperring av et beløp på en konto
  • PATCH – Bestilling av en endring av en eksisterende sperring på en konto

  • DELETE – Bestilling av en sletting av en eksisterende sperring på en konto
    API-et støtter at POST, PATCH og DELETE metodene blir gjennomført synkront eller asynkront av datatilbyder (finansforetak). Avhengig av fagsystemer og type kontoer vil datatilbyder kunne velge hvilken gjennomførings metode (synkront/asynkront) som vil bli benyttet for å fullføre bestillingen.

  • GET – Innhenting av status og gjennomføring av bestilling i ettertid
    Innhenting av status på en bestilling via GET metoden gjennomføres kun synkront av datatilbyder (finansforetak), men API-et støtter at status til bestilling tilsier at bestillingen ennå ikke er fullført. Datakonsument vil dermed prøve igjen senere å hente status på en bestilling inntil denne er fullført av datatilbyder (eller har feilet).

  • PING – Sjekking om at tjenesten er oppe og går
    Brukes av datakonsument for å sikre seg at tjenesten er oppe og går i sanntid.


Teknisk spesifikasjon for BlockFund API-et

Versjon Beskrivelse Dokumentasjon
Versjon 0.9.5 Gjeldende versjon for piloten BlockFund API-specification V.0.9.5

HTTP-feilkoder og spesifikke feilsituasjoner med tilhørende ACC-meldingskoder

Her mangler en lenke

Gjeldende spesifikasjon for HTTP-feil 4XX og 5XX med tilhørende ACC-koder er definerte i BlockFund API - HTTP error codes and specific error situations with associated ACC-codes.
Finansforetakene skal returnere assosiert og predefinert feilmelding med ACC.

Her mangler en lenke


Viktige prinsipper for gjennomføring av forespørsler i tjenesten FI-Utlegg Notifikasjon

For å unngå unødvendige feilsituasjoner skal finansinstitusjoner forholde seg til følgende prinsipper i tjenesten:

  • Det skal aksepteres at flere forespørsler sendes i parallelt til et finansforetak for samme skyldner, så lenge disse gjelder forskjellige kontoer.
  • Dersom etat sender flere forespørsler til den samme kontoen uavhengig om det gjelder en eksisterende sperring eller en ny, vil kun den første forespørselen gjennomføres og etat vil måtte vente på at den første forespørselen er fullført før å sende en ny forespørsel.
    • Dette gjelder for hele kontoen og ikke kun for en gitt sperring
    • Dette gjelder for HTTP-forespørselsmetoder POST, PATCH og DELETE i BlockFund API-et.
    • Dette gjelder uavhengig av synkron eller asynkron flyt.
  • Det vil bli sendt eksplisitte feilmeldinger dersom etat allikevel sender forespørsler på den samme kontoen før den forrige forespørselen er fullført (http-error 409).
    Dersom etat sender den samme forespørselen flere ganger (idempotens) til den samme kontoen vil finansforetak opplyser etat at denne forespørselen allerede er mottatt og håndtert.
    Dette er uavhengig av gjennomførings metode (synkront/asynkront).


    • Håndtering av HTTP-forespørselsmetoder (HTTP Request Methods)

    Når identifiseringen av etat er gjennomført vil Skatteetaten sende forespørsler på følgende måte:

    alt text


    Input-feler i API-et

    Det er flere input-felter som brukes på tvers av HTTP-forespørselsmetodene i API-et. Disse er beskrevet under.

    Input-felter Beskrivelse Benyttes i HTTP-forespørselsmetode
    accountInfoRequestID Unike referanse til saksnummer i løsningen hos innkrevingsmyndighetene eller alminnelig namsmann.
    «AccountInfoRequestID» må være den samme for alle forespørsler knyttet til den samme saken, knyttet til en partyId, på tvers av kontoer og på tvers av finasforetak.    		 Alle
    correlationId UUID-verdi for unik teknisk referanse til forespørselen. Alle
    idempotenceKey UUID-verdi for idempotens-nøkkel. Dersom to forespørsler har ulike IdempotenceKey skal disse tolke som to separate bestillinger, mens forespørsler med lik IdempotenceKey skal tolkes som den samme bestillingen. Alle
    legal-Mandate Lovhjemmel som benyttes for å gjennomføre forespørsel.

    For innkrevingsmyndighetene (Skatteetaten) er lovhjemmel:
    “tvfbl. §§ 7-17, 7-19, 5-15, 5-16, 7-26, jf. innkrevingsl. § 23”.
    URL Encoded verdien skal være: “tvfbl.%20%C2%A7%C2%A7%207-17%2C%207-19%2C%205-15%2C%205-16%2C%207-26%2C%20jf.%20innkrevingsl.%20%C2%A7%2023”

    For alminnelig namsmann (politiet) er lovhjemmel:
    - For blockType «utleggspant»: «tvfbl. §§ 7-17, 7-19, 5-15, 5-16 og 7-26»
    URL Encoded verdien skal være:
    “tvfbl.%20%C2%A7%C2%A7%207-17%2C%207-19%2C%205-15%2C%205-16%20og%207-26”

    - For blockType «arrest»:
    «tvfbl. §§ 33-5 til 33-7»
    URL Encoded verdien skal være:
    “tvfbl.%20%C2%A7%C2%A7%2033-5%20til%2033-7”    		 Alle
    requesterId I tjenesten FI-Utlegg Notifikasjon skal dette feltet inneholde en representasjon av brukerID til saksbehandleren eller systembrukeren i Skatteetaten (Innfri) eller politiet (SIRO) selv om parameteren ikke er obligatorisk teknisk.

    Retningslinjer for RequesterID:
  • RequesterID identifiserer brukeren som sender inn forespørselen hos den offentlige etaten. De offentlige etatene står fritt til å pseudonymisere RequesterID slik at finansforetak ikke kan koble denne ID-en til etatens bruker eller fysiske person.
  • Den offentlige etaten må på sin side kunne koble RequesterID til en bruker i den offentlige etaten.
  • Det er viktig at RequesterID forblir konstant per bruker og ikke gjenbrukes for nye brukere.
    		•  Alle
    partyId Skyldnerens FNR, D-nr eller org.nr. Alle
    accountNumber Kontonummer der beløp er bedt sperret.
    I tjenesten FI-Utlegg Notifikasjon skal verdien som sendes i accountNumber være verdien som har blitt returnert fra DSOP Kontroll API-et i tjenesten FI-Utlegg Saldo (accounts.accountIdentifier eller account.accountIdentifier).     		Alle
    blockFundReferenceUUID Unik identifikator for sperringen (blockfund) dette gjelder (per kontonummer). Denne er først returnert av finansforetaket ifm. POST-response eller GET-response, begge med orderStatus = COMPLETED. PATCH, DELETE
    orderUUID Unik identifikator for sperringens ordre.
    Denne er returnert av finansforetaket ifm. POST/PATCH/DELETE-response med orderStatus = PENDING.    		 GET
    Request body
    blockType Type sperring (utleggspant / arrest)
  • utleggspant: En utleggspant er en pant i eiendeler, som fast eiendom, bankkontoer eller verdipapirer. En kreditor kan da begjære tvangssalg av eiendelen det er etablert pant i.
  • arrest: Midlertidig sikring av pengekrav som betyr at kravshaveren mottar en form for sikkerhet i en eiendel som tilhører skyldneren for å forhindre at tvangsfullbyrdelse senere blir umulig eller vanskelig.
    		•  POST
    requestedBlockfundAmount Beløp datakonsument (etat) som er bedt sperret. POST, PATCH
    decisionDateTime Dato og klokkeslett for avgjørelsen i saken. POST
    creditor Informasjon om kreditoren som BlockFund er opprettet på vegne av.
    Det anbefales sterkt å lagre denne informasjonen i tilfelle finansforetaket blir kontaktet av kreditoren eller av en norske juridisk representant.     		POST
    norwegianPartyId Unik identifikator for en part med norsk id. Kan være organisasjonsnummer (9 siffer) eller fødselsnummer (11 siffer). POST
    foreignPartyIdentifier Strukturert identifikasjon av utenlandsk kreditor uten norsk ID. POST
    name Fullt juridisk navn på den utenlandske parten.
  • For en person: fornavn og etternavn.
  • For en bedrift: registrert firmanavn.
    		•  POST
    address Fullstendig postadresse til den utenlandske parten, inkludert gate, by, postnummer og land. POST
    tin Tax Identification Number (TIN) til den utenlandske parten, inkludert land og type. POST
    identifierValue Selve TIN-verdien. POST
    identifierType Type skatteidentifikator, f.eks. mva., UTR, personnummer, ITIN. POST
    countryCode ISO 3166-1 alpha-2 landskode for landet som utstedte TIN-nummeret. POST
    partyType Informasjon om kreditoren er en fysisk person eller en forretning. POST
    legalRepresentativeId Unik identifikator for kreditorens Norsk juridisk representant. Kan være organisasjonsnummer (9 siffer) eller fødselsnummer (11 siffer). POST


    Se API spesifikasjonen for mer detaljer.


    Trinn 1a - Bestilling av ny sperring (POST)

    Datakonsumenter (etat) og datatilbydere (finansforetak) skal implementere POST forespørsler på følgende måte:

    POST Forespørsel - Ny sperring

    Se beskrivelsen av input-feltene under Input-felter i API-et

    NY LENKE ovenfor NY LENKE ovenfor NY LENKE ovenfor

    Input-felter
    Header
    accountInfoRequestId
    correlationID
    legal-Mandate
    requesterId
    partyId
    accountNumber
    Request body
    blockType
    requestedBlockfundAmount
    decisionDateTime
    creditor
    norwegianpartyId
    foreignPartyIdentifier
    name
    address
    tin
    identifierValue
    identifierType
    countryCode
    partyType
    legalRepresentativeId

    POST - Response

    BlockFundOrder Beskrivelse
    orderUUId Unik identifikator for bestilling av sperring som benyttes ved asynkron innhenting av status med GET.
    orderStatus Status for gjennomføring av bestillingen.
    • COMPLETED: Bestillingen er fullført, og sperring er opprettet.
      Dette er den normale responsen for synkron behandling.
      BlockFund (objektet) vil følgelig også bli levert i responsen.
        • - HTTP koden 200 (Idempotence): Kallet har gått bra, men det fantes et tilsvarende kall med samme IdempotenceKey (Idenpotens-nøkkel).
        - HTTP koden 201: Kallet har gått bra og sperringen er fullført.
    • PENDING: Bestillingen er ikke utført og vil gjennomføres i ettertid.
      Normal respons for asynkron behandling.
        • - HTTP koden 200 (Idempotens): Kallet har gått bra, men det fantes et tilsvarende kall med samme IdempotenceKey (Idempotens-nøkkel).
        - HTTP koden 202: Kallet har gått bra og bestillingen om sperring er registrert.
    BlockFund (dersom orderStatus = COMPLETED)
    blockFundReferenceUUId Unik identifikator for sperringen (blockfund) fra finansforetak. Denne returneres av finansforetaket.
    partyId Skyldnerens FNR, D-nr eller org.nr.
    accountNumber Kontonummer der beløp er bedt sperret.
    requestedBlockfundAmount Beløp datakonsument (etat) som er bedt sperret.
    decisionDateTime Dato og klokkeslett for avgjørelsen i saken.
    BlockFund (dersom orderStatus = PENDING)
    blockFunds returneres ikke og den må hentes i ettertid med GET.
    Conflict
    HTTP koden 409: Datatilbyder har allerede mottatt en forespørsel for det samme kontonummer som ikke er fullført ferdig.
    Error
    • HTTP koden 4xx som støttes for POST:
        • - 400, 401, 403 and 404
    • HTTP koden 5xx:
        • - 500, 503, 504 and 511


    Trinn 1b - Endring av eksisterende sperring (PATCH)

    Datakonsumenter (etat) og datatilbydere (finansforetak) skal implementere PATCH forespørsler på følgende måte:


    PATCH Forespørsel - Endring av eksisterende sperring

    Input-felter
    Header
    AccountInfoRequestID
    CorrelationID
    Legal-Mandate
    RequesterID
    partyId
    accountNumber
    blockFundReferenceUUId
    Request body
    requestedBlockfundAmount


    PATCH - Response

    BlockFundOrder Beskrivelse
    orderUUId Unik identifikator for endring av eksisterende sperring som benyttes ved asynkron innhenting av status med GET.
    orderStatus Status for gjennomføring av bestillingen.
    • COMPLETED: Bestillingen er fullført, og eksisterende sperring er endret.
      Dette er den normale responsen for synkron behandling.
      BlockFund (objektet) vil følgelig også bli levert i responsen.
        • - HTTP koden 200 (Idempotence): Kallet har gått bra, men det fantes et tilsvarende kall med samme IdempotenceKey (Idenpotens-nøkkel).
        - HTTP koden 201: Kallet har gått bra og sperringen er endret.
    • PENDING: Bestillingen er ikke utført og vil gjennomføres i ettertid.
      Normal respons for asynkron behandling.
        • - HTTP koden 200 (Idempotens): Kallet har gått bra, men det fantes et tilsvarende kall med samme IdempotenceKey (Idempotens-nøkkel).
        - HTTP koden 202: Kallet har gått bra og bestillingen om endring er registrert.
    BlockFund (dersom orderStatus = COMPLETED)
    blockFundReferenceUUId Unik identifikator for sperringen (blockfund) fra finansforetak. Denne skal være akkurat den samme som i forespørselen og returneres av finansforetaket.
    partyId Skyldnerens FNR, D-nr eller org.nr.
    accountNumber Kontonummer der sperrede beløp har blitt endret.
    requestedBlockfundAmount Nytt beløp datakonsument (etat) har bedt å sperre.
    decisionDateTime Dato og klokkeslett for avgjørelsen i saken ved opprettelse av sperring via POST.
    actualBlockFundAmount Beløp finansforetaket faktisk fikk endret til.
    actualBlockFundDateTime Dato og klokkeslett for når sperrede beløp ble endret av finansforetak.
    BlockFund (dersom orderStatus = PENDING)
    blockFund returneres ikke og den må hentes i ettertid med GET.
    Conflict
    HTTP koden 409: Datatilbyder har allerede mottatt en forespørsel for det samme kontonummer som ikke er fullført.
    Error
    • HTTP koden 4xx som støttes for PATCH:
        • - 400, 401, 403 and 404
    • HTTP koden 5xx:
        • - 500, 503, 504 and 511


    Trinn 1c - Sletting av eksisterende sperring (DELETE)

    Datakonsumenter (etat) og datatilbydere (finansforetak) skal implementere DELETE forespørsler på følgende måte:

    DELETE Forespørsel - Sletting av en eksisterende sperring

    Input-felter
    Header
    AccountInfoRequestID
    CorrelationID
    Legal-Mandate
    RequesterID
    partyId
    accountNumber
    blockFundReferenceUUId


    DELETE - Response

    BlockFundOrder Beskrivelse
    orderUUId Unik identifikator for endring av eksisterende sperring som benyttes ved asynkron innhenting av status med GET.
    orderStatus Status for gjennomføring av bestillingen.
    • COMPLETED: Bestillingen er fullført, og eksisterende sperring er slettet.
      Dette er den normale responsen for synkron behandling.
        • - HTTP koden 200 (Idempotence): Kallet har gått bra, men det fantes et tilsvarende kall med samme IdempotenceKey (Idenpotens-nøkkel).
        - HTTP koden 204: Kallet har gått bra og slettingen er fullført.
    • PENDING: Bestillingen er ikke utført og vil gjennomføres i ettertid.
      Normal respons for asynkron behandling.
        • - HTTP koden 200 (Idempotens): Kallet har gått bra, men det fantes et tilsvarende kall med samme IdempotenceKey (Idempotens-nøkkel).
        - HTTP koden 202: Kallet har gått bra og bestillingen om sletting er registrert.
    Conflict
    HTTP koden 409: Datatilbyder har allerede mottatt en forespørsel for det samme kontonummer som ikke er fullført ferdig.
    Error
    • HTTP koden 4xx som støttes for DELETE:
        • - 400, 401, 403 and 404
    • HTTP koden 5xx:
        • - 500, 503, 504 and 511


    Trinn 1d - Verifiser at tjenesten er tilgjengelig (PING)

    Datakonsumenter (etat) og datatilbydere (finansforetak) skal implementere PING forespørsler på følgende måte:


    PING Forespørsel - Verifiser at tjenesten er tilgjengelig

    BlockFundOrder Beskrivelse
    Ingen parametre


    PING - Response

    PING vil respondere med http kode 200 dersom tjenesten er tilgjengelig.


    Trinn 2 - Henting av status (GET)

    Datakonsumenter (etat) og datatilbydere (finansforetak) skal implementere GET forespørsler på følgende måte for å hente status fra tidligere POST/PATCH/DELETE bestillinger:

    GET Forespørsel - Henting av status

    Header
    AccountInfoRequestID
    CorrelationID
    Legal-Mandate
    RequesterID
    partyId
    accountNumber
    OrderUUId

    GET - Response for POST, PATCH og DELETE

    BlockFundOrder Beskrivelse
    orderUUId Unik identifikator for bestillingen det refereres til. Denne skal være akkurat den samme som i forespørselen og returneres av finansforetaket.
    orderStatus Status for gjennomføring av bestillingen.
    • COMPLETED: Bestillingen er fullført.
        • HTTP koden 200: Kallet har gått bra og
        - POST: BlockFund er levert.
        - PATCH: BlockFund er endret.
        - DELETE: BlockFund er slettet.
    • PENDING: Bestillingen er ikke utført og vil gjennomføres i ettertid.
      Normal respons for asynkron behandling.
        • HTTP koden 202: Kallet har gått bra, men
        - POST: BlockFund er ikke opprettet enda.
        - PATCH: BlockFund er ikke endret enda.
        - DELETE: BlockFund er ikke slettet enda.
    • ERROR:
        • HTTP koden 4xx som støttes for GET:
        400, 401, 403 and 404
        HTTP koden 5xx:
        500, 503, 504 and 511
    BlockFund (dersom orderStatus = COMPLETED)
    blockFundReferenceUUId Unik identifikator for sperringen (blockfund) fra finansforetak. Denne returneres av finansforetaket.
    partyId Skyldnerens FNR, D-nr eller org.nr.
    accountNumber Kontonummer der beløp er bedt sperret.
    requestedBlockfundAmount Beløp datakonsument (etat) som er bedt sperret.
    decisionDateTime Dato og klokkeslett for avgjørelsen i saken.
    actualBlockFundAmount Beløp finansforetaket faktisk fikk sperret.
    Finansforetak vil skille mellom forespurt (requested) og faktisk (actual) beløpsverdier. Hvis ingenting kan sperres, returnerer actualBlockFundAmount = 0, ikke en feil.
    actualBlockFundDateTime Dato og klokkeslett for når beløp ble sperret av finansforetak.
    BlockFund (dersom orderStatus = PENDING)
    blockFund returneres ikke og den må hentes i ettertid med ny GET forespørsel.
    Error
    • HTTP koden 4xx som støttes for GET:
    • 400, 401, 403 and 404
    • HTTP koden 5xx:
    • 500, 503, 504 and 511


    Datavalidering

    Det er finansforetakenes ansvar å validere forespørsler fra etat og det er opp til finansforetakene å sørge for at alle forespørsler fra etat blir validert godt nok. Ved å validere og logge input-parametere fra etat riktig, vil finansforetakene være bedre egnet til å unngå utfordringer i senere anledning. Implementering av slik logikk er finansforetakenes ansvar.


    Generelle og generiske valideringer

    Disse er beskrevet på Generic DSOP Control validations. Org.nr. til Skatteetaten er 974761076 for Innkrevingsmyndighetene og orgnr. til Politi- og lensmannsetaten er 915429785 for alminnelig namsmann.
    Se FAQ: Access token from Maskinporten.


    Spesifikke valideringer for FI-Utlegg Notifikasjon

    Gyldig input-parameter for FI-Utlegg Notifikasjon

    • Tilgangstoken fra Maskinporten: For alle HTTP- forespørselsmetoder bør finansforetakene validere tokenet fra Maskinporten for forespørsler fra Skatteetaten for innkrevingsmyndighetene eller fra Politi- og lensmannsetaten for alminnelig namsmann med følgende scope:
      bits:blockfund-IM for Innkrevingsmyndighetene og bits:blockfund-AN for alminnelig namsmann. Det er viktig å verifisere signaturs gyldighet for tilgangstoken fra Maskinporten, samt integritet.
      • For Innkrevingsmyndighetene (IM) – Skatteetaten: Verifisere at "consumer.ID" = "0192:974761076".
      • For Alminnelig Namsmann (AN) – Politiet: Verifisere at "consumer.ID" = "0192:915429785" og "supplier.ID" = "0192:974761076".
      • Mer om tilgangstoken validering på Access token validation på Digdir.


    Forslag til validering for input-parameterne i BlockFund for de ulike HTTP-forespørselsmetodene

    Input parametere Forventet verdi Forslag til validering
    CorrelationID (For alle HTTP-metodene) Uuid verdi til en unik teknisk referanse for forespørselen. Formatet kan valideres. I tillegg benyttes denne parameteren for å hensynta idempotens for POST og PATCH.
    Legal-Mandate (For alle HTTP-metodene) For innkrevingsmyndighetene (Skatteetaten) er lovhjemmel:
    “tvfbl.%20%C2%A7%C2%A7%207-17%2C%207-19%2C%205-15%2C%205-16%2C%207-26%2C%20jf.%20innkrevingsl.%20%C2%A7%2023”

    For alminnelig namsmann (politiet) er lovhjemmel:
    - For blockType «utleggspant»: “tvfbl.%20%C2%A7%C2%A7%207-17%2C%207-19%2C%205-15%2C%205-16%20og%207-26”

    - For blockType «arrest»:
    “tvfbl.%20%C2%A7%C2%A7%2033-5%20til%2033-7”    		 Verdi må finnes i forespørselen. Strengen skal være i encoded format og burde valideres iht. til definerte verdier og kombinasjoner av dem per datakonsument og type sperring.
    RequesterID (For alle HTTP-metodene) Representasjon av brukerID til saksbehandleren. Verdi må finnes i forespørselen.
    partyID Kontrollbjektet:
    Organisasjonsnummer, FNR eller D.NR.    		 Formatet kan valideres.
    accountNumber Kontonummer der endringen på eksisterende sperring med referanse blockFundReferenceUUId skal gjennomføres. Formatet kan valideres. For PATCH, må accountNumber stemme med tidligere kontonummer knyttet til blockFundReferenceUUId.
    blockFundReferenceUUId (Kun for HTTP-metodene PATCH og DELETE) Unik identifikator for sperringen (blockfund) dette gjelder Verdi må finnes i PATCH/DELETE forespørselen og format kan valideres.
    OrderUUId (Kun for HTTP-metoden GET) Unik identifikator for tidligere bestillinger Verdi må finnes i GET forespørselen og format kan valideres.
    Request body (for HTTP-metoden POST)
    blockType Type sperring (utleggspant / arrest) De to verdiene kan valideres.
    requestedBlockfundAmount Ønsket beløp for blockfund Verdi må finnes. Beløpet kan være større enn disponibel saldo.
    decisionDateTime Dato og klokkeslett Verdi må finnes. Datoformat kan valideres.
    creditor.norwegianPartyId Norsk kreditor:
    Organisasjonsnummer, FNR eller D.NR.    		 Formatet kan valideres.
    creditor.foreignPartyIdentifier Utenlandske kreditor:
    Noen av feltene i foreignPartyIdentifier strukturen kan valideres    		 Noe av formatet kan valideres.
    creditor.partyType To ulike predefinerte verdier Formatet kan valideres.
    creditor. legalRepresentativeId Norsk juridisk representant:
    Organisasjonsnummer eller FNR.    		 Formatet kan valideres.
    Request body (Kun for HTTP-metoden PATCH)
    requestedBlockfundAmount Ønsket beløp for blockfund Verdi må finnes. Beløpet må være mindre enn eksisterende sperrede beløp for blockFundReferenceUUId.


    Endringslogg

    Dato Endring
    xx.xx.26 Publisering av godkjent løsningsbeskrivelse.