API-spesifikasjon

Denne siden forklarer endepunktene i KFR og hvordan de brukes i praksis. Den fullstendige, formelle spesifikasjonen (skjemaer, alle responskoder og eksempler) finnes i API-specification v1.4.0.

Bruksmønster

• Finansforetaket autentiserer seg med access token fra Maskinporten (se Onboarding for oppsett).
• Kundeforhold registreres og slettes fortløpende via enkeltregistrering, mens batch benyttes ved førstegangsetablering eller større oppdateringer.
• GET-endepunktene brukes til å verifisere hva som er registrert, både etter enkeltregistrering og batch.

Oversikt over endepunkter

Basis-URL er https://{miljo}.bits.no/kar-ws/api/v1, der {miljo} er preprod.api (test) eller api (produksjon).

Alle endepunkter krever Authorization-header med access token fra Maskinporten (scope bits:kundeforhold.write), samt headerne CorrelationID og CustomerID (sistnevnte gjelder ikke batch, der kundene identifiseres i filen).

Se Datamodell for objektene som returneres/sendes.

Enkeltregistrering

POST /customers/financialInstitutions/{fid}/relationshipType/{type}

Krever headerne CustomerID og CorrelationID. Kan ta et valgfritt JSON-body for å registrere et historisk kundeforhold:

{
  "openDate": "2020-01-01",
  "closeDate": "2020-12-31"
}

Uten body åpnes kundeforholdet fra dagens dato (opprinnelig oppførsel, uendret). Se Endringer i tjenesten for eksempler og testcaser.

Avslutning av kundeforhold

DELETE /customers/financialInstitutions/{fid}/relationshipType/{type}

Avslutter det aktive kundeforholdet av angitt type for kunden (204 ved suksess). Kundeforholdet fjernes ikke fra historikken: det får satt avslutningsdato og returneres deretter med toDate fra GET /relationships. Finnes ikke noe aktivt kundeforhold av angitt type, returneres 404 (KFR-008).

Batch

POST /customers/financialInstitutions/{fid}/batch

Sendes som multipart/form-data med to deler:

• customer_type – DSOPBANK eller DSOPBANKRIGHTTOUSE.
• customers – CSV med identifikatorer, kommaseparert. Hver post kan ha formatet customerId#openDate#closeDate, der begge datoene er valgfrie.

POST https://preprod.api.bits.no/kar-ws/api/v1/customers/financialInstitutions/916960190/batch

=== HEADER ===
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=873380600719114776488944
CorrelationID: 2b6fc544-e708-4887-8425-378733eea631

=== BODY ===
--873380600719114776488944
Content-Disposition: form-data; name="customer_type";

DSOPBANK

--873380600719114776488944
Content-Disposition: form-data; name="customers"; filename="customers.csv";
Content-Type: text/plain

922203687#2019-11-08,958069367#2011-11-05,921785194#2019-10-15,917439389,989181335#2019-01-03,996128768
--873380600719114776488944--

Viktig om boundary: Verdien i boundary skal ikke ha anførselstegn (“) i headeren. Boundary settes normalt automatisk av HTTP-klienten eller programmeringsspråket som brukes. Hvis KFR returnerer 403 på en batch-forespørsel, bør det først kontrolleres om boundary er feil definert i header eller body.

Batch er asynkron: En 201-respons bekrefter at filen er gyldig og mottatt, men dataene er ikke nødvendigvis lest inn i databasen når svaret mottas. Bruk GET-endepunktene til å verifisere innlesningen i etterkant.

KFR leser inn ca. 250 kundeforhold per sekund, og maksimal filstørrelse er 10 MB. Skal det leses inn mer enn 100 000 kundeforhold i løpet av en dag, skal Bits informeres på DSOP@bits.no. Se Onboarding D-3 for anbefalt fremgangsmåte ved førstegangsinnlesning.

Lesing / verifisering

• GET /customers/financialInstitutions/{fid}/ returnerer opplysninger om det angitte finansforetaket dersom kunden har eller har hatt kundeforhold der, inkludert feltet activeAccount (alltid false i KFR, se Datamodell). Endepunktet støtter de valgfrie query-parametrene fromDate og toDate (format YYYY-MM-DD) for å avgrense forespørselen til en periode. Uten disse benyttes dagens dato.
• GET /customers/financialInstitutions/{fid}/relationships returnerer alle registrerte kundeforholdstyper og perioder for kunden hos det angitte finansforetaket, med fromDate/toDate.

Begge GET-endepunktene er altså avgrenset til finansforetaket som er angitt i fid. De brukes ikke til å hente en samlet oversikt over flere finansforetak.

Validering

Gjelder både enkeltregistrering og batch, for perioder angitt med openDate/closeDate:

• Datoformatet er YYYY-MM-DD.
• closeDate kan kun brukes sammen med openDate.
• closeDate kan ikke være før openDate.
• Datoer kan ikke ligge frem i tid (avvises med KFR-010).
• Overlappende perioder for samme kunde, finansforetak og kundeforholdstype er ikke gyldige. I batch avvises overlapp innenfor samme fil med 409 (KFR-011). Ved enkeltregistrering blir kundeforholdet ikke registrert, og tjenesten returnerer 200. Poster i en batch-fil som overlapper med et allerede registrert kundeforhold, blir ikke lest inn uten egen feilmelding, fordi batch-innlesningen er asynkron.
• Et nytt kundeforhold kan starte samme dag som et tidligere kundeforhold ble avsluttet. Dette regnes ikke som overlapp.

Feilkoder

Skriveendepunktene (POST/DELETE) bruker feilkoder med prefiks KFR:

Leseendepunktene (GET) bruker feilkoder med prefiks ERR:

Se fullstendig liste med eksempler i API-specification v1.4.0.