Kontrollinformasjon - Innhenting av kontoinformasjon til Skatteetaten

Tjenesten er basert på DSOP Kontrollinformasjon fellesstandard og gjelder utlevering av kontoopplysninger til Skatteetaten. Se Juridiske rammebetingelser for Skatt-kontroll.

Prosessoversikt

Trinn 1 - DSOP Oversikt over kundeforhold

Skatteetaten skal bruke DSOP Oversikt over kundeforhold API-et på følgende måte:

Tillatte endepunkter i trinn 1 for tjenesten Skatt-Kontroll

Endepunkter Scope fra Maskinporten Minimum nødvendig versjon av API
customerRelationships bits:kundeforhold V.2.0

Gyldig forespørsel - Trinn 1

Skatteetaten skal bruke endepunktet customerRelationships på følgende måte:

Input-felter Beskrivelse
Authorization Gyldig token fra Maskinporten (bits:kundeforhold).
CustomerID FNR/D-NR eller orgnr til kontrollobjektet.
CorrelationID Uuid-verdi for unik teknisk referanse til forespørselen.
Legal-Mandate Lovhjemmel er: “Skatteforvaltningsloven § 10-2 første ledd, jf. § 10-14, jf. skatteforvaltningsforskriften § 10-2-1”. URL Encoded verdien skal altså være “Skatteforvaltningsloven%20%C2%A7%2010-2%20f%C3%B8rste%20ledd%2C%20jf.%20%C2%A7%2010-14%2C%20jf.%20skatteforvaltningsforskriften%20%C2%A7%2010-2-1”.
AccountInfoRequestID Uuid-verdi for saksnummer i Skatteetaten.
fromDate Opptil 10 år før dagens dato.
toDate En dato nyere eller lik fromDate.
onlyPrimaryOwner Skatteetaten har mulighet til å bruke “onlyPrimaryOwner” = “FALSE» eller “TRUE”. Dersom Skatteetaten ikke har behov for kundeforhold der kontrollobjektet er/var disponent anbefales det å dataminimere i forespørelen: “onlyPrimaryOwner” = “TRUE”

Se datamodell for customerRelationships.

Trinn 2 a og b - DSOP Kontrollinformasjon

Generell informasjon

Informasjon om W Beskrivelse Link
Funksjonell spesifikasjon Den funksjonelle spesifikasjonen for DSOP Kontrollinformasjon fellesstandard gjelder for tjenesten Skatt-kontroll. Dokumentasjon på engelsk: Functional specification DSOP Control Common Standard.
Informasjon om volum og responstider Responstidene kan variere mellom finansinstitusjoner, men det typiske mønsteret er at forespørsler etter data vil ha raske responstider (sekunder), mens store historiske forespørsler kan ta lengre tid.

Volum for tjenesten Skatt-Kontroll.
- Det forventes en betydelig økning i forespørsler til finansforetakene fra Skatteetaten. Totalt volum per år for forespørsel om kontoliste, transaksjoner og saldo:
- Estimert nåværende: xx.xxx
- Estimert fremtidig: xxx.xxx
 
Sikkerhetsdokumentasjon Sikkerhetsdokumentasjon for DSOP Kontrollinformasjon fellesstandard gjelder for tjenesten Skatt-Kontroll. Sikkerhetsdokumentasjon.
Arkitektur Arkitektur for DSOP Kontrollinformasjon fellesstandard gjelder for tjenesten Skatt-Kontroll. Dokumentasjon på engelsk: Architecture documentation.
API-spesifikasjon Følgende endepunkter inngår i tjenesten Skatt-Kontroll:
- Accounts
- Account details
- Transactions
- Cards
- Roles

Det er minimum versjon 2.0 av DSOP Kontroll API-et som skal benyttes for tjenesten.
Dokumentasjon på engelsk: API-specification.
Overordnet spesifikasjon av DSOP-Kontroll API-et Den overordnede spesifikasjon av DSOP Kontroll API-et for DSOP Kontrollinformasjon fellesstandard gjelder for løsningen Skatt-Kontroll. Overall description of the DSOP Control API
Integrasjonstesting Definerte test-caser for DSOP Kontrollinformasjon fellesstandard gjelder for tjenesten Skatt-Kontroll.
Internal testing / quality assurance DSOP Control Common Standard.
Datavalidering Generelle anbefalinger om validering i DSOP Kontrollinformasjon fellesstandard er også gjeldende for utlevering av kontoinformasjon i tjenesten Skatt-Kontroll.

Det er også spesifikke valideringer som gjelder i tjenesten Skatt-Kontroll som også bør implementeres.
Generic DSOP Control validations

Se eget avsnitt nede på siden.

Tillatte endepunkter i trinn 2 for tjenesten Skatt-Kontroll

Endepunkter Scope fra Maskinporten Minimum nødvendig versjon av API
Accounts (kontoliste)
Account Details (kontodetaljer)
Transactions (transaksjoner)
Cards (Kort)
Roles (roller)
bits:kontoinformasjon V.2.0

Gyldig forespørsel - Trinn 2a

Skatteetaten skal bruke endepunktet Accounts på følgende måte:

Input-felter Beskrivelse
AccountInfoRequestId Uuid-verdi for et saksnummer hos Skatteetaten.
CorrelationID Uuid-verdi for unik teknisk referanse til forespørselen.
Legal-Mandate Lovhjemmel er: “Skatteforvaltningsloven § 10-2 første ledd, jf. § 10-14, jf. skatteforvaltningsforskriften § 10-2-1”. URL Encoded verdien skal altså være “Skatteforvaltningsloven%20%C2%A7%2010-2%20f%C3%B8rste%20ledd%2C%20jf.%20%C2%A7%2010-14%2C%20jf.%20skatteforvaltningsforskriften%20%C2%A7%2010-2-1”.
PartyID FNR/D-NR eller orgnr til kontrollobjektet.
onlyPrimaryOwner “onlyPrimaryOwner” = “TRUE” eller “FALSE”.
AdditionalReferenceID Ingen data.
AdditionalReferenceIDType Ingen data
RequesterID I tjenesten Skatt-Kontroll skal dette feltet inneholde en representasjon av brukerID til saksbehandleren i Skatteetaten selv om parameteren ikke er obligatorisk teknisk.
Se mer detaljert definisjon i datamodell for DSOP Kontroll API.
fromDate Opptil 10 år før dagens dato.
toDate En dato nyere eller lik fromDate.

Se datamodell for Accounts.

Gyldig forespørsel - Trinn 2b

Etter velykket response fra 2a, skal Skatteetaten bruke endepunktene Account Details, Transactions, Cards og Roles på følgende måte:

Felter Beskrivelse
accountReference Unik referanse til kontoen.
AccountInfoRequestID Samme definisjon som for Accounts.
CorrelationID Samme definisjon som for Accounts.
Legal-Mandate Samme definisjon som for Accounts.
AdditionalReferenceID Samme definisjon som for Accounts.
AdditionalReferenceIDType Samme definisjon som for Accounts.
RequesterID Samme definisjon som for Accounts.
fromDate Samme definisjon som for Accounts.
toDate Samme definisjon som for Accounts.

Se datamodell for:

Utlevering av datafelter per endepunkt

Finansforetakene skal utlevere kontoopplysninger for denne tjenesten iht. gjeldende datamodell for DSOP Kontrollinformasjon API. Se Description of all input- and output parameters in the APIs.


Kategorisering av utlevering av kontoopplysninger på feltnivå:

  • Teknisk obligatorisk: Denne opplysningen skal utleveres, ettersom det er teknisk påkrevet i API-et. Det er viktig å ta hensyn til forkortelsene (M, D og MC) fra datamodellen i DSOP Kontroll API-et når det gjelder utlevering av obligatoriske felter, spesielt der finansforetak ikke har mulighet til å utlevere data.
  • Skal utleveres: Etaten har behov for denne opplysningen, og tjenesten skal derfor utlevere den dersom finansforetaket har informasjonen tilgjengelig.
  • Kan filtreres bort: Etaten har ikke behov for denne opplysningen, og finansforetaket kan velge å utelate den fra utleveringen. Dersom etaten mottar denne opplysningen, skal den slettes.
  • Utleveres ikke: Finansforetak vil ikke levere opplysning gjennom datafeltet.
  • Til vurdering: Denne kategorien brukes for felt som ennå ikke er avklart. Det betyr at det fortsatt pågår en vurdering av om opplysningen skal utleveres eller ikke.


Overordnede prinsipper for utlevering definert i DSOP Kontrollinformasjon fellesstandard vil gjelde for denne tjenesten.

Utlevering for Accounts (Kontoliste):

“Kontoliste” er det første endepunktet etat vil benytte for å få utlevert en liste over konti som tilhører kontrollobjektet. Videre bruk av tjenesten baseres på dette Kontoliste-kallet.

For tjenesten Skatt-Kontroll gjelder følgende utlevering fra Kontoliste:

  • Liste over konti som kontrollobjektet eier eller eide i den gjeldende tidsperioden.
  • Fullstendig liste over konti kontrollobjektet eier og disponerer dersom “onlyPrimaryOwner” = “false”. Det vil være mulig å returnere “accountReference” = “dataNotDelivered” for de konti der Finansforetaket ikke utleverer data via de øvrige endepunktene i tjenesten.


Se gyldig forespørsel for endepunktet Accounts.

Finansforetakene skal utlevere kontoopplysninger fra dette endepunktet etter overordnede prinsipper for utlevering definert i DSOP Kontrollinformasjon fellesstandard.

Videre er retningslinjene for utlevering av data per felt for dette endepunktet beskrevet i tabellen nedenfor, i henhold til kategoriseringen definert i Utlevering av datafelter per endepunkt.

Svar fra Accounts Datautlevering
responseDetails.status Teknisk obligatorisk
responseDetails.message Skal utleveres
   
accounts.status Skal utleveres
accounts.servicer.identifier.countryOfResidence Skal utleveres
accounts.servicer.identifier.value Teknisk obligatorisk
accounts.servicer.identifier.type Teknisk obligatorisk
accounts.servicer.name Skal utleveres
accounts.accountIdentifier Teknisk obligatorisk
accounts.accountReference Teknisk obligatorisk
accounts.type Skal utleveres
accounts.currency Skal utleveres
accounts.primaryOwner.permission Skal utleveres
accounts.primaryOwner.identifier.countryOfResidence Skal utleveres
accounts.primaryOwner.identifier.value Teknisk obligatorisk
accounts.primaryOwner.identifier.type Teknisk obligatorisk
accounts.primaryOwner.name Skal utleveres
accounts.primaryOwner.startDate Skal utleveres
accounts.primaryOwner.endDate Skal utleveres
accounts.name Utleveres ikke
   
links.rel Teknisk obligatorisk
links.href Teknisk obligatorisk

Utlevering for Account Details (Kontodetaljer):

Finansforetakene skal utlevere kontoopplysninger fra dette endepunktet etter overordnede prinsipper for utlevering definert i DSOP Kontrollinformasjon fellesstandard.

For tjenesten Skatt-Kontroll gjelder følgende utlevering fra Kontodetaljer:

  • Konti som kontrollobjektet eier eller eide i den gjeldende tidsperioden.


Videre er retningslinjene for utlevering av data per felt for dette endepunktet beskrevet i tabellen nedenfor, i henhold til kategoriseringen definert i Utlevering av datafelter per endepunkt.

Svar fra AccountDetails Datautlevering
responseDetails.status Teknisk obligatorisk
responseDetails.message Skal utleveres
   
account.status Skal utleveres
account.servicer.identifier.countryOfResidence Skal utleveres
account.servicer.identifier.value Teknisk obligatorisk
account.servicer.identifier.type Teknisk obligatorisk
account.servicer.name Utleveres ikke
account.accountIdentifier Teknisk obligatorisk
account.accountReference Teknisk obligatorisk
account.type Skal utleveres
account.currency Skal utleveres
account.name Skal utleveres
account.balances.creditLineIncluded Skal utleveres
account.balances.amount Skal utleveres
account.balances.creditDebitIdicator Skal utleveres
account.balances.registered Skal utleveres
account.balances.type Skal utleveres
account.balances.creditLineAmount Skal utleveres
account.balances.creditLineCurrency Skal utleveres
account.balances.currency Skal utleveres
account.primaryOwner.permission Skal utleveres
account.primaryOwner.identifier.countryOfResidence Skal utleveres
account.primaryOwner.identifier.value Teknisk obligatorisk
account.primaryOwner.identifier.type Teknisk obligatorisk
account.primaryOwner.name Skal utleveres
account.primaryOwner.startDate Skal utleveres
account.primaryOwner.endDate Skal utleveres
account.startDate Skal utleveres
account.endDate Skal utleveres

Utlevering for Transactions (Transaksjoner):

Finansforetakene skal utlevere kontoopplysninger fra dette endepunktet etter overordnede prinsipper for utlevering definert i DSOP Kontrollinformasjon fellesstandard.

Videre er retningslinjene for utlevering av data per felt for dette endepunktet beskrevet i tabellen nedenfor, i henhold til kategoriseringen definert i Utlevering av datafelter per endepunkt.

Svar fra Transactions Datautlevering
responseDetails.status Teknisk obligatorisk
responseDetails.message Skal utleveres
   
transactions.transactionIdentifier Teknisk obligatorisk
transactions.references.value Skal utleveres
transactions.references.type Skal utleveres
transactions.creditDebitIndicator Skal utleveres
transactions.reversalIndicator Skal utleveres
transactions.status Skal utleveres
transactions.transactionCode.domain Skal utleveres
transactions.transactionCode.family Skal utleveres
transactions.transactionCode.subFamily Skal utleveres
transactions.transactionCode.freeText Skal utleveres
transactions.bookingDate Skal utleveres
transactions.valueDate Skal utleveres
transactions.counterParties.accountIdentifier Skal utleveres
transactions.counterParties.identifier.countryOfResidence Skal utleveres
transactions.counterParties.identifier.value Teknisk obligatorisk
transactions.counterParties.identifier.type Teknisk obligatorisk
transactions.counterParties.name Skal utleveres
transactions.counterParties.type Skal utleveres
transactions.counterParties.postalAddress.postCode Skal utleveres
transactions.counterParties.postalAddress.type Skal utleveres
transactions.counterParties.postalAddress.streetName Skal utleveres
transactions.counterParties.postalAddress.buildingNumber Skal utleveres
transactions.counterParties.postalAddress.townName Skal utleveres
transactions.counterParties.postalAddress.country Skal utleveres
transactions.counterParties.postalAddress.addressLines Skal utleveres
transactions.additionalInfo Skal utleveres
transactions.currencyExchange.originalAmount Skal utleveres
transactions.currencyExchange.sourceCurrency Skal utleveres
transactions.currencyExchange.targetCurrency Skal utleveres
transactions.currencyExchange.unitCurrency Skal utleveres
transactions.currencyExchange.exchangeRate Skal utleveres
transactions.merchant Skal utleveres
transactions.paymentCard.cardIdentifier Teknisk obligatorisk
transactions.paymentCard.holderName Skal utleveres
transactions.paymentCard.startDate Skal utleveres
transactions.paymentCard.expiryDate Skal utleveres
transactions.paymentCard.cardIssuerName Skal utleveres
transactions.paymentCard.type Skal utleveres
transactions.paymentCard.cardStatus Skal utleveres
transactions.paymentCard.versionNumber Skal utleveres
transactions.paymentCard.cardIssuerIdentifier.countryOfResidence Skal utleveres
transactions.paymentCard.cardIssuerIdentifier.value Teknisk obligatorisk
transactions.paymentCard.cardIssuerIdentifier.type Teknisk obligatorisk
transactions.registered Skal utleveres
transactions.amount Skal utleveres
transactions.currency Skal utleveres
   
links.rel Teknisk obligatorisk
links.href Teknisk obligatorisk

Utlevering for Cards (Kort):

Finansforetakene skal utlevere kontoopplysninger fra dette endepunktet etter overordnede prinsipper for utlevering definert i DSOP Kontrollinformasjon fellesstandard.

For tjenesten Skatt-Kontroll gjelder følgende utlevering fra Cards:

  • Dersom kontrollobjektet på en konto, har finansforetaket adgang til å filtrere bort informasjon om øvrige disponenter fra endepunktet Cards.


Videre er retningslinjene for utlevering av data per felt for dette endepunktet beskrevet i tabellen nedenfor, i henhold til kategoriseringen definert i Utlevering av datafelter per endepunkt.

Svar fra Cards Datautlevering
responseDetails.status Teknisk obligatorisk
responseDetails.message Skal utleveres
   
paymentCards.cardIdentifier Teknisk obligatorisk
paymentCards.holderName Skal utleveres
paymentCards.startDate Skal utleveres
paymentCards.expiryDate Skal utleveres
paymentCards.cardIssuerName Skal utleveres
paymentCards.type Skal utleveres
paymentCards.cardStatus Skal utleveres
paymentCards.versionNumber Skal utleveres
paymentCards.cardIssuerIdentifier.countryOfResidence Skal utleveres
paymentCards.cardIssuerIdentifier.value Teknisk obligatorisk
paymentCards.cardIssuerIdentifier.type Teknisk obligatorisk

Utlevering for Roles (Roller):

Finansforetakene skal utlevere kontoopplysninger fra dette endepunktet etter overordnede prinsipper for utlevering definert i DSOP Kontrollinformasjon fellesstandard.

For tjenesten Skatt-Kontroll gjelder følgende utlevering fra Roles:

  • Dersom kontrollobjektet er disponent på en konto, har finansforetaket adgang til å filtrere bort informasjon om øvrige disponenter fra endepunktet Roles.


Videre er retningslinjene for utlevering av data per felt for dette endepunktet beskrevet i tabellen nedenfor, i henhold til kategoriseringen definert i Utlevering av datafelter per endepunkt.

Svar fra Roles Datautlevering
responseDetails.status Teknisk obligatorisk
responseDetails.message Skal utleveres
   
roles.accountRole.permission Skal utleveres
roles.accountRole.identifier.countryOfResidence Skal utleveres
roles.accountRole.identifier.value Teknisk obligatorisk
roles.accountRole.identifier.type Teknisk obligatorisk
roles.accountRole.name Skal utleveres
roles.accountRole.startDate Skal utleveres
roles.accountRole.endDate Skal utleveres

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å levering av overskuddsinformasjon. Implementering av slik logikk er finansforetakenes ansvar.

For å sikre godt kontrollnivå på tvers av finansforetakene, er det beskrevet et sett med anbefalinger om generelle og generiske valideringer i DSOP Kontrollinformasjon fellesstandard og spesifikke valideringer knyttet til tjenesten Skatt-Kontroll.

Generelle og generiske valideringer

Disse er beskrevet på «Generic DSOP Control validations».
Org.nr. til Skatteetaten er 974761076.

Spesifikke valideringer for Skatt-Kontroll

  • Gyldig input-parameter for Skatt-Kontroll:
    • Tilgangstoken fra Maskinporten: Finansforetakene må validere token fra Maskinporten med følgende scope: bits:kontoinformasjon
    • Input parameter for Skatt-Kontroll: Se gjeldende API-spesifikasjon for teknisk beskrivelse: API Specification

For Accounts:

Input parametere Forventet verdi Forslag til validering  
AccountInfoRequestID (M) Uuid referanse til saksnr. Formatet kan valideres. I tillegg kan denne parameteren valideres iht definisjonen i Overall description of the DSOP Control API.  
CorrelationID (M) Uuid verdi til en unik teknisk referanse for forespørselen. Formatet kan valideres. I tillegg kan denne parameteren valideres iht definisjonen i Overall description of the DSOP Control API.  
Legal-Mandate (M) “Skatteforvaltningsloven%20%C2%A710-2%20f%C3%B8rste%20ledd%2C%20jf.%20skatteforvaltningsforskriften%20%C2%A710-2-1” Strengen skal være I ‘encoded’ format og burde valideres iht til Juridiske rammebetingelser Skatt-Kontroll.  
PartyID (M) Kontrollbjektet: Organisasjonsnummer, FNR eller D.NR. Formatet kan valideres.  
OnlyPrimaryOwner (M) “FALSE” eller “TRUE” Formatet kan valideres.  
AdditionalReferenceID (O) Ingen -  
AdditionalReferenceIDType (O) Ingen -  
RequesterID (O) Representasjon av brukerID til saksbehandleren. Verdi finnes i forespørselen.  
fromDate (M) Opptil 10 år før dagens dato. Formatet kan valideres. I tillegg bør verdien også valideres slik at datoen ikke er eldre en 10 år før dagens dato.  
toDate (M) Dagens dato. Formatet kan valideres.  

Se HTTP error codes and specific error situations with associated message codes.

For de andre endepunktene:

Input parametere Forventet verdi Forslag til validering  
AccountReference (M) Uuid referanse til kontonr. -  
AccountInfoRequestID (M) Uuid referanse til saksnr. Samme som for Accounts.  
CorrelationID (M) Uuid verdi til en unik teknisk referanse for forespørselen. Samme som for Accounts.  
Legal-Mandate (M) “Skatteforvaltningsloven%20%C2%A710-2%20f%C3%B8rste%20ledd%2C%20jf.%20skatteforvaltningsforskriften%20%C2%A710-2-1” Samme som for Accounts.  
AdditionalReferenceID (O) Ingen -  
AdditionalReferenceIDType (O) Ingen -  
RequesterID (O) Representasjon av brukerID til saksbehandleren. Samme som for Accounts.  
fromDate (M) Opptil 10 år før dagens dato. Samme som for Accounts.  
toDate (M) Dagens dato. Samme som for Accounts.  

Se HTTP error codes and specific error situations with associated message codes.

Endringslogg

Dato Versjon Endring
03.07.25 1.0 Siden er publisert.