Integrationsguide & autentisering 2.1

Denna dokumentation är avsedd att vara en omfattande guide för våra olika användargrupper, inklusive återförsäljare, leverantörer och andra företagstyper. Finfos API erbjuder en robust och flexibel lösning för hantering och tillgång till kritiska data, anpassad för olika aktörer inom branschen.

Swagger Dokumentation

Finfo tillhandahåller skräddarsydda Swagger-dokumentationer för olika användargrupper:

1. Återförsäljare (Subscriber Documentation)

2. Leverantörer (Supplier Documentation)

3. Övriga företag (Enterprise Documentation)

API-åtkomst och Autentisering

För att säkerställa en säker och effektiv användning av vårt API, använder vi OAuth2 med Password Grant för autentisering. Följande information krävs för att få tillgång:

• Access-token-URL: https://sso.logiq.no/auth/realms/finfo/protocol/openid-connect/token

• Client Id: finfo-api

• Client Secret: [Client secret tillhandahålls separat]

• User: [Användarnamnet tillhandahålls separat]

• Password: [Lösenordet tillhandahålls separat]

• Grant_type: password

• Scope: openid

Exempel på OAuth2-autentisering

Nedan är ett exempel på hur du kan begära en OAuth2-token (Python):

def get_oauth2_params(): return {
'access_token_url': 'https://sso.logiq.no/auth/realms/finfo/protocol/openid-connect/token',
'client_id': 'finfo-api',
'client_secret': '[Client secret]', 
'user': '[Ditt användarnamn]',
'password': '[Ditt lösenord]',
'grant_type': 'password',
'scope': 'openid'
}

Förväntat svar från API (JSON):

{
  "access_token": "[Access token]", 
  "expires_in": 900, 
  "refresh_expires_in": 1800, 
  "refresh_token": "[Refresh token]", 
  "token_type": "Bearer",
  "id_token": "[ID token]", 
  "not-before-policy": 0, 
  "session_state": "[Session state]", 
  "scope": "openid email profile"
}

Tokenhantering

• Tokens är giltiga i 15 minuter.

• Det är förbjudet att generera nya tokens för varje förfrågan.

• För förnyelse, använd refresh_token med client_id, client_secret och grant_type=refresh_token.
  

Hantering av API-begränsningar (Throttling) och Rekommenderad Backoff

För att säkerställa stabil drift och rättvis resursfördelning tillämpar vi hastighetsbegränsningar (rate limits) på API-anrop enligt följande:

• 6 anrop per sekund: Gäller för article, etim, environment och supplier-endpoints.

• 10 anrop per sekund: Gäller för media-endpoints.

Om en klient överskrider dessa gränser returnerar API:et en HTTP 429 Too Many Requests-respons. Klienter förväntas hantera detta genom att implementera exponentiell backoff.

Exponentiell Backoff och Rekommenderad Implementering

Exponentiell backoff innebär att klienten ökar väntetiden mellan omförsök exponentiellt när en begäran nekas på grund av throttling. Detta minskar risken för att omedelbart skicka nya anrop som också blockeras.

Allmänna riktlinjer vid 429 Too Many Requests

1. Vid en 429-respons:

• Vänta minst 1 sekund innan första omförsöket.

• Vid fortsatt 429, fördubbla väntetiden (2 sekunder, sedan 4 sekunder, 8 sekunder osv.).

• Fortsätt öka väntetiden upp till ett maxintervall på 60 sekunder.

• När en begäran lyckas, återställ backoff-tiden till 1 sekund.

2. SSO och Refresh Tokens

• Samma exponentiella backoff-logik gäller vid 429- och 503-svar på autentiseringsförfrågningar, inklusive refresh_token-anrop.

• Starta med en väntetid på 5 sekunder vid 429/503 för refresh_token.

• Fortsätt fördubbla upp till ett maxintervall på 60 sekunder.

• Om en ny access-token kan genereras via ett fungerande refresh-token bör klienten använda den istället för att omedelbart begära en ny.

Python – Hantering av Refresh Tokens med Backoff

import requests
import time

def fetch_with_backoff(url, retries=5, delay=1):
    for _ in range(retries):
        response = requests.get(url)
        
        if response.status != 429:
            return response
        
        print(f"Throttled, retrying in {delay} seconds...")
        time.sleep(delay)
        delay = min(delay * 2, 60)  # Öka exponentiellt upp till 60 sekunder
    
    raise Exception("Max retries exceeded")

def refresh_token(token_url, payload, retries=5, delay=5):
    for _ in range(retries):
        response = requests.post(token_url, json=payload)
        
        if response.status not in [429, 503]:
            return response
        
        print(f"SSO throttled, retrying refresh in {delay} seconds...")
        time.sleep(delay)
        delay = min(delay * 2, 60)  # Exponentiell backoff
    
    raise Exception("Failed to refresh token after multiple attempts")

Versionshantering av Endpoints

För att säkerställa stabilitet och kontinuerlig utveckling av vårt API använder vi en versionshanteringsstrategi som möjliggör både bakåtkompatibilitet och flexibilitet för att introducera nya funktioner.

Versioneringsmodell

Vårt API följer en tvånivåmodell för versionshantering i formatet major.minor (t.ex. v1.0):

• Major-versioner (v1, v2 osv.): Dessa introduceras vid brytande ändringar (Breaking Changes) som kräver att mottagare uppdaterar sin integration för att kunna fortsätta använda API:t.

• Minor-versioner (v1.1, v1.2 osv.): Dessa används för att introducera nya funktioner eller datatillägg som inte påverkar befintliga implementationer.

Vi strävar efter att hålla minor-uppdateringar bakåtkompatibla, vilket innebär att mottagare inte behöver uppdatera sin implementation om de inte vill dra nytta av de nya funktionerna.

Policy för versionuppdatering

• Vid övergång från en minor-version (t.ex. v1.2 → v1.3):

  • Ingen åtgärd krävs av mottagare om de inte önskar ta del av den nya informationen eller funktionaliteten.

  • Dokumentation och changelog uppdateras för att tydligt kommunicera tillägg och förbättringar.

• Vid övergång till en ny major-version (t.ex. v1 → v2):

  • API-klienter bör uppgradera sin integration till den nya versionen inom 12 månader från lansering.

  • Under övergångsperioden kommer båda versionerna att finnas tillgängliga för att underlätta migrering.

Undantag

Det kan finnas fall där vi av affärsmässiga eller operativa skäl introducerar en ny major-version utan tekniska brytande ändringar. Sådana förändringar kommuniceras tydligt i förväg.

Vanliga Serversvar

Förståelse av serversvar är viktigt för effektiv felsökning:

• 200: OK - Begärd data returnerad.

• 204: No Content - Ingen data hittades.

• 403: Forbidden - Åtkomst nekad.

• 404: Not Found - API otillgängligt eller felaktig URL.

• 429: Too Many Calls - API överbelastat.

• 500: Internal Server Error - Serverfel, försök igen senare.

Drift och Underhåll

• API övervakas 24/7 för driftstörningar.

• Eventuella störningar kommuniceras via e-post.

• Produktionssättningar sker normalt utanför arbetstid, men kan förekomma under dagtid.

• API:et uppdateras regelbundet med icke-brytande förändringar för kontinuerlig förbättring och utökning.

Best Practices för integration mot Finfo API

Finfo API är utvecklat för att möjliggöra effektiv, tydlig och modulär hantering av artikeldata inom byggbranschen. Genom att separera olika datatyper i specialiserade endpoints kan varje system som integrerar mot Finfo välja exakt vilken information som behövs – inget mer, inget mindre. Denna arkitektur är en bärande del av Finfos strategi för att möjliggöra högkvalitativ informationsdistribution utan att varje förändring i strukturen ska kräva branschomfattande konsensus

Grundprinciper för integration

Grunden i all integration med Finfo API är endpointen /article. Här finns den mest centrala informationen om varje artikel, alltid identifierad med ett unikt Finfonummer (finfoArticleId). Denna nyckel används sedan för att komplettera artikelbilden genom ytterligare anrop till andra endpoints – till exempel för logistik, media, klimatdata, miljöbedömningar eller tekniska egenskaper.

Strukturen är avsiktligt uppdelad för att varje endpoint ska ha ett tydligt avgränsat ansvar. Vi på Finfo har som princip att artikeldata inte ska blandas in i andra endpoints. Det betyder till exempel att utgåendekoder, logistikfält eller produktstatus enbart finns i /article, och inte i till exempel /media, /climate eller /etim. Detta beslut är strategiskt och tekniskt motiverat: det ger oss ett lättunderhållet och konsekvent API och gör det enklare för integratörer att förstå och förvalta sina flöden.

Systemroller: ERP eller PIM som master

Vid integration med Finfo API är det viktigt att förstå vilket system som ska vara master för artikelinformationen i ert eget ekosystem. Om ERP-systemet är master bör det också vara källan till artikel- och logistikdata. Det säkerställer att e-handelsplattformar eller andra digitala tjänster speglar det faktiska sortimentet som är tillgängligt för försäljning. Om istället ett PIM- eller MDM-system är master, behöver man även där ta ansvar för PLC-data – alltså produktens livscykel. Detta inkluderar utgåendeprocesser, ersättningsartiklar och andra sortimentsförändringar.

PLC – Produktens livscykel

I Finfos datamodell finns två fält som är centrala för att styra en artikels livscykel, utgåendedatum och utgåendekod. Tillsammans ger de en strukturerad väg för att hantera utfasning, ersättningar och rensning.

Följande koder används för att beskriva PLC-status:

Det är mottagarens ansvar att tolka och agera på denna information enligt sin roll i kedjan. Kod 90 är en särskild markör för att indikera att Finfo slutar hantera artikeln överhuvudtaget.

Om GTIN och artikelidentitet

Det är vanligt att flera olika artiklar delar samma GTIN. Finfo hanterar därför varje artikel som unik per leverantör. En artikel identifieras därför säkrast med:

• Finfonummer (finfoArticleId)

• Kombinerad nyckel av leverantörsnummer + leverantörens artikelnummer

Detta gör det möjligt att hålla isär likadana produkter som levereras av olika aktörer, vilket är centralt i en B2B-miljö med parallella leveranskedjor.

Varugruppering – BK04 och BRAVG

Finfo tillhandahåller stöd för branschstandardiserad varugruppering enligt modellen BK04, som är framtagen av Byggmaterialhandlarna (BMH). Dess exklusiva användningsområde är rapportering av statistik till Byggmaterialhandlarna. Alla annan användning av BK04 sker på egen risk.

Varje artikel innehåller två fält kopplade till BK04:

• STATVGRP – den officiella versionen för statistikanvändning

• BRAVG – den version som mottagaren själv kan välja att ligga på

För de som behöver mer flexibilitet och framtidssäkring erbjuder Finfo även kundunik varugruppering, där ni kan koppla egna interna varugrupper mot Finfos. När nya grupper introduceras blir ni informerade och kan göra er egen mappning via API:t.

Varför API:et är uppdelat

Finfos affärsmodell bygger på att utveckla och tillhandahålla informationsprodukter utan att först ha en existerande kundrelation. Istället erbjuder vi olika delar av branschen möjlighet att köpa just den information de behöver. Detta har visat sig vara ett effektivt sätt att finansiera produktutveckling och samtidigt påskynda digitaliseringen av byggbranschen.

Genom att undvika konsensusprocesser i varje utvecklingssteg har Finfo kunnat agera snabbare än många andra aktörer, vilket också resulterat i en av marknadens mest kompletta och kvalitetssäkrade artikelbaser.

Den modulära uppbyggnaden av API:et är alltså inte en teknisk tillfällighet – det är ett medvetet och beprövat sätt att balansera flexibilitet, kontroll och affärsnytta. Det är detta som gör att vi kan erbjuda spetsinformation till hela branschen, utan att någon tvingas ta del av mer än vad de faktiskt behöver.