Die Arcalotl-API

• Eine Basis-URL, pro Community abgegrenzt

  Alle Ressourcen liegen unter https://api.arcalotl.com/v1. Jede Ressource gehört zu der Community, der auch der verwendete API-Key gehört. Eine ID aus einer anderen Community antwortet mit 404 statt 403, Antworten lassen sich also nicht nutzen, um die Daten einer anderen Community abzutasten.

• Bearer-API-Keys mit ausdrücklichen Scopes

  Jede Anfrage trägt einen Authorization-Header mit einem Bearer-Key, den Sie im Dashboard unter Developers und dann API Keys anlegen. Ein Key hält die Scopes, die Sie beim Anlegen gewählt haben, und eine Anfrage ohne den Scope, den eine Route verlangt, antwortet mit 403 und dem Code missing_scope. Der vollständige Key wird genau einmal beim Anlegen gezeigt, danach bleibt nur ein Präfix zur Anzeige gespeichert.

• Lesezugriffe decken die ganze Abrechnung ab

  GET-Endpunkte liefern Abos mit Filtern nach Status und Plan, Pläne mit ihren verschachtelten Abrechnungsplänen, Mitglieder mit ihren Plattform-Identitäten, die aufgelösten Zugänge eines Mitglieds, Einmalkäufe, Rabattcodes mit Einlösezahlen und eine Auswertung mit MRR, aktiven Abonnenten und den jüngsten Neuanmeldungen und Kündigungen.

• Wenige, bewusst gesetzte Schreibzugriffe

  Die Schreibzugriffe decken den kompletten Lebenszyklus eines Abos ab: einen Zahlungslink für einen bestimmten Käufer erstellen, ein Abo zwischen Plänen wechseln, es zum Laufzeitende kündigen oder reaktivieren, den Mitgliederbereich für ein Mitglied öffnen, Ihre eigene Nutzer-ID an ein Mitglied hängen und Webhook-Endpunkte verwalten. Ein Zahlungslink nimmt eine verbundene Plattform-Identität, eine bestehende Mitglieds-ID oder eine Namespace-ID aus Ihrem eigenen System entgegen. Genau so verkauft eine Anwendung unter Ihrer Kontrolle über Arcalotl.

• Paginiert wird über Cursor

  Listen-Endpunkte nehmen einen undurchsichtigen Cursor und ein Limit entgegen, maximal 100 und standardmäßig 25, und geben ein next_cursor zurück. Auf der letzten Seite ist das Feld null oder fehlt. Geben Sie den Wert unverändert zurück: Der innere Aufbau eines Cursors gehört nicht zum Vertrag, bauen oder zerlegen Sie ihn also nicht.

• Idempotency-Keys machen Wiederholungen sicher

  Anfragen zum Kündigen und zum Erstellen von Zahlungslinks nehmen einen Idempotency-Key-Header entgegen. Derselbe Key mit demselben Body innerhalb von 24 Stunden spielt die ursprüngliche Antwort erneut ab und ergänzt Idempotent-Replayed: true. Derselbe Key mit einem anderen Body antwortet mit 422 idempotency_key_reuse, und eine Wiederverwendung, während die erste Anfrage noch läuft, mit 409 request_in_flight. Erzeugen Sie pro logischem Vorgang einen frischen Key.

• Fehler sind Problem-Dokumente nach RFC 9457

  Fehlschläge antworten mit application/problem+json und einem stabilen Feld code, etwa unauthorized, missing_scope, not_found, invalid_request, conflict, not_eligible oder rate_limited. Prüfen Sie auf code. Die Felder title und detail sind für Menschen gedacht und ihre Formulierung kann sich jederzeit ändern.

• Rate Limits stehen in jeder Antwort

  Authentifizierter Verkehr ist pro Key auf 300 Anfragen pro Minute mit einem Burst von 60 begrenzt. Anfragen mit fehlendem oder ungültigem Key sind pro Client-IP auf 20 pro Minute mit einem Burst von 10 begrenzt und beeinflussen erfolgreich authentifizierte Aufrufe nicht. Jede Antwort trägt RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset, und eine 429 ergänzt Retry-After in Sekunden.

• Webhooks folgen der Spezifikation Standard Webhooks

  Jede Zustellung trägt die Header webhook-id, webhook-timestamp und webhook-signature. Die Signatur ist HMAC-SHA256 über die ID, den Zeitstempel und den rohen Body, mit Punkten verbunden, mit dem dekodierten Teil Ihres whsec_-Secrets als Schlüssel. Prüfen Sie gegen den rohen Body, bevor Sie JSON parsen, akzeptieren Sie jedes der durch Leerzeichen getrennten v1-Token, damit eine Rotation des Secrets funktioniert, und weisen Sie Zeitstempel ab, die mehr als fünf Minuten von Ihrer Uhr abweichen.

• Zugestellt wird mindestens einmal, mit Wiederholungen und Auto-Abschaltung

  Jede 2xx zählt als Erfolg. Alles andere wird nach einem festen Zeitplan wiederholt, ungefähr zehn Versuche über rund 2,3 Tage, bevor die Zustellung als erschöpft gilt. Ein Endpunkt mit zehn erschöpften Zustellungen in Folge wird automatisch deaktiviert, und jeder Erfolg setzt diesen Zähler zurück. Eine Community kann bis zu fünf HTTPS-Endpunkte registrieren, das Versuchsprotokoll einsehen und eine einzelne Zustellung erneut einreihen.

• Der Ereignis-Feed deckt ab, was Webhooks verpassen

  GET /v1/events liefert dieselben Umschläge, die Ihre Endpunkte bekommen, neueste zuerst, filterbar nach Typ und nach after_id, sodass Sie einen Checkpoint statt eines Zeitstempels führen können. Projizierte Ereignisse werden 90 Tage aufbewahrt, Zustellprotokolle 30 Tage. Sie können also lange nach dem Verfall eines Zustellprotokolls noch abgleichen.

• Innerhalb einer Version kommt nur etwas dazu

  Die API und der Webhook-Umschlag teilen sich eine Versionsangabe. Innerhalb einer Version bekommen Sie neue Felder, neue optionale Parameter, neue Ereignistypen und neue Endpunkte, und bestehende Felder ändern weder Form noch Bedeutung. Ignorieren Sie Felder, die Sie nicht kennen, dann bricht Ihre Integration an ergänzenden Änderungen nie.

• Der Vertrag ist als OpenAPI 3.1 veröffentlicht

  Der vollständige Vertrag für Anfragen und Antworten ist ein OpenAPI-3.1-Dokument, das die Website ausliefert, und die Referenzseiten werden aus genau diesem Dokument erzeugt. Die Referenz kann also nicht von der Spezifikation abweichen, die Ihr Codegenerator liest.

Scopes für API-Keys