Portal-Objekte und API-Ressourcen
Das tebio Business-Portal und die tebio API arbeiten mit denselben Plattformdaten. Sie stellen diese Daten jedoch unterschiedlich dar.
Das Business-Portal ist prozessorientiert aufgebaut. Es bündelt Informationen so, dass Business-User Kunden, Subscriptions, Bestellungen, Rechnungen, Zahlungen oder Dokumente effizient bearbeiten können.
Die API ist ressourcenorientiert aufgebaut. Sie stellt einzelne fachliche und technische Ressourcen bereit, die von externen Systemen gezielt erstellt, gelesen, aktualisiert oder verarbeitet werden können.
Dieser Artikel erklärt, wie Portal-Objekte und API-Ressourcen zusammenhängen und worauf Sie bei Integrationen achten sollten.
Grundprinzip
Abschnitt betitelt „Grundprinzip“Ein Objekt im Business-Portal entspricht nicht immer genau einer einzelnen API-Ressource.
Häufig zeigt das Portal eine fachliche Ansicht, die mehrere technische Ressourcen kombiniert.
Beispiel:
Eine Kundenansicht im Portal kann folgende Informationen enthalten:
- Kundendaten
- Kontakte
- Adressen
- Subscriptions
- Bestellungen
- Rechnungen
- Zahlungen
- Dokumente
- Einwilligungen
- Eigenschaften
- Ereignisverlauf
- Helpdesk-Tickets
Für Business-User erscheint dies als eine zusammenhängende Kundenansicht. Technisch können diese Informationen jedoch aus mehreren API-Ressourcen stammen.
Business-Portal: prozessorientierte Darstellung
Abschnitt betitelt „Business-Portal: prozessorientierte Darstellung“Das Business-Portal stellt Daten so dar, dass Nutzer konkrete Aufgaben erledigen können.
Beispiele:
- einen Kunden prüfen
- eine Subscription bearbeiten
- eine Bestellung nachvollziehen
- eine Rechnung stornieren
- einen Zahlungseingang prüfen
- ein Dokument einsehen
- ein Helpdesk-Ticket bearbeiten
- Ereignisse zu einem Vorgang nachvollziehen
Dafür bündelt das Portal relevante Informationen aus unterschiedlichen Bereichen.
Eine Portalansicht ist daher häufig eine aggregierte Arbeitsansicht und nicht zwingend eine direkte 1:1-Abbildung einer API-Ressource.
API: ressourcenorientierte Struktur
Abschnitt betitelt „API: ressourcenorientierte Struktur“Die API stellt Plattformobjekte als Ressourcen bereit.
Typische API-Ressourcen sind zum Beispiel:
- Customer
- Contact
- Address
- Product
- Option
- Order
- Subscription
- Invoice
- Receipt
- Payment
- Document
- Event History
- Webhook
- Campaign, sofern das Modul verfügbar ist
Jede Ressource hat eigene Eigenschaften, Statuswerte, Relationen und Berechtigungen.
Über die API können externe Systeme gezielt mit diesen Ressourcen arbeiten, zum Beispiel um Kunden anzulegen, Bestellungen auszulösen, Subscriptions abzurufen oder Rechnungsdaten in ein ERP-System zu übertragen.
Mapping der wichtigsten Portalbereiche
Abschnitt betitelt „Mapping der wichtigsten Portalbereiche“Die folgende Tabelle zeigt, wie zentrale Fachlichkeiten im Portal typischerweise mit API-Ressourcen zusammenhängen.
| Portalbereich | Typische API-Ressourcen | Bedeutung |
|---|---|---|
| Kunden | Customer, Contact, Address, Consent, Property | Kundendaten, Kontakte, Adressen, Einwilligungen und kundenspezifische Eigenschaften |
| Subscriptions | Subscription, Subscription Option, Property, Document, Event History | Laufende Leistungen, Optionen, Eigenschaften, Dokumente und Ereignisse |
| Bestellungen | Order, Customer, Product, Option, Payment, Subscription | Bestellvorgänge und daraus entstehende Folgeprozesse |
| Produkte und Optionen | Product, Option, Price List, Option Group | Produktkatalog, buchbare Optionen, Preise und Konfigurationsregeln |
| Rechnungen und Finanzen | Invoice, Receipt, Payment, Journal, Document | Rechnungen, Quittungen, Zahlungen, Buchungsdaten und Dokumente |
| Helpdesk | Ticket, Comment, Attachment, Customer, Subscription | Support- und Servicevorgänge mit Bezug zu Kunden oder Plattformobjekten |
| Kommunikation | Message, Template, Event, Contact | Nachrichten, Vorlagen, Ereignisse und Empfängerinformationen |
| Vertriebspartner | Salespartner, Customer, Subscription, Commission, Document | Vertriebspartner, vermittelte Kunden, Subscriptions und Provisionsprozesse |
| Entwickler | API Key, Webhook, Event History | technische Zugänge, Ereignisse und Integrationskontrolle |
| Kampagnen | Campaign, Campaign Execution, Event History | Kampagnen, Ausführungen, Zielgruppen und Ausführungsstatus, sofern das Modul verfügbar ist |
Die genaue technische Bezeichnung und Verfügbarkeit einzelner Ressourcen ist in der separaten API-Referenz dokumentiert.
Beispiel: Kundenansicht im Portal
Abschnitt betitelt „Beispiel: Kundenansicht im Portal“Die Kundenansicht im Business-Portal ist ein gutes Beispiel für eine aggregierte Portalansicht.
Ein Business-User sieht dort unter anderem:
- Stammdaten des Kunden
- Rechnungsadresse
- Kontakte
- Subscriptions
- Bestellungen
- Rechnungen
- Zahlungen
- Dokumente
- Nachrichten
- Ereignisverlauf
- Helpdesk-Tickets
Technisch können diese Daten aus mehreren Ressourcen stammen.
Für eine API-Integration bedeutet das:
Wenn ein externes System eine ähnliche Kundenansicht nachbauen möchte, muss es nicht nur die Customer-Ressource abrufen, sondern je nach Anwendungsfall auch verbundene Ressourcen wie Subscriptions, Rechnungen, Zahlungen oder Dokumente berücksichtigen.
Beispiel: Subscription im Portal
Abschnitt betitelt „Beispiel: Subscription im Portal“Auch eine Subscription ist im Portal mehr als nur eine einzelne Zeile.
Eine Subscription kann im Portal Informationen enthalten wie:
- Kunde
- Produkt
- gebuchte Optionen
- Status
- Laufzeit
- Abrechnungsmodell
- Dokumente
- Ereignisverlauf
- Bestellungen
- Rechnungsbezug
- technische oder fachliche Eigenschaften
In der API können diese Informationen auf mehrere Ressourcen und Relationen verteilt sein.
Für Integrationen ist deshalb wichtig, zwischen der eigentlichen Subscription und verbundenen Ressourcen wie Produkt, Optionen, Rechnung, Zahlung oder Event History zu unterscheiden.
Identifikatoren und Referenzen
Abschnitt betitelt „Identifikatoren und Referenzen“API-Ressourcen werden über eindeutige technische Kennungen identifiziert.
Je nach Ressource können zum Beispiel verwendet werden:
- UUIDs
- systemseitige IDs
- Mandantenkennungen
- externe Referenzen
- Kundennummern
- Bestellnummern
- Rechnungsnummern
Eine Ressource referenziert andere Ressourcen in der Regel über technische IDs.
Beispiel:
Eine Subscription speichert nicht den Kundennamen als fachliche Verknüpfung, sondern verweist technisch auf den zugehörigen Customer.
Für Integrationen bedeutet das:
- Speichern Sie relevante tebio IDs in Ihrem externen System.
- Verwenden Sie externe Referenzen, wenn Ihr eigenes System führend für bestimmte Objekte ist.
- Vermeiden Sie Integrationen, die Objekte nur anhand von Namen oder Freitext suchen.
- Berücksichtigen Sie, dass sichtbare Nummern und technische IDs unterschiedliche Zwecke haben können.
Technische ID und fachliche Nummer unterscheiden
Abschnitt betitelt „Technische ID und fachliche Nummer unterscheiden“Im Portal sehen Business-User häufig fachliche Nummern oder lesbare Referenzen, zum Beispiel:
- Kundennummer
- Bestellnummer
- Rechnungsnummer
- Subscription-Nummer
- externe Referenz
In der API werden Ressourcen zusätzlich über technische Kennungen identifiziert.
Diese Unterscheidung ist wichtig:
| Art der Kennung | Zweck |
|---|---|
| Technische ID | eindeutige technische Identifikation einer Ressource |
| Fachliche Nummer | lesbare Nummer für Business-User, Rechnungen, Support oder externe Kommunikation |
| Externe Referenz | Verbindung zu einem Objekt in einem externen System |
Best Practice: Speichern Sie sowohl die technische tebio ID als auch relevante fachliche oder externe Referenzen, wenn Ihr externes System regelmäßig mit tebio kommuniziert.
Relationen zwischen Ressourcen
Abschnitt betitelt „Relationen zwischen Ressourcen“Viele API-Ressourcen sind miteinander verbunden.
Beispiele:
- Ein Customer kann mehrere Subscriptions haben.
- Eine Subscription basiert auf einem Product.
- Eine Subscription kann mehrere Options enthalten.
- Eine Order kann eine Subscription erzeugen.
- Eine Invoice kann sich auf eine oder mehrere Subscriptions beziehen.
- Ein Payment kann mit einer Rechnung oder einem Zahlungsvorgang verbunden sein.
- Ein Document kann mit Kunde, Bestellung, Subscription oder Rechnung verknüpft sein.
- Ein Event History-Eintrag kann sich auf unterschiedliche Entitäten beziehen.
Diese Relationen erklären, warum Portalansichten häufig mehrere API-Ressourcen kombinieren.
Expand-Konzept
Abschnitt betitelt „Expand-Konzept“Da die API ressourcenorientiert aufgebaut ist, wären für zusammenhängende Ansichten theoretisch mehrere API-Aufrufe erforderlich.
Soweit von der jeweiligen Ressource unterstützt, kann ein Expand-Konzept verwendet werden. Dabei werden über einen Query-Parameter zusätzliche verbundene Daten direkt in der Antwort mitgeliefert.
Ein Expand kann zum Beispiel genutzt werden, um Detailinformationen oder verbundene Ausführungen, Dokumente oder Statusinformationen mitzuladen.
Beispielhaftes Prinzip:
GET /.../{uuid}?expand=...Wichtig: Welche Expand-Werte unterstützt werden, hängt von der jeweiligen API-Ressource ab. Die verfügbaren Parameter sind in der API-Referenz dokumentiert.
Search- und Detail-Endpunkte unterscheiden
Abschnitt betitelt „Search- und Detail-Endpunkte unterscheiden“Viele Ressourcen bieten unterschiedliche Zugriffsmuster:
| Zugriffsmuster | Zweck |
|---|---|
| Search | Listen, Filter, Pagination und Suche nach mehreren Objekten |
| Get by ID | Abruf eines konkreten Objekts |
| Create | Erstellen eines neuen Objekts |
| Update | Aktualisieren eines bestehenden Objekts |
| Delete / Deactivate / Cancel | Entfernen, Deaktivieren oder fachliches Beenden eines Objekts, je nach Ressource |
| Action-Endpunkt | Auslösen eines fachlichen Prozesses, zum Beispiel Start, Pause, Storno oder Ausführung |
Für API-Integrationen ist wichtig, nicht nur die Ressource selbst zu verstehen, sondern auch den fachlichen Zweck des jeweiligen Endpunkts.
Ein Search-Endpunkt eignet sich zum Beispiel für Listenansichten oder Synchronisationen. Ein Action-Endpunkt löst dagegen häufig einen Prozess aus, der weitere Folgeprozesse erzeugen kann.
Statuswerte im Portal und in der API
Abschnitt betitelt „Statuswerte im Portal und in der API“Statuswerte werden im Portal häufig in einer für Business-User verständlichen Form angezeigt.
In der API können Statuswerte technischer oder detaillierter sein.
Beispiel:
Im Portal könnte eine Kampagne als Läuft angezeigt werden. Technisch kann die zugehörige Ausführung unterschiedliche Statuswerte haben, zum Beispiel geplant, laufend, pausiert, finalisierend, beendet oder abgebrochen.
Für Integrationen bedeutet das:
- Verwenden Sie die Statuswerte aus der API-Referenz.
- Berücksichtigen Sie Zwischenstatus und asynchrone Verarbeitung.
- Reagieren Sie nicht nur auf den Start eines Prozesses, sondern auch auf spätere Statusänderungen.
- Nutzen Sie Webhooks, wenn externe Systeme auf Statusänderungen reagieren sollen.
Ereignisverlauf und Nachvollziehbarkeit
Abschnitt betitelt „Ereignisverlauf und Nachvollziehbarkeit“Viele Änderungen in tebio erzeugen Ereignisse.
Der Ereignisverlauf ist sowohl im Portal als auch für API-Integrationen relevant.
Typische Ereignisse sind:
- Kunde wurde erstellt oder geändert
- Bestellung wurde verarbeitet
- Subscription wurde erstellt oder geändert
- Rechnung wurde erstellt
- Zahlung war erfolgreich oder ist fehlgeschlagen
- Dokument wurde erzeugt
- Nachricht wurde versendet
- Kampagne wurde gestartet, pausiert oder beendet, sofern das Modul verfügbar ist
Für Business-User ist der Ereignisverlauf eine Nachvollziehbarkeitsfunktion im Portal.
Für API-Nutzer ist er hilfreich, um Prozesse technisch zu prüfen, Fehler zu analysieren oder externe Systeme abzugleichen.
Typische Fehler vermeiden
Abschnitt betitelt „Typische Fehler vermeiden“Portalansicht nicht mit einer einzelnen API-Ressource gleichsetzen
Abschnitt betitelt „Portalansicht nicht mit einer einzelnen API-Ressource gleichsetzen“Eine Portalansicht kann mehrere API-Ressourcen bündeln. Prüfen Sie deshalb bei Integrationen, welche Ressourcen für Ihren Anwendungsfall tatsächlich benötigt werden.
Technische IDs nicht verlieren
Abschnitt betitelt „Technische IDs nicht verlieren“Wenn ein externes System tebio IDs nicht speichert, müssen Objekte später über Suchlogik erneut ermittelt werden. Das ist fehleranfälliger als eine eindeutige Referenzierung.
Fachliche Nummern nicht als technische IDs verwenden
Abschnitt betitelt „Fachliche Nummern nicht als technische IDs verwenden“Kundennummern, Rechnungsnummern oder Bestellnummern sind für Business-Prozesse wichtig. Für API-Aufrufe wird jedoch häufig eine technische ID benötigt.
Expand nicht ungeprüft verwenden
Abschnitt betitelt „Expand nicht ungeprüft verwenden“Expand-Parameter können Integrationen vereinfachen, aber auch größere Antwortobjekte erzeugen. Verwenden Sie Expand gezielt für die Daten, die Ihr System wirklich benötigt.
Asynchrone Folgeprozesse berücksichtigen
Abschnitt betitelt „Asynchrone Folgeprozesse berücksichtigen“Ein API-Aufruf kann einen Prozess starten, dessen Folgeprozesse später abgeschlossen werden. Nutzen Sie Webhooks und Statusabfragen, wenn Ihr System auf vollständige Verarbeitung angewiesen ist.
API-Hinweis
Abschnitt betitelt „API-Hinweis“Dieser Artikel beschreibt das Verhältnis zwischen Portal-Objekten und API-Ressourcen auf fachlicher Ebene.
Die genaue technische Beschreibung der Ressourcen, Endpunkte, Parameter, Expand-Optionen, Request Bodies, Response Bodies und Statuscodes finden Sie in der separaten API-Referenz.