Kom i gang med Aluntas offentlige API

Historisk tilbageblik - november 2025
Denne artikel er skrevet efterfølgende og beskriver API-adgangen, som den blev introduceret i perioden.

API’et er forbindelsen mellem Alunta og et system, du selv driver. Brug det til at hente teamets data og til de handlinger, som den aktuelle v1-kontrakt tillader. Den offentlige API-reference og OpenAPI-dokumentet er den autoritative kilde til felter, statusser og svar.

Før du sender den første request

Aktivér API-modulet for teamet, og gå til Indstillinger → API. Opret et personligt API-token ved at angive et navn, og kopiér tokenet, når det vises. Et token er en hemmelighed: læg det i en secret manager eller miljøvariabel, aldrig i kildekode, en URL, logs eller et supporteksempel. Brug en særskilt testkonto, når integrationen afprøves. Partnerintegrationer kan have en separat OAuth-godkendelse; den er ikke det samme som teamets personlige API-token.

API’et bruger /api/v1 som base for v1-endpoints. En minimal request ser sådan ud:

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

Gem de UUID’er, som API’et returnerer, og brug dem ved senere opslag. Interne database-id’er er ikke en offentlig reference og må ikke bruges som stabil nøgle.

Læs kontrakten først

Åbn den offentlige API-reference eller OpenAPI-specifikationen, før du bygger et kald. Se på den konkrete ressources felter, pagination, validering og svar. API’et returnerer beløb i den mindste valutaenhed, hvor kontrakten angiver det, så et eksempel som 10000 DKK normalt betyder 100,00 DKK.

En 401 betyder typisk manglende eller udløbet token. 403 betyder manglende tilladelse eller et API-modul, der ikke er tilgængeligt for teamet. Ved 422 skal du læse feltfejlene og rette requesten. Følg Retry-After ved 429, og gentag kun operationer, der er sikre at gentage.

Når integrationen er i drift

Brug pagination efter den konkrete endpointbeskrivelse, og antag ikke at alle samlinger accepterer de samme filtre. Brug webhooks til hændelser i stedet for at poll’e unødigt, og gør modtageren idempotent. Hold klienten opdateret efter den offentlige changelog og kontraktdokumentet.

Du kan til enhver tid tilbagekalde et personligt token under Indstillinger → API. Det stopper requests, der bruger tokenet; opret et nyt token, og opdatér integrationens secret, hvis forbindelsen skal fortsætte.

Se den aktuelle guide til offentlig API og webhooks (Markdown-fil, AI-agentvenlig) for en samlet opskrift og fejlfinding.

Et sikkert første forløb

Brug først GET /api/v1/ping eller GET /api/v1/me, hvis disse endpoints er tilgængelige for tokenet, og fortsæt derefter med GET /api/v1/customers. Gem response-status og request-id i din egen integration, men aldrig tokenet. Når en collection har flere sider, skal du følge den pagination, som netop den endpoint beskriver; stop først, når der ikke er en næste side.

En test med den fiktive, ikke-eksisterende kunde-UUID 00000000-0000-4000-8000-000000000001 skal kunne tåle både 404 og 422 uden at oprette en ny kunde automatisk. En 404 siger, at ressourcen ikke findes i tokenets teamkontekst. En 422 siger, at data eller handling ikke er gyldig. Vis disse forskelle i din adminflade, så en bruger ved, om adgang eller input skal rettes.

Kan jeg bruge ét token til alle teams? Nej, adgangen er knyttet til teamkonteksten. Vælg den rigtige konto og opret passende adgang.

Er et UUID det samme som et eksternt ID? Nej. UUID’en er Aluntas reference; et valgfrit eksternt ID er dit systems mapping.

Skal alle 5xx-svar gentages? Brug begrænsede retries ved netværksfejl og midlertidige 5xx, men gentag ikke ukritisk en handling, der kan skabe en ny ressource.