Typischer API-Workflow

Viele Integrationen mit der tebio API folgen einem ähnlichen Grundmuster: Ein externes System übermittelt Kunden-, Bestell- oder Nutzungsdaten an tebio. tebio verarbeitet diese Daten kaufmännisch und informiert das externe System anschließend über Webhooks oder API-Abrufe über relevante Statusänderungen.

Dieser Artikel beschreibt einen typischen API-Workflow für Unternehmen, die tebio mit eigenen Systemen integrieren möchten.

Typische Integrationsszenarien sind:

• eigener Checkout oder eigene App
• eigenes Kundenportal
• CRM-Integration
• ERP- oder Buchhaltungsintegration
• Provisioning-System
• Usage-based Billing
• Datenabgleich mit Drittsystemen

Grundprinzip

Die API wird genutzt, um Prozesse in tebio technisch auszulösen oder Daten aus tebio abzurufen.

Webhooks ergänzen die API, indem sie externe Systeme automatisch über Ereignisse informieren.

Ein typischer Ablauf besteht daher aus drei Teilen:

1. Vorbereitung im Business-Portal: Produkte, Preise, Zahlungsmethoden, Steuern, Fakturierung und Webhooks werden konfiguriert.
2. API-Aufrufe durch das externe System: Kunden, Bestellungen, Subscriptions oder Nutzungsdaten werden übertragen.
3. Asynchrone Rückmeldungen: tebio informiert das externe System über Webhooks oder stellt Statusinformationen per API bereit.

Voraussetzungen

Bevor Sie mit der API-Integration starten, sollten folgende Voraussetzungen erfüllt sein:

• Ein aktives tebio Konto mit gebuchtem Produkt Subscription Management
• Ein API-Schlüssel mit den erforderlichen Rollen und Berechtigungen
• konfigurierte Produkte, Optionen und Preise
• konfigurierte Zahlungsmethoden, sofern Zahlungen über tebio verarbeitet werden sollen
• konfigurierte Steuern und Rechnungseinstellungen
• eingerichtete Webhook-Endpunkte für relevante Ereignisse
• Zugriff auf die technische API-Referenz

Viele fachliche Einstellungen werden nicht in der API selbst vorgenommen, sondern im tebio Business-Portal konfiguriert. Die API nutzt diese Konfiguration anschließend für die Verarbeitung.

Typischer Ablauf im Überblick

Ein typischer API-Workflow für eine neue Subscription sieht vereinfacht so aus:

1. Kunde anlegen oder bestehenden Kunden identifizieren
2. Produkt, Optionen und Preise ermitteln
3. Zahlungsmethode oder Zahlungsmandat vorbereiten
4. Bestellung über die API auslösen
5. Subscription, Rechnung oder Quittung durch tebio erzeugen lassen
6. Webhook-Ereignisse verarbeiten
7. Status, Dokumente oder Zahlungsinformationen abrufen
8. externes System aktualisieren oder Leistung freischalten

Je nach Geschäftsmodell können einzelne Schritte entfallen oder ergänzt werden.

Schritt 1: Kunden anlegen oder identifizieren

Viele API-Prozesse beginnen mit einem Kunden.

Eine Bestellung, Subscription, Rechnung oder Zahlung ist in der Regel einem Kunden zugeordnet. Deshalb muss das externe System entweder einen neuen Kunden in tebio anlegen oder einen bestehenden Kunden eindeutig identifizieren.

Neuer Kunde

Wenn der Kunde noch nicht in tebio existiert, legt das externe System den Kunden über die API an.

Dabei werden je nach Kundentyp unterschiedliche Daten übermittelt, zum Beispiel:

• Kundentyp
• Name oder Firmenname
• E-Mail-Adresse
• Rechnungsadresse
• USt.-ID bei Geschäftskunden
• externe Referenz aus dem CRM- oder ERP-System

Als Antwort erhält das externe System eine eindeutige Kundenkennung, die in den folgenden Schritten verwendet wird.

Bestehender Kunde

Wenn der Kunde bereits existiert, sollte das externe System die tebio Kundenkennung speichern und wiederverwenden.

Alternativ kann der Kunde über Suchparameter identifiziert werden, zum Beispiel über:

• E-Mail-Adresse
• Kundennummer
• externe Referenz
• CRM-ID
• ERP-ID

Best Practice: Speichern Sie die tebio Kundenkennung im führenden externen System, damit spätere API-Aufrufe eindeutig zugeordnet werden können.

Schritt 2: Produkte, Optionen und Preise ermitteln

Damit eine Bestellung ausgelöst werden kann, muss das externe System wissen, welches Produkt gebucht werden soll.

Dazu werden je nach Integration Produktdaten, Optionen und Preislisten aus tebio abgerufen oder vorab im externen System hinterlegt.

Typische Daten sind:

• Produkt-ID
• Options-ID
• Preislisten-ID
• Laufzeit
• Zahlungsstrategie
• Steuerkategorie
• erlaubte Zahlungsmethoden
• externe Produktreferenzen

In vielen Integrationen werden diese Daten nicht bei jeder Bestellung live abgerufen. Stattdessen werden sie regelmäßig synchronisiert und im externen System gespeichert.

Das ist besonders sinnvoll, wenn ein eigener Checkout oder eine eigene App verwendet wird.

Schritt 3: Zahlungsmethode vorbereiten

Je nach Produkt, Zahlungsstrategie und Checkout-Modell muss vor oder während der Bestellung eine Zahlungsmethode vorbereitet werden.

Postpaid

Bei Postpaid-Modellen wird die Leistung häufig zunächst erbracht und später abgerechnet.

Typische Zahlungsmethoden sind:

• Rechnung mit Überweisung
• SEPA-Lastschrift
• externe oder manuell finalisierte Zahlungen

In diesen Fällen ist vor der Bestellung nicht immer ein separater Zahlungsschritt erforderlich.

Prepaid

Bei Prepaid-Modellen bezahlt der Kunde im Voraus. Die Zahlung ist häufig Voraussetzung dafür, dass die Leistung freigeschaltet wird.

Typische Zahlungsmethoden sind:

• Kreditkarte
• PayPal
• andere direkte Online-Zahlungsmethoden

Bei Zahlungsmethoden, die eine aktive Kundenbestätigung erfordern, muss der Checkout-Prozess entsprechend gestaltet werden. Je nach Payment Gateway können Zahlungsmandate, Tokens, Redirects oder andere Zahlungsressourcen beteiligt sein.

Wichtig: Die genaue technische Umsetzung hängt von der verwendeten Zahlungsmethode und der Konfiguration des Payment Gateways ab.

Schritt 4: Bestellung auslösen

Die Bestellung ist in vielen Integrationen der zentrale API-Schritt.

Das externe System übermittelt an tebio, welcher Kunde welches Produkt mit welchen Optionen und Referenzen buchen möchte.

Typische Bestandteile einer Bestellung sind:

• Kundenkennung
• Produktkennung
• ausgewählte Optionen
• Preis- oder Preislistenbezug
• Zahlungsmethode
• Startdatum
• externe Bestellnummer
• externe Referenz
• zusätzliche Eigenschaften oder Metadaten

tebio validiert die Bestellung anhand der bestehenden Plattformkonfiguration.

Dazu gehören unter anderem:

• Produktgültigkeit
• Verkaufszeitraum
• erlaubte Zahlungsmethoden
• Steuerkonfiguration
• Kunden- und Adressdaten
• Pflichtfelder
• Optionsregeln
• Berechtigungen

Wenn die Bestellung erfolgreich verarbeitet wird, kann daraus eine Subscription oder ein anderer Folgeprozess entstehen.

Schritt 5: Subscription und Folgeprozesse verarbeiten

Nach erfolgreicher Bestellung übernimmt tebio die weitere Verarbeitung.

Je nach Produkt- und Abrechnungsmodell können unter anderem folgende Folgeprozesse entstehen:

• Subscription wird erstellt
• Zahlung wird ausgelöst
• Rechnung oder Quittung wird erzeugt
• Dokumente werden erstellt
• Nachrichten werden versendet
• Ereignisse werden protokolliert
• Webhooks werden ausgelöst

Viele dieser Prozesse laufen asynchron. Das bedeutet: Die API-Antwort auf die Bestellung bestätigt nicht zwingend, dass alle Folgeprozesse bereits vollständig abgeschlossen sind.

Deshalb sollten externe Systeme nicht nur auf die unmittelbare API-Antwort vertrauen, sondern zusätzlich Webhooks und Statusabfragen berücksichtigen.

Schritt 6: Webhooks verarbeiten

Webhooks informieren externe Systeme automatisch über Ereignisse in tebio.

Typische Webhook-Ereignisse sind:

• Kunde wurde erstellt oder aktualisiert
• Bestellung wurde erfasst oder verarbeitet
• Subscription wurde erstellt
• Subscription wurde geändert oder gekündigt
• Rechnung wurde erstellt
• Quittung wurde erstellt
• Zahlung war erfolgreich
• Zahlung ist fehlgeschlagen
• Dokument wurde erzeugt
• Helpdesk-Ticket wurde erstellt oder aktualisiert

Ein externes System kann diese Ereignisse nutzen, um Folgeprozesse auszulösen.

Beispiele:

• Zugang in einer SaaS-Anwendung freischalten
• Provisioning für einen Service starten
• CRM-Datensatz aktualisieren
• ERP-System informieren
• Dokument im eigenen Kundenportal anzeigen
• Supportprozess starten
• Zahlungsausfall markieren

Schritt 7: Status und Dokumente abrufen

Nach einem Webhook kann das externe System bei Bedarf weitere Details über die API abrufen.

Typische Abrufe sind:

• Kundendetails
• Bestelldetails
• Subscription-Status
• Rechnungsdetails
• Zahlungsstatus
• Dokumente
• Ereignisverlauf

Dieses Muster ist häufig sinnvoll:

1. tebio sendet Webhook mit Ereignis und Referenz.
2. Externes System prüft die Signatur oder Herkunft des Webhooks.
3. Externes System ruft Details über die API ab.
4. Externes System aktualisiert eigene Daten oder startet einen Folgeprozess.

So bleibt der Webhook schlank, während Detaildaten gezielt über die API abgerufen werden können.

Beispiel: Eigener Checkout mit tebio im Hintergrund

Ein Unternehmen betreibt einen eigenen Checkout und nutzt tebio im Hintergrund für Subscription Management, Billing und Payments.

Typischer Ablauf:

1. Kunde registriert sich im eigenen Checkout.
2. Externes System legt den Kunden über die tebio API an.
3. Externes System zeigt Produkte und Optionen aus tebio oder aus einem synchronisierten Katalog an.
4. Kunde wählt Produkt, Optionen und Zahlungsmethode.
5. Externes System übermittelt die Bestellung an tebio.
6. tebio verarbeitet Bestellung, Subscription, Zahlung und Dokumente.
7. tebio sendet Webhook-Ereignisse an das externe System.
8. Externes System schaltet die Leistung frei oder aktualisiert den eigenen Status.

Dieses Muster eignet sich, wenn die Nutzerführung vollständig im eigenen Frontend bleiben soll, tebio aber die kaufmännische Verarbeitung übernimmt.

Beispiel: CRM-Integration

Ein Unternehmen nutzt ein CRM-System als führendes System für Kundendaten.

Typischer Ablauf:

1. Kunde wird im CRM erstellt oder aktualisiert.
2. CRM übermittelt Kundendaten an tebio.
3. tebio speichert den Kunden und gibt eine Kundenkennung zurück.
4. CRM speichert die tebio Kundenkennung.
5. Spätere Bestellungen oder Subscriptions referenzieren diese Kundenkennung.
6. tebio informiert das CRM über relevante Ereignisse per Webhook.
7. CRM zeigt den aktuellen Status oder relevante Dokumente an.

Dieses Muster eignet sich, wenn Kundendaten außerhalb von tebio geführt werden, tebio aber für Subscription Management und Abrechnung genutzt wird.

Beispiel: Usage-based Billing

Bei Usage-based Billing werden Verbrauchsdaten aus einem externen System an tebio übertragen.

Typischer Ablauf:

1. Produkt und Preismodell werden im Rahmen der Konfiguration vorbereitet.
2. Externes System misst Nutzung, zum Beispiel Minuten, Transaktionen, Datenvolumen oder API-Aufrufe.
3. Externes System übermittelt Verbrauchsdaten regelmäßig an tebio.
4. tebio verarbeitet die Nutzung im passenden Abrechnungszeitraum.
5. Im Rechnungslauf werden die nutzungsbasierten Positionen berücksichtigt.
6. Rechnung und Ereignisse werden erzeugt.
7. Externe Systeme können Status und Dokumente über API oder Webhooks verarbeiten.

Usage-based Billing sollte in der Regel im Rahmen eines Projekts mit tebio abgestimmt werden.

Synchron und asynchron verstehen

Ein häufiger Fehler bei API-Integrationen ist die Annahme, dass alle Folgeprozesse direkt mit der API-Antwort abgeschlossen sind.

Das ist nicht immer der Fall.

Viele Prozesse in tebio können asynchron verarbeitet werden, zum Beispiel:

• Zahlungsabwicklung
• Rechnungserstellung
• Dokumentenerstellung
• Nachrichtenversand
• Webhook-Zustellung
• Folgeprozesse aus Bestellungen

Deshalb sollten Integrationen so gebaut werden, dass sie mit Statusänderungen umgehen können.

Empfehlung:

• API-Antwort speichern
• Webhooks verarbeiten
• Status regelmäßig über API prüfen, wenn erforderlich
• idempotente Verarbeitung sicherstellen
• Fehlerfälle und Wiederholungen einplanen

Typische Fehler vermeiden

IDs nicht im externen System speichern

Wenn externe Systeme tebio IDs nicht speichern, müssen Kunden, Produkte oder Subscriptions später über Suchlogik erneut ermittelt werden.

Besser ist es, relevante tebio Kennungen direkt im externen System zu speichern.

Nur auf die erste API-Antwort reagieren

Die erste API-Antwort bedeutet nicht immer, dass Zahlung, Subscription, Rechnung oder Dokument bereits final verarbeitet sind.

Nutzen Sie Webhooks und Statusabfragen.

Webhooks ohne Idempotenz verarbeiten

Webhook-Ereignisse können erneut zugestellt werden oder in einer anderen Reihenfolge eintreffen als erwartet.

Externe Systeme sollten Ereignisse idempotent verarbeiten und anhand eindeutiger Ereignis- oder Objektkennungen prüfen, ob ein Ereignis bereits verarbeitet wurde.

Produktdaten nicht synchronisieren

Wenn Produkt-, Options- oder Preis-IDs im externen System fehlen oder veraltet sind, können Bestellungen fehlschlagen.

Synchronisieren Sie Produktdaten regelmäßig oder definieren Sie klare Prozesse für Produktänderungen.

Fehlerfälle nicht einplanen

API-Integrationen sollten mit Validierungsfehlern, fehlgeschlagenen Zahlungen, abgelehnten Bestellungen oder technischen Timeouts umgehen können.

Planen Sie dafür Logging, Retry-Strategien und manuelle Klärungsprozesse ein.

API-Hinweis

Die konkreten Endpunkte, Request Bodies, Response Bodies, Statuscodes und Authentifizierungsdetails finden Sie in der separaten API-Referenz.

Für typische API-Workflows sind vor allem folgende Ressourcen relevant:

Ressource	Typische Bedeutung
Customer	Kunden anlegen, suchen oder aktualisieren
Product	Produkte, Optionen und Preise abrufen oder konfigurieren
Order	Bestellungen auslösen und verarbeiten
Subscription	laufende Leistungen abrufen oder verwalten
Payment	Zahlungen starten, prüfen oder erstatten
Invoice / Receipt	Rechnungen, Quittungen und Abrechnungsdokumente abrufen
Document	Dokumente abrufen oder bereitstellen
Webhook	externe Systeme über Ereignisse informieren
Event History	Ereignisse und Statusänderungen nachvollziehen
Usage / Metering	Verbrauchsdaten für Usage-based Billing übermitteln

Verwandte Themen

• Wann nutze ich Portal, API oder Hosted Pages?
• API-Schlüssel erstellen
• Webhooks einrichten
• Events nachvollziehen
• API-Referenz
• Playground
• Hosted Pages einrichten
• Usage-based Billing
• Glossar