Kom igång med Aluntas publika API

Historisk tillbakablick – november 2025
Den här artikeln skrevs i efterhand och beskriver API-åtkomst så som den infördes under perioden.

API:et kopplar Alunta till ett system som du driver. Använd det för att läsa teamdata och utföra de åtgärder som tillåts av det aktuella v1-kontraktet. Den publika API-referensen och OpenAPI-dokumentet är auktoritativa för fält, statusar och svar.

Innan det första anropet

Aktivera API-modulen för teamet och gå till Inställningar → API. Skapa en personlig API-token genom att ange ett namn och kopiera tokenen när den visas. En token är hemlig: förvara den i en hemlighetshanterare eller miljövariabel, aldrig i källkod, en URL, loggar eller ett supportexempel. Använd ett separat testkonto när du utvecklar integrationen. Partnerintegrationer kan ha ett separat OAuth-auktoriseringsflöde; det skiljer sig från teamets personliga API-token.

Basen för v1 är /api/v1. Ett minimalt anrop ser ut så här:

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

Spara UUID:n som API:et returnerar och använd dem vid senare sökningar. Interna databas-ID:n är inte publika referenser och får inte användas som stabila nycklar.

Läs kontraktet först

Öppna den publika API-referensen eller OpenAPI-specifikationen innan du bygger ett anrop. Kontrollera resursens fält, paginering, validering och svar. API-belopp använder den minsta valutaenheten när kontraktet säger det; till exempel betyder 10000 DKK normalt 100,00 DKK.

401 betyder vanligtvis att en token saknas eller har löpt ut. 403 betyder otillräcklig behörighet eller att teamet inte har API-modulen tillgänglig. För 422 läser du felen för respektive fält och rättar begäran. Följ Retry-After efter 429 och försök endast igen med åtgärder som är säkra att upprepa.

När integrationen körs

Använd den dokumenterade pagineringen för varje ändpunkt och anta inte att alla samlingar godtar samma filter. Använd webhooks i stället för onödig avsökning för händelser och gör mottagaren idempotent. Håll klienten uppdaterad med den publika ändringsloggen och kontraktsdokumentationen.

Du kan när som helst återkalla en personlig token under Inställningar → API. Då stoppas anrop med den tokenen; skapa en ny token och uppdatera integrationens hemlighet om anslutningen ska fortsätta.

Se den aktuella guiden om publikt API och webhooks (Markdown-fil, AI-agentvenlig) för ett fullständigt arbetsflöde och felsökning.

Ett säkert första arbetsflöde

Börja med GET /api/v1/ping eller GET /api/v1/me när tokenen har åtkomst till dessa ändpunkter och fortsätt sedan med GET /api/v1/customers. Spara svarsstatus och en begärandeidentifierare i integrationen, men aldrig tokenen. När en samling har flera sidor följer du den paginering som dokumenterats för ändpunkten och slutar först när det inte finns någon nästa sida.

Ett test med det påhittade, obefintliga kund-UUID:t 00000000-0000-4000-8000-000000000001 ska hantera både 404 och 422 utan att automatiskt skapa en ny kund. 404 betyder att resursen inte finns i tokenens teamkontext. 422 betyder att uppgifterna eller åtgärden är ogiltig. Visa skillnaden i administratörsgränssnittet så att användaren vet om åtkomsten eller indata behöver rättas.

Kan en token användas för alla team? Nej. Åtkomsten är knuten till teamkontexten. Välj rätt konto och skapa lämplig åtkomst.

Är ett UUID samma sak som ett externt ID? Nej. UUID:t är Aluntas referens; ett valfritt externt ID är ditt systems mappning.

Ska varje 5xx-fel provas igen? Använd begränsade nya försök för nätverksfel och tillfälliga 5xx-svar, men upprepa inte blint en åtgärd som kan skapa en ny resurs.