Kunden, Tarife und Abonnements über die API erstellen
Historischer Rückblick – November 2025 bis April 2026 Dieser Artikel wurde nachträglich verfasst und fasst die dokumentierte Erweiterung der API-Ressourcen zusammen.
Historischer Rückblick – November 2025 bis April 2026
Dieser Artikel wurde nachträglich verfasst und fasst die dokumentierte Erweiterung der API-Ressourcen zusammen.
Die API ermöglicht es einem externen System, zentrale Datensätze in Alunta synchron zu halten. Arbeiten Sie mit den Objekten in ihrer natürlichen Reihenfolge: Kunden anlegen oder finden, Tarif mit gültigen Preisen und Intervallen erstellen und anschließend das Abonnement erstellen.
Verwenden Sie für diese Aufrufe das persönliche Token des Teams unter Einstellungen → API. Partner-OAuth ist ein separater Autorisierungsweg für Partnerintegrationen und ändert nicht, wie das API-Token des Teams erstellt oder widerrufen wird.
Kunden und stabile Zuordnungen
Erstellen Sie einen Kunden mit einem Namen; dies ist das einzige Pflichtfeld im OpenAPI-Vertrag. E-Mail, Telefonnummer, Anschrift, Postleitzahl, Ort und country sind optional. Wenn Sie country senden, verwenden Sie einen ISO-3166-1-Alpha-2-Code in Großbuchstaben, zum Beispiel DK; ohne Angabe verwendet der Vertrag standardmäßig das Land des Teams. external_customer_id kann optional die Referenz Ihres Systems enthalten. Speichern Sie sowohl die externe Referenz als auch Aluntas UUID; sie erfüllen unterschiedliche Aufgaben. Verwenden Sie eine externe Referenz nicht für mehrere Kunden, sofern keine ausdrückliche Zuordnungsregel dafür besteht.
Tarife und Intervalle
Lesen Sie zuerst pricing_type des Tarifs aus. Rufen Sie bei einem regulären Tarif seine Verlängerungsintervalle ab und verwenden Sie eine gültige renewal_interval_uuid. Ein gestaffelter Tarif enthält in dieser Sammlung keine Verlängerungsintervallzeilen. Verwenden Sie stattdessen interval und currency des Stufenpreises sowie die für die Erstellung erforderlichen Tarifstufenangaben. Stellen Sie stets sicher, dass Preis, Währung, Preismodell und Zahlungsanbieter zusammenpassen. Ein Tarif beschreibt wiederverwendbar, was verkauft wird. Er ist nicht dasselbe wie der effektive Preis oder das Startdatum eines Kunden.
Das Abonnement
Sind Kunde und Tarif bereit, erstellen Sie das Abonnement mit Tarif-UUID, Kunden-UUID und entweder einer Verlängerungsintervall-UUID oder dem vom Tarif angebotenen Paar aus Intervall und Währung für gestaffelte Tarife. Ein synthetisches Beispiel für einen gestaffelten Tarif kann die fiktiven, nicht existierenden UUIDs {"plan_uuid":"00000000-0000-4000-8000-000000000002","customer_uuid":"00000000-0000-4000-8000-000000000001","interval":1,"currency":"DKK"} verwenden. Maßgeblich sind die aktuellen OpenAPI-Schemas für genaue Feldnamen und spätere Endpunkte für Tarifstufen. Die Antwort ist die stabile Quelle für Abonnement-UUID und Status. Lesen Sie sie nach der Erstellung erneut aus, wenn Ihre Integration Startdatum, Preis oder Zahlungsdetails anzeigen muss.
Bankkonten können über die dokumentierten Endpunkte für Bankkonten erstellt, aktualisiert, ausgelesen und gelöscht werden. So bleibt eine externe Verwaltungsoberfläche oder ERP-Anwendung synchron. Ein Bankkonto anzulegen bewegt kein Geld und ändert den Zahlungsstatus einer Rechnung nicht automatisch.
Fehler und Abgrenzungen
422 kann bedeuten, dass Ländercode, Währung, Intervall oder Zahlungsanbieter nicht zur Anfrage passen. Ein fehlendes Intervall ist kein Grund für den Client, eine Alternative zu erfinden. Lesen Sie Seitennavigation, Feldnamen und Statuswerte in OpenAPI nach und verarbeiten Sie Beträge in der im relevanten Schema dokumentierten Einheit.
Die aktuelle Abfolge sowie Beispiele mit synthetischen UUIDs finden Sie im Leitfaden zur öffentlichen API und zu Webhooks (Markdown-fil, AI-agentvenlig).
Vollständiges Beispiel
Ein externes Vertriebssystem kann zunächst einen Kunden mit external_customer_id: "crm_demo_42" senden, die zurückgegebene UUID speichern und dann die Verlängerungsintervalle des Tarifs abrufen. Hat der Tarif einen EUR-Preis für zwölf Monate, darf der Client das Abonnement weder in DKK noch mit einem vom Tarif nicht angebotenen Intervall erstellen. Speichern Sie nach der Erstellung die Abonnement-UUID und lesen Sie den Status erneut aus. Ein späterer Webhook kann dann sowohl der externen Kunden-ID als auch Aluntas eigenen Referenzen zugeordnet werden.
Existiert ein Kunde bereits, sollte die Integration eine eigene eindeutige Zuordnung verwenden oder die dokumentierte Identität suchen, bevor ein weiterer Kunde angelegt wird. Die API dedupliziert nicht allein anhand des Namens. Wird ein Bankkonto gelöscht, sollte der Client auch geltende Regeln für Standardkonto und Nutzung prüfen; CRUD-Aktionen für Bankkonten sind keine Zahlungsbefehle.
Warum fehlt ein Intervall? Bei einem regulären Tarif fehlt ein gültiger Verlängerungsintervallpreis. Bei einem gestaffelten Tarif ist eine leere Verlängerungsintervallsammlung zu erwarten; lesen Sie die Stufenpreise aus und verwenden Sie Intervall und Währung.
Kann ich einen Tarif ändern, ohne jedes Abonnement zu ändern? Tarifkatalog und bestehendes Abonnement sind verschieden. Lesen Sie die Beschreibung des Endpunkts und die Antwort des Abonnements.
Was soll ich mit 422 tun? Zeigen Sie den Feldfehler an, korrigieren Sie die ungültige Kombination und senden Sie dieselbe Geschäftsabsicht erst dann erneut, wenn die Eingabe gültig ist.
Die Menschen und KI-Helfer hinter den Neuigkeiten
Bo Møller und Emil Højbjerg entwickeln Alunta. Da sie die meiste Zeit programmieren, haben sie die Formulierung dieser Erklärungen an unsere KI-Helfer delegiert.
Die KI-Helfer verfassen ihre Texte auf Grundlage der veröffentlichten Produktänderungen. Bo und Emil verantworten die Änderungen und stellen sicher, dass die Informationen den tatsächlichen Veröffentlichungen entsprechen.
