Guider

Praktiska guider för att integrera med Finvis publika API.

Frågor? Kontakta oss på hej@finvis.se
OnboardingLägg till klient, företag och bankkontonRekommenderat flöde när en partnerintegration ska börja hämta bankdata för en ny klient eller ett nytt företag.
Klientmiljö

Åtkomstgränsen för kunddata. API-klienten får bara läsa och skriva data för företag som är kopplade till den klientmiljön.

Företag

Den juridiska personen du onboardar. Svaret från /companies innehåller id som används som company_id och X-Company-ID.

Bankkonto

Ett bankkonto under ett företag. Kontot identifieras stabilt med bank_id och external_ref, vanligtvis IBAN.

1

Begär token med rätt scopes

Använd OAuth2 client credentials. För onboarding behövs write:ledger; för att läsa bankdata behövs read:ledger och ofta read:reporting.

curl -sS -X POST https://api.finvis.se/public/auth/token/ \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -d "grant_type=client_credentials" \
  -d "scope=read:ledger write:ledger read:reporting"
2

Upserta företaget

POST /companies är idempotent på organisationsnummer för API-klienten. Spara id från svaret; det är company_id för alla efterföljande företagsscopade anrop.

curl -sS -X POST https://api.finvis.se/public/companies/ \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: company-5590284682-v1" \
  -H "Content-Type: application/json" \
  -d '{"orgnr":"5590284682","name":"Innovaktiv AB","country":"SE"}'
3

Upserta bankkontot

Skicka X-Company-ID och samma company_id i body. Kontot upsertas med klientmiljö, bank_id och external_ref, så samma konto kan skickas igen utan dubletter.

curl -sS -X POST https://api.finvis.se/public/accounts/ \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "X-Company-ID: ${COMPANY_ID}" \
  -H "Idempotency-Key: account-seb-main-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id":"${COMPANY_ID}",
    "bank_id":"seb",
    "external_ref":"SE1750000000050111084407",
    "external_ref_type":"IBAN",
    "currency":"SEK",
    "status":"active"
  }'
4

Läs bankdata med company header

Alla konto-, saldo-, transaktions- och rapporteringsanrop ska skickas med X-Company-ID. Det gör att samma API-klient kan arbeta säkert med flera företag.

curl -sS "https://api.finvis.se/public/accounts/${ACCOUNT_ID}/transactions?from_date=2026-01-01" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "X-Company-ID: ${COMPANY_ID}"

Kontrakt att följa

  • •Spara id-värdena från API-svaren. Inferera inte ägarskap senare från IBAN eller kontonummer.
  • •X-Company-ID måste tillhöra API-klienten och matcha company_id när body eller query innehåller company_id.
  • •Alla skrivande onboarding-anrop ska ha Idempotency-Key så retries inte skapar dubletter.
  • •Använd read:ledger för bankkonton, saldon och transaktioner; använd write:ledger för att skapa eller uppdatera företag och konton.
API-kontraktFiltrering, paginering och felhanteringPraktiska regler för listanrop, headers, felkoder och retries i produktionsintegrationer.

Headers

Authorization
Obligatorisk för alla skyddade anrop. Skicka Bearer-token från OAuth2 client credentials-flödet.
X-Company-ID
Obligatorisk för företagsscopade bankdata-, rapporterings- och betalningsanrop. Värdet måste vara företagets id från /companies.
Idempotency-Key
Obligatorisk för skrivande endpoints. Använd en stabil unik nyckel per logisk operation, inte per retry.
Content-Type
Skicka application/json för JSON-body. Token-endpointen använder application/x-www-form-urlencoded.

Vanliga filter

from_date / to_date
ISO-datum i formatet YYYY-MM-DD. Använd båda för stabila avgränsade exporter.
page / page_size
page är 1-indexerad. page_size är 100 som standard och max 1000. Återställ page till 1 när filter ändras.
account_id
Begränsar resultat till ett konto inom aktuell X-Company-ID-scope.
direction
Transaktionsfilter med värdena credit eller debit.
currency
ISO 4217-kod, till exempel SEK eller EUR. Aggregat ska alltid tolkas per valuta.
status / balance_type
Endpoint-specifika filter, till exempel kontostatus eller saldotyp. Skicka inte okända värden.

Paginering

Alla listresponser använder samma envelope. count är totalt antal matchande rader, total_pages är antal sidor för vald page_size och results innehåller aktuell sida.

{
  "count": 1234,
  "total_pages": 13,
  "page": 2,
  "page_size": 100,
  "next": "https://api.finvis.se/public/transactions/?page=3",
  "previous": "https://api.finvis.se/public/transactions/?page=1",
  "results": []
}

Felkoder

400 validation_error
Requesten är formellt felaktig eller saknar obligatoriska fält. Läs errors för fältspecifika detaljer.
401 authentication_failed
Token saknas, är ogiltig eller har gått ut. Hämta ny token och försök igen.
403 permission_denied
Token saknar scope eller X-Company-ID är inte åtkomlig för API-klienten.
404 not_found
Objektet finns inte inom aktuell klient- och företagsscope.
409 conflict
Operationen krockar med befintligt tillstånd, ofta idempotency key med annan payload.
429 throttled
Rate limit. Respektera Retry-After eller X-RateLimit-Reset innan retry.

Retries och stabilitet

  • •Retrya 429 och tillfälliga 5xx-fel med exponential backoff och jitter.
  • •Retrya inte 400, 403 eller 404 utan att ändra requesten.
  • •Förnya token före expiry; vid 401, hämta ny token och kör om anropet en gång.
  • •Vid filtrerade listor, håll sortering och filter stabila och följ next-länken när den finns.

Filtrerat listanrop

curl -sS "https://api.finvis.se/public/transactions/?from_date=2026-01-01&to_date=2026-01-31&direction=credit&page=1&page_size=100" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "X-Company-ID: ${COMPANY_ID}"
Skrivande anropIdempotensAlla skrivande endpoints kräver en Idempotency-Key-header för replay-skydd.

Regler

  • 1. Samma nyckel + samma payload returnerar det ursprungliga svaret.
  • 2. Samma nyckel + annan payload returnerar 409 Conflict.
  • 3. Nycklar löper ut efter en retentionsperiod.

Exempel

curl -X POST https://api.finvis.se/public/webhooks/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: 9c1a1c1d-3c02-48b6-8f36-6c58d15f8d30" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhooks/finvis", "event_types": ["transaction.created"]}'
ÅtkomstKlientåtkomst för partnersSå ger du en integration säker åtkomst till rätt klientdata i Finvis.

Arkitektur

Finvis använder en OAuth-klient per partnerintegration och separata företagsscopade anrop med X-Company-ID. Det gör att samma integration kan läsa bankdata för flera klienter och företag utan att behörigheter blandas.

Viktiga punkter

  • • Inga refresh tokens används. Förnya genom att begära ny access token.
  • • Företagsscopade anrop kräver Authorization-header och X-Company-ID-header.
  • • X-Company-ID måste tillhöra API-klienten och företaget som anropet gäller.

Token-flöde

Använd klientuppgifter och scopes för att hämta en access token med rätt behörighet.

Token-endpoint
POST /public/auth/token/
Request
{
  "grant_type": "client_credentials",
  "scope": "read:ledger read:reporting"
}
Svar
{
  "access_token": "....",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:ledger read:reporting"
}

API-anrop

Företagsscopade /public/*-anrop ska inkludera bearer-token och X-Company-ID så anropet kopplas till rätt företagsdata.

curl -sS https://api.finvis.se/public/accounts/ \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "X-Company-ID: ${COMPANY_ID}"

Tokenförnyelse

Inga refresh tokens. Anropa token-endpointen igen före utgångsdatum. Rekommenderat: förnya vid ~55 minuter när expires_in=3600.

Klientisolering

Åtkomst styrs av API-klientens kopplade företag, X-Company-ID och OAuth2-scopes. Ett anrop kan inte läsa data för ett företag som inte är kopplat till klienten.

Skrivbegränsning

POST, PUT och PATCH med partner-tokens returnerar 403 om skrivåtkomst inte har godkänts explicit.