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.
Å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.
Den juridiska personen du onboardar. Svaret från /companies innehåller id som används som company_id och X-Company-ID.
Ett bankkonto under ett företag. Kontot identifieras stabilt med bank_id och external_ref, vanligtvis IBAN.
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"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"}'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"
}'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.
POST /public/auth/token/{
"grant_type": "client_credentials",
"scope": "read:ledger read:reporting"
}{
"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.