API

API

Digitalkost exponerar ett REST-API som gör det möjligt att integrera systemets data med externa verktyg, BI-plattformar och tredjepartssystem. API:et är versionshanterat och autentiseras via Microsoft Entra ID (tidigare Azure Active Directory).

API:et är avsett för kontrollerade integrationer där data behöver hämtas, bearbetas eller analyseras utanför Digitalkost, till exempel för rapportering, uppföljning eller integration med andra verksamhetssystem.

Obs: API-åtkomst kräver att er organisation har en aktiv Digitalkost-licens och att en klientapplikation har konfigurerats av Seaberry. Kontakta Seaberry innan ni påbörjar integrationsutveckling.

Bas-URL

Samtliga anrop riktas mot:

https://api.prod.digitalkost.se

Alla resurser är prefixade med /api/{DigitalkostTenantID}/v1/. Versionshanteringen säkerställer bakåtkompatibilitet inom samma huvudversion. Ett byte av huvudversion aviseras i förväg. Värdet för DigitalkostTenantID ges i samband med att man får del av sina uppgifter för åtkomst till apiet.

Hälsokontroll

GET https://api.prod.digitalkost.se/health

Denna endpoint kräver ingen autentisering och returnerar 200 OK när tjänsten är tillgänglig. Den kan användas för övervakning, hälsokontroller och upptidskontroller.

Autentisering

API:et använder OAuth 2.0 med Microsoft Entra ID och JWT Bearer-tokens. Samtliga anrop, med undantag för /health och /version, kräver en giltig token i Authorization-headern:

Authorization: Bearer <token>

Autentisering via Microsoft Entra ID innebär att åtkomst kan styras centralt och kopplas till den klientapplikation som har godkänts för integrationen.

Server-till-server-integrationer

För maskin-till-maskin-integrationer utan mänsklig inloggning används Client Credentials-flödet. Seaberry tillhandahåller de uppgifter som krävs för integrationen: klient-ID, klienthemlighet, scope och token-endpoint.

Kontakta Seaberry för att få en klientapplikation konfigurerad för er miljö.

När uppgifterna finns på plats hämtas en token från Microsoft Entra med ett POST-anrop:

curl -s -X POST \
  "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token" \
  -d "grant_type=client_credentials" \
  -d "client_id={klient-id}" \
  -d "client_secret={klient-hemlighet}" \
  -d "scope={scope}"

Seaberry anger vilket tenant-id, klient-id, klient-hemlighet och scope som gäller för er miljö. Svaret innehåller fältet access_token, vilket är det värde som skickas som Bearer-token i efterföljande API-anrop.

Tokens är giltiga i 60 minuter. Implementera token-cache i integrationen för att undvika onödiga anrop till Microsoft Entra.

Obs: Klienthemligheten ska behandlas som en känslig uppgift och får inte sparas i källkod, publika repositories eller oskyddade konfigurationsfiler.

Obs: Utan en konfigurerad klientapplikation från Seaberry avvisas anrop med 401 Unauthorized.

API-dokumentation

En fullständig interaktiv referens med tillgängliga endpoints, parametrar och scheman finns via Swagger UI:

https://api.prod.digitalkost.se/swagger

Swagger UI låter er utforska tillgängliga resurser, se request- och response-format samt provköra anrop direkt i webbläsaren.

Dokumentationen uppdateras i takt med API:et och bör användas som primär teknisk referens vid integrationsutveckling.

Exempel

Nedanstående exempel förutsätter att ni har en giltig Bearer-token lagrad i miljövariabeln TOKEN.

Verifiera token och hämta inloggad användare

Ett enkelt sätt att bekräfta att autentiseringen fungerar är att anropa /api/v1/iam/me. Anropet returnerar information om den inloggade användaren eller klientapplikationen.

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.prod.digitalkost.se/api/v1/iam/me"

Hämta egenkontrollkörningar

Följande exempel hämtar en paginerad lista över egenkontroller för er organisation. Listan kan filtreras med exempelvis siteId, status, from och to vid behov.

Se Swagger UI för samtliga tillgängliga parametrar.

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.prod.digitalkost.se/api/20b989bc-bfad-4d6d-9f1f-6c80630f81ab/v1/egenkontroll/workitems?skip=0&take=25"

Behörigheter

API:et tillämpar en rollbaserad behörighetsmodell med granulära rättigheter per resurs och åtgärd.

Vilka rättigheter en klientapplikation får bestäms av Seaberry vid konfigurationen och är knutna till klientapplikationens identitet i Microsoft Entra.

Detta gör det möjligt att begränsa integrationens åtkomst till de resurser och åtgärder som krävs för det aktuella användningsfallet.

Kontakta Seaberry om behörigheterna för en integration behöver justeras.

Tekniska egenskaper

Tips: Använd Swagger UI som primär referens under integrationsutvecklingen. Dokumentationen uppdateras i takt med systemet och återspeglar den aktuella API-ytan.