Kom i gang med Aluntas offentlige API

Historisk tilbakeblikk – november 2025
Denne artikkelen ble skrevet i ettertid og beskriver API-tilgangen slik den ble innført i perioden.

API-et kobler Alunta til et system du drifter. Bruk det til å lese teamdata og utføre handlingene som er tillatt i den gjeldende v1-kontrakten. Den offentlige API-referansen og OpenAPI-dokumentet er autoritative for felter, statuser og svar.

Før den første forespørselen

Aktiver API-modulen for teamet, og gå til Innstillinger → API. Opprett et personlig API-token ved å angi et navn, og kopier deretter tokenet når det vises. Et token er en hemmelighet: Oppbevar det i en hemmelighetsbehandler eller miljøvariabel, aldri i kildekode, en URL, logger eller et støtteksempel. Bruk en separat testkonto mens du utvikler integrasjonen. Partnerintegrasjoner kan ha en egen OAuth-autoriseringsflyt; den er forskjellig fra teamets personlige API-token.

Grunnadressen for v1 er /api/v1. En minimal forespørsel ser slik ut:

GET /api/v1/customers
Authorization: Bearer {access-token}
Accept: application/json

Lagre UUID-ene som API-et returnerer, og bruk dem ved senere oppslag. Interne database-ID-er er ikke offentlige referanser og skal ikke brukes som stabile nøkler.

Les kontrakten først

Åpne den offentlige API-referansen eller OpenAPI-spesifikasjonen før du bygger en forespørsel. Kontroller ressursens felter, paginering, validering og svar. API-beløp angis i minste valutaenhet der kontrakten sier det; for eksempel betyr 10000 DKK vanligvis 100,00 DKK.

401 betyr vanligvis at et token mangler eller er utløpt. 403 betyr utilstrekkelige tillatelser eller at API-modulen ikke er tilgjengelig for teamet. For 422 leser du feltfeilene og korrigerer forespørselen. Følg Retry-After etter 429, og prøv bare handlinger på nytt når det er trygt å gjenta dem.

Når integrasjonen er i drift

Bruk paginering slik den er dokumentert for hvert endepunkt, og ikke anta at alle samlinger godtar de samme filtrene. Bruk webhooks for hendelser i stedet for unødvendig polling, og sørg for at mottakeren er idempotent. Hold klienten oppdatert i tråd med den offentlige endringsloggen og kontraktdokumentasjonen.

Du kan når som helst tilbakekalle et personlig token under Innstillinger → API. Da stoppes forespørsler som bruker tokenet; opprett et nytt token og oppdater integrasjonens hemmelighet hvis tilkoblingen skal fortsette.

Se den gjeldende veiledningen for offentlig API og webhooks (Markdown-fil, AI-agentvenlig) for en fullstendig arbeidsflyt og feilsøking.

En trygg første arbeidsflyt

Start med GET /api/v1/ping eller GET /api/v1/me når disse endepunktene er tilgjengelige for tokenet, og fortsett deretter med GET /api/v1/customers. Lagre svarstatus og en forespørselsidentifikator i integrasjonen, men aldri tokenet. Når en samling har flere sider, følger du pagineringen som er dokumentert for endepunktet, og stopper først når det ikke finnes noen neste side.

En test med den fiktive, ikke-eksisterende kunde-UUID-en 00000000-0000-4000-8000-000000000001 skal håndtere både 404 og 422 uten automatisk å opprette en ny kunde. 404 betyr at ressursen ikke finnes i teamkonteksten til tokenet. 422 betyr at dataene eller handlingen er ugyldige. Vis forskjellen i administrasjonsgrensesnittet, slik at brukeren vet om tilgang eller inndata må korrigeres.

Kan ett token brukes for alle team? Nei. Tilgangen er knyttet til teamkonteksten. Velg riktig konto og opprett passende tilgang.

Er en UUID det samme som en ekstern ID? Nei. UUID-en er Aluntas referanse; en eventuell ekstern ID er koblingen til systemet ditt.

Bør alle 5xx-feil prøves på nytt? Bruk et begrenset antall forsøk ved nettverksfeil og midlertidige 5xx-svar, men ikke gjenta ukritisk en handling som kan opprette en ny ressurs.