Integration im Überblick
Die tebio Plattform kann über das tebio Business-Portal, über die REST API, über Webhooks und über Hosted Pages in bestehende Systemlandschaften eingebunden werden.
Dieser Artikel gibt einen Überblick über die wichtigsten Integrationsmöglichkeiten und erklärt, wann welche technische Anbindung sinnvoll ist.
Typische Integrationsszenarien sind:
- CRM-Integration
- ERP- oder Buchhaltungsintegration
- eigener Checkout
- eigenes Kundenportal
- eigene App
- Provisioning-System
- Usage-based Billing
- Reporting und Data Warehouse
- Synchronisation von Kunden-, Subscription-, Rechnungs- oder Zahlungsdaten
Grundprinzip
Abschnitt betitelt „Grundprinzip“tebio stellt zentrale Plattformprozesse für Subscription Management, Billing, Payments, Rechnungen, Dokumente und Kommunikation bereit.
Je nach Anwendungsfall können diese Prozesse auf unterschiedliche Weise genutzt werden:
| Zugang | Zweck |
|---|---|
| Business-Portal | Manuelle Bedienung, Konfiguration, Prüfung und Support |
| REST API | Technische Integration und Automatisierung |
| Webhooks | Automatische Benachrichtigung externer Systeme über Ereignisse |
| Hosted Pages | Bereitgestellte Oberflächen für Kunden- oder Vertriebspartnerprozesse |
Viele Integrationen kombinieren mehrere dieser Zugänge. Ein Unternehmen kann zum Beispiel Produkte im Business-Portal konfigurieren, Bestellungen über eine eigene Website per API an tebio übergeben und externe Systeme per Webhook über neue Subscriptions informieren.
Integrationsmethoden
Abschnitt betitelt „Integrationsmethoden“REST API
Abschnitt betitelt „REST API“Die REST API ist die technische Schnittstelle zur tebio Plattform.
Über die API können externe Systeme Daten an tebio übertragen, Plattformprozesse auslösen oder Informationen aus tebio abrufen.
Typische Eigenschaften:
- REST-basierte Schnittstelle
- JSON-Datenformat
- Authentifizierung über API-Schlüssel
- standardisierte HTTP-Methoden und Statuscodes
- ressourcenorientiertes Datenmodell
Typische Anwendungsfälle:
- Kunden aus einem CRM-System erstellen oder aktualisieren
- Bestellungen aus einem eigenen Checkout an tebio übergeben
- Subscriptions aus einem externen System synchronisieren
- Nutzungsdaten für Usage-based Billing übermitteln
- Rechnungs- und Zahlungsdaten in ein ERP-System übertragen
- Dokumente abrufen
- eigene Portale oder Apps auf tebio Daten aufbauen
Die API eignet sich besonders, wenn Prozesse automatisiert oder in eine bestehende Systemlandschaft integriert werden sollen.
Webhooks
Abschnitt betitelt „Webhooks“Webhooks informieren externe Systeme automatisch über Ereignisse in der tebio Plattform.
Während die REST API aktiv von einem externen System aufgerufen wird, sendet tebio bei einem relevanten Ereignis eine Nachricht an eine vorkonfigurierte Ziel-URL.
Typische Eigenschaften:
- asynchrone Ereignisbenachrichtigung
- HTTP POST an eine konfigurierte Webhook-URL
- Ereignisse zu Kunden, Bestellungen, Subscriptions, Rechnungen, Zahlungen oder Dokumenten
- geeignet für nachgelagerte Prozesse in externen Systemen
Typische Anwendungsfälle:
- Provisioning starten, wenn eine Subscription erstellt wurde
- CRM-System aktualisieren, wenn ein Kunde angelegt wurde
- ERP-System informieren, wenn eine Rechnung erstellt wurde
- Zahlungsausfall in einem externen System markieren
- eigenes Kundenportal aktualisieren, wenn ein Dokument erzeugt wurde
- Support- oder Monitoring-Prozesse auslösen
Webhooks sind besonders wichtig, weil viele Prozesse in tebio asynchron ablaufen können. Eine API-Antwort bedeutet daher nicht immer, dass alle Folgeprozesse bereits abgeschlossen sind.
Hosted Pages
Abschnitt betitelt „Hosted Pages“Hosted Pages sind von tebio bereitgestellte Oberflächen im Branding Ihres Unternehmens.
Sie ermöglichen kunden- oder partnerseitige Prozesse, ohne dass dafür ein vollständig eigenes Frontend entwickelt werden muss.
Typische Hosted Pages sind:
- Bestellseiten
- Self-Care / Kundenportal
- Vertriebspartnerportal
- Affiliate Pages
- Kundenregistrierung
Typische Anwendungsfälle:
- Kunden bestellen eine Subscription selbst
- Kunden ändern ihre Zahlungsmethode
- Kunden sehen Rechnungen und Dokumente ein
- Kunden verwalten ihre Subscriptions
- Kunden geben Einwilligungen ab
- Vertriebspartner erfassen Kunden oder Bestellungen
- Affiliate- oder Partnerprozesse werden im eigenen Branding bereitgestellt
Hosted Pages eignen sich besonders, wenn ein Prozess schnell bereitgestellt werden soll und keine vollständig eigene Oberfläche erforderlich ist.
Hinweis: Hosted Pages werden in der Regel über Links, Buttons oder eigene Domains eingebunden. Eine iFrame-Einbindung sollte nur verwendet werden, wenn sie technisch und fachlich für den konkreten Anwendungsfall geeignet ist.
Business-Portal als Teil der Integration
Abschnitt betitelt „Business-Portal als Teil der Integration“Auch bei einer API-zentrierten Integration bleibt das tebio Business-Portal wichtig.
Viele fachliche Einstellungen werden im Portal vorgenommen und anschließend von API, Webhooks und Hosted Pages genutzt.
Dazu gehören zum Beispiel:
- Produkte, Optionen und Preise
- Zahlungsmethoden
- Steuern
- Fakturierung
- Rechnungseinstellungen
- Hosted Pages
- Nachrichtenvorlagen
- Ereignisauswahl
- API-Schlüssel
- Webhooks
- Rollen und Berechtigungen
Das Business-Portal dient außerdem zur Prüfung, Korrektur und Nachvollziehbarkeit von Vorgängen.
Beispiele:
- Support prüft eine Kundenbestellung
- Finance prüft eine Rechnung
- Operations kontrolliert eine fehlgeschlagene Subscription-Erstellung
- Entwickler prüfen Ereignisse oder Webhook-Verarbeitung
Authentifizierung
Abschnitt betitelt „Authentifizierung“Der Zugriff auf die API erfolgt über API-Schlüssel.
API-Schlüssel werden im tebio Business-Portal erstellt und verwaltet. Jeder API-Schlüssel sollte nur die Rollen und Berechtigungen erhalten, die für den jeweiligen Integrationsfall erforderlich sind.
Best Practices:
- Für jedes externe System einen eigenen API-Schlüssel verwenden
- API-Schlüssel nicht in Frontend-Code veröffentlichen
- API-Schlüssel sicher speichern
- Berechtigungen so restriktiv wie möglich vergeben
- nicht mehr benötigte Schlüssel deaktivieren oder löschen
- separate Schlüssel für Test- und Produktivumgebungen verwenden
Weitere Informationen finden Sie im Artikel API-Schlüssel erstellen.
Umgebungen
Abschnitt betitelt „Umgebungen“tebio unterscheidet zwischen Test- und Produktivnutzung.
| Umgebung | Zweck |
|---|---|
| Playground | Entwicklung, Tests und technische Integration |
| Live | Produktiver Betrieb mit echten Kunden, Zahlungen und Dokumenten |
Die Playground-Umgebung dient dazu, API-Aufrufe, Webhooks, Produktkonfigurationen, Bestellprozesse und Zahlungsabläufe zu testen.
Die Live-Umgebung wird für produktive Prozesse mit echten Kunden, echten Zahlungen und rechtsrelevanten Dokumenten verwendet.
Für jede Umgebung sollten separate API-Schlüssel verwendet werden.
Wichtig: Verwenden Sie für Entwicklungs- und Testzwecke keine Live-API-Schlüssel.
Ressourcenmodell
Abschnitt betitelt „Ressourcenmodell“Die API ist ressourcenorientiert aufgebaut.
Zentrale Ressourcen sind unter anderem:
| Ressource | Bedeutung |
|---|---|
| Customer | Kunden und Kundendaten |
| Contact | Kontakte zu Kunden oder Unternehmen |
| Address | Rechnungs-, Liefer- oder Standardadressen |
| Product | Produkte im Produktkatalog |
| Option | Zusatzleistungen, Varianten oder Erweiterungen |
| Order | Bestellungen und Bestellprozesse |
| Subscription | laufende oder wiederkehrende Leistungsbeziehungen |
| Invoice / Receipt | Rechnungen, Quittungen und Abrechnungsdokumente |
| Payment | Zahlungen, Zahlungsstatus und Erstattungen |
| Document | erzeugte oder hochgeladene Dokumente |
| Event History | Ereignisse und Statusänderungen |
| Webhook | Ereignisbenachrichtigungen an externe Systeme |
| Campaign | Kampagnen und automatisierte Massenprozesse, sofern das Modul verfügbar ist |
Die Identifikation von Ressourcen erfolgt über eindeutige technische Kennungen, zum Beispiel UUIDs oder andere systemseitige IDs.
Typische Integrationsarchitektur
Abschnitt betitelt „Typische Integrationsarchitektur“Ein typisches Integrationsszenario kann so aussehen:
- Produkte, Preise, Zahlungsmethoden und Hosted Pages werden im Business-Portal konfiguriert.
- Ein externes CRM-System legt Kunden über die API in tebio an.
- Ein eigener Checkout übermittelt Bestellungen an tebio.
- tebio erstellt daraus Subscriptions, Rechnungen, Quittungen oder Zahlungen.
- tebio sendet Webhook-Ereignisse an externe Systeme.
- Ein ERP-System ruft Rechnungs- oder Zahlungsdaten über die API ab.
- Support- und Finance-Teams prüfen Vorgänge im Business-Portal.
Dieses Zusammenspiel ermöglicht eine klare Trennung:
- Externe Systeme steuern automatisierte Prozesse.
- tebio übernimmt Subscription Management, Billing und Zahlungslogik.
- Das Business-Portal dient für Konfiguration, Prüfung und operative Bearbeitung.
Synchron und asynchron verstehen
Abschnitt betitelt „Synchron und asynchron verstehen“API-Aufrufe sind häufig synchron: Ein externes System sendet eine Anfrage und erhält eine Antwort.
Viele Folgeprozesse in tebio können jedoch asynchron laufen.
Beispiele:
- Zahlungsabwicklung
- Rechnungserstellung
- Dokumentenerzeugung
- Nachrichtenversand
- Webhook-Zustellung
- Folgeprozesse aus Bestellungen
Deshalb sollten Integrationen nicht nur die unmittelbare API-Antwort auswerten, sondern auch Webhooks und Statusabfragen berücksichtigen.
Empfehlung:
- API-Antwort speichern
- relevante IDs im externen System sichern
- Webhooks verarbeiten
- Status über API abrufen, wenn Details benötigt werden
- idempotente Verarbeitung sicherstellen
- Fehlerfälle und Wiederholungen einplanen
Typische Fehler vermeiden
Abschnitt betitelt „Typische Fehler vermeiden“API und Business-Portal nicht getrennt planen
Abschnitt betitelt „API und Business-Portal nicht getrennt planen“Viele Integrationen scheitern nicht an der API, sondern an fehlender fachlicher Konfiguration.
Produkte, Preise, Steuern, Zahlungsmethoden und Rechnungseinstellungen sollten vor der technischen Integration im Business-Portal geprüft werden.
Webhooks nicht vergessen
Abschnitt betitelt „Webhooks nicht vergessen“Wenn externe Systeme auf Änderungen reagieren sollen, sind Webhooks meist besser geeignet als regelmäßiges Polling.
IDs nicht nur temporär verwenden
Abschnitt betitelt „IDs nicht nur temporär verwenden“Speichern Sie relevante tebio IDs in Ihren externen Systemen. Dazu gehören zum Beispiel Kunden-, Bestell-, Subscription- oder Rechnungskennungen.
Live-Schlüssel nicht für Tests verwenden
Abschnitt betitelt „Live-Schlüssel nicht für Tests verwenden“Testen Sie neue Integrationen zunächst im Playground und verwenden Sie dafür separate API-Schlüssel.
Hosted Pages nicht mit API verwechseln
Abschnitt betitelt „Hosted Pages nicht mit API verwechseln“Hosted Pages sind bereitgestellte Oberflächen. Die API ist eine technische Schnittstelle.
Wenn Sie ein eigenes Frontend vollständig selbst steuern möchten, verwenden Sie die API. Wenn Sie schnell bereitgestellte Oberflächen im eigenen Branding nutzen möchten, verwenden Sie Hosted Pages.
API-Hinweis
Abschnitt betitelt „API-Hinweis“Die technische Beschreibung der Endpunkte, Parameter, Request Bodies, Response Bodies, Authentifizierung und Statuscodes finden Sie in der separaten API-Referenz.
Dieser Artikel beschreibt die Integrationslogik auf fachlicher Ebene. Für konkrete Implementierungsdetails ist die API-Referenz maßgeblich.