Erste Schritte mit der öffentlichen Alunta-API

Historischer Rückblick – November 2025
Dieser Artikel wurde nachträglich verfasst und beschreibt den API-Zugriff zum Zeitpunkt seiner Einführung.

Die API verbindet Alunta mit einem System, das Sie betreiben. Verwenden Sie sie zum Lesen von Teamdaten und für Aktionen, die der aktuelle v1-Vertrag erlaubt. Die öffentliche API-Referenz und das OpenAPI-Dokument sind maßgeblich für Felder, Statuswerte und Antworten.

Vor der ersten Anfrage

Aktivieren Sie das API-Modul für das Team und öffnen Sie Einstellungen → API. Erstellen Sie durch Eingabe eines Namens ein persönliches API-Token und kopieren Sie es, sobald es angezeigt wird. Ein Token ist ein Geheimnis: Bewahren Sie es in einem Secret-Manager oder einer Umgebungsvariablen auf, niemals in Quellcode, URLs, Protokollen oder Supportbeispielen. Verwenden Sie bei der Entwicklung ein separates Testkonto. Partnerintegrationen können einen eigenen OAuth-Autorisierungsablauf haben; dieser ist nicht dasselbe wie das persönliche API-Token des Teams.

Die v1-Basis ist /api/v1. Eine minimale Anfrage sieht so aus:

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

Speichern Sie die von der API zurückgegebenen UUIDs und verwenden Sie sie bei späteren Abfragen. Interne Datenbank-IDs sind keine öffentlichen Referenzen und dürfen nicht als stabile Schlüssel verwendet werden.

Zuerst den Vertrag lesen

Öffnen Sie vor dem Erstellen einer Anfrage die öffentliche API-Referenz oder die OpenAPI-Spezifikation. Prüfen Sie Felder, Seitennavigation, Validierung und Antwort der Ressource. API-Beträge verwenden, wenn im Vertrag angegeben, die kleinste Währungseinheit. Beispielsweise bedeutet 10000 DKK normalerweise 100,00 DKK.

401 weist normalerweise auf ein fehlendes oder abgelaufenes Token hin. 403 bedeutet unzureichende Rechte oder ein für das Team nicht verfügbares API-Modul. Bei 422 lesen Sie die Feldfehler und korrigieren Sie die Anfrage. Beachten Sie nach 429 den Header Retry-After und wiederholen Sie nur Vorgänge, die sicher wiederholt werden können.

Wenn die Integration läuft

Verwenden Sie die für jeden Endpunkt dokumentierte Seitennavigation und gehen Sie nicht davon aus, dass jede Sammlung dieselben Filter akzeptiert. Verwenden Sie Webhooks statt unnötiger Abfragen für Ereignisse und gestalten Sie den Empfänger idempotent. Halten Sie den Client mit öffentlichem Änderungsprotokoll und Vertragsdokumentation aktuell.

Ein persönliches Token können Sie jederzeit unter Einstellungen → API widerrufen. Dadurch werden Anfragen mit diesem Token gestoppt. Soll die Verbindung weiterbestehen, erstellen Sie ein neues Token und aktualisieren Sie das in der Integration gespeicherte Geheimnis.

Den vollständigen Ablauf und Hinweise zur Fehlerbehebung finden Sie im aktuellen Leitfaden zur öffentlichen API und zu Webhooks (Markdown-fil, AI-agentvenlig).

Sicherer erster Ablauf

Beginnen Sie mit GET /api/v1/ping oder GET /api/v1/me, sofern das Token auf diese Endpunkte zugreifen darf, und fahren Sie anschließend mit GET /api/v1/customers fort. Speichern Sie Antwortstatus und Anforderungskennung in Ihrer Integration, niemals das Token. Hat eine Sammlung mehrere Seiten, folgen Sie der für diesen Endpunkt dokumentierten Seitennavigation und stoppen Sie erst, wenn keine weitere Seite existiert.

Eine Anfrage mit der fiktiven, nicht existierenden Kunden-UUID 00000000-0000-4000-8000-000000000001 muss sowohl 404 als auch 422 verarbeiten können, ohne automatisch einen neuen Kunden anzulegen. 404 bedeutet, dass die Ressource im Teamkontext des Tokens nicht existiert. 422 bedeutet, dass Daten oder Aktion ungültig sind. Zeigen Sie den Unterschied in Ihrer Verwaltungsoberfläche, damit klar ist, ob Zugriff oder Eingabe korrigiert werden muss.

Kann ein Token für jedes Team verwendet werden? Nein. Der Zugriff ist an den Teamkontext gebunden. Wählen Sie das richtige Konto und richten Sie den passenden Zugriff ein.

Ist eine UUID dasselbe wie eine externe ID? Nein. Die UUID ist Aluntas Referenz; eine optionale externe ID ordnet den Datensatz Ihrem System zu.

Soll jeder 5xx-Fehler wiederholt werden? Verwenden Sie begrenzte Wiederholungen bei Netzwerkfehlern und vorübergehenden 5xx-Antworten. Wiederholen Sie jedoch nicht blind eine Aktion, die eine neue Ressource erzeugen könnte.