API-Referenz verwenden

Die Artikel im Bereich Integration und API erklären Integrationskonzepte, typische Workflows und Best Practices auf fachlicher Ebene.

Die API-Referenz ist dagegen die technische Grundlage für die konkrete Implementierung. Sie beschreibt, welche Endpunkte verfügbar sind, welche Parameter erwartet werden, wie Request und Response aufgebaut sind und welche Fehlerfälle auftreten können.

Dieser Artikel erklärt, wie Sie die API-Referenz lesen und effizient für Ihre Integration nutzen.

Was ist die API-Referenz?

Die API-Referenz ist die technische Dokumentation der tebio API.

Sie beschreibt die verfügbaren REST-Endpunkte der Plattform und zeigt, wie externe Systeme mit tebio kommunizieren können.

In der API-Referenz finden Sie unter anderem:

verfügbare Ressourcen und Endpunkte
unterstützte HTTP-Methoden wie GET, POST, PUT, PATCH oder DELETE
erforderliche Path- und Query-Parameter
Request Bodies für schreibende Operationen
Response Bodies für erfolgreiche Antworten
Pflichtfelder und Datentypen
Validierungsregeln
mögliche HTTP-Statuscodes
Fehlerantworten und Fehlercodes
verfügbare Filter, Paginierung und Expand-Parameter

Die API-Referenz ist damit maßgeblich, wenn Sie konkrete API-Aufrufe implementieren.

API-Referenz und Integrationsartikel unterscheiden

Die Integrationsartikel erklären das Warum und Wie auf fachlicher Ebene.

Beispiele:

Wann nutze ich Portal, API oder Hosted Pages?
Wie sieht ein typischer API-Workflow aus?
Wie funktionieren Webhooks?
Wie gehe ich mit Fehlern um?
Wie hängen Portal-Objekte und API-Ressourcen zusammen?

Die API-Referenz beantwortet dagegen technische Fragen wie:

Welcher Endpunkt wird aufgerufen?
Welche Methode wird verwendet?
Welche Parameter sind erlaubt?
Welche Felder sind Pflichtfelder?
Wie sieht der Request Body aus?
Wie sieht die Response aus?
Welche Statuscodes können zurückgegeben werden?
Welche Fehlerantworten sind möglich?

Nutzen Sie daher beide Dokumentationsarten zusammen: Die Integrationsartikel für Architektur und Vorgehensweise, die API-Referenz für die konkrete technische Umsetzung.

Aufbau der API-Referenz

Die API-Referenz ist ressourcenorientiert aufgebaut.

Typische Ressourcen sind zum Beispiel:

Customer
Contact
Address
Product
Option
Order
Subscription
Invoice
Payment
Document
Event History
Webhook
Campaign, sofern das Modul verfügbar ist

Für jede Ressource sind die verfügbaren Endpunkte gruppiert.

Ein typischer Eintrag in der API-Referenz besteht aus mehreren Bereichen.

Endpunkt und HTTP-Methode

Jeder API-Eintrag zeigt, welche HTTP-Methode und welcher Pfad verwendet werden.

Beispiele für typische Muster:

GET /.../{uuid}
POST /...
PATCH /.../{uuid}

Die HTTP-Methode beschreibt die technische Aktion:

Methode	Typische Bedeutung
`GET`	Daten abrufen
`POST`	neue Ressource erstellen oder Prozess auslösen
`PUT`	Ressource vollständig ersetzen, sofern vom Endpunkt unterstützt
`PATCH`	Ressource teilweise aktualisieren, sofern vom Endpunkt unterstützt
`DELETE`	Ressource löschen oder entfernen, sofern fachlich unterstützt

Wichtig: Nicht jede Ressource unterstützt jede Methode. Die verfügbaren Methoden sind in der API-Referenz pro Endpunkt dokumentiert.

Path-Parameter

Path-Parameter sind Bestandteil der URL.

Sie werden häufig verwendet, um eine konkrete Ressource zu identifizieren.

Beispielhaftes Muster:

GET /.../{uuid}

In diesem Beispiel ist {uuid} ein Path-Parameter.

Path-Parameter sind in der Regel verpflichtend, weil der Endpunkt sonst nicht weiß, auf welche Ressource sich der Request bezieht.

Query-Parameter

Query-Parameter stehen am Ende einer URL und beeinflussen, wie Daten gefiltert, sortiert oder erweitert werden.

Typische Anwendungsfälle:

Suche
Filter
Paginierung
Sortierung
Expand-Parameter

Beispielhaftes Muster:

GET /...?limit=50&offset=0

oder:

GET /.../{uuid}?expand=...

Die API-Referenz beschreibt, welche Query-Parameter ein Endpunkt unterstützt und welche Werte erlaubt sind.

Request Body

Bei schreibenden Operationen wie POST, PUT oder PATCH wird häufig ein Request Body verwendet.

Der Request Body enthält die Daten, die Ihr System an tebio übermittelt.

Beispiele:

Kundendaten bei der Erstellung eines Customers
ausgewähltes Produkt und Optionen bei einer Bestellung
neue Eigenschaften bei einer Aktualisierung
Konfigurationsdaten bei einer technischen Ressource

Die API-Referenz zeigt das erwartete JSON-Schema.

Achten Sie besonders auf:

Pflichtfelder
optionale Felder
erlaubte Datentypen
erlaubte ENUM-Werte
verschachtelte Objekte
Listen
Datums- und Zeitformate
maximale Feldlängen
Validierungsregeln

Wenn Pflichtfelder fehlen oder Werte nicht zur fachlichen Konfiguration passen, kann die API den Request mit einem Fehler ablehnen.

Typische Statuscodes in diesem Zusammenhang sind:

400 Bad Request
422 Unprocessable Entity

Response Body

Der Response Body beschreibt, welche Daten tebio zurückgibt.

Bei erfolgreichen Requests enthält die Response häufig:

technische ID der Ressource
Status der Ressource
fachliche Daten
Zeitstempel
Referenzen auf verbundene Ressourcen
Ergebnis eines ausgelösten Prozesses

Beispiele:

ein neu erstellter Customer
eine ausgelöste Bestellung
Details einer Subscription
Rechnungsdaten
Zahlungsstatus
Webhook-Konfiguration

Prüfen Sie in der API-Referenz immer, welche Felder garantiert enthalten sind und welche nur unter bestimmten Bedingungen oder mit bestimmten Expand-Parametern zurückgegeben werden.

Statuscodes und Fehlerantworten

Die API-Referenz dokumentiert, welche Statuscodes ein Endpunkt zurückgeben kann.

Typische Statuscode-Gruppen sind:

Bereich	Bedeutung
`2xx`	Request erfolgreich oder angenommen
`4xx`	Fehler im Request, in der Berechtigung oder im fachlichen Zustand
`5xx`	technischer Fehler oder temporäres Problem

Neben dem HTTP-Statuscode kann die API eine strukturierte Fehlerantwort zurückgeben.

Diese Fehlerantwort hilft Ihrem System, Fehler programmgesteuert auszuwerten.

Achten Sie dabei auf:

maschinenlesbare Fehlercodes
lesbare Fehlermeldungen
betroffene Felder
Validierungsdetails
Hinweise auf Berechtigungen oder Statuskonflikte

Weitere Hinweise finden Sie im Artikel Fehlerbehandlung.

Expand-Parameter verwenden

Einige Endpunkte unterstützen das Laden zusätzlicher verbundener Daten über einen Expand-Parameter.

Beispielhaftes Muster:

GET /.../{uuid}?expand=...

Mit Expand können Detailantworten um zusätzliche Informationen erweitert werden, sofern der jeweilige Endpunkt dies unterstützt.

Typische Einsatzbereiche:

verbundene Detailinformationen mitladen
Ausführungsdaten ergänzen
Dokument- oder Statusinformationen gemeinsam abrufen
eine Portal-ähnliche Detailansicht effizienter aufbauen

Wichtig: Verwenden Sie Expand gezielt. Expand kann Antwortobjekte größer machen und sollte nur für Daten genutzt werden, die Ihr System tatsächlich benötigt.

Die verfügbaren Expand-Werte sind pro Endpunkt in der API-Referenz dokumentiert.

Search-Endpunkte und Paginierung

Viele Ressourcen stellen Search-Endpunkte oder Listenendpunkte bereit.

Diese Endpunkte sind für folgende Anwendungsfälle relevant:

Listenansichten
Synchronisation
Filterung
Reporting
regelmäßige Datenabgleiche

Typische Query-Parameter können sein:

Suchbegriffe
Statusfilter
Datumsfilter
Tenant- oder Client-Filter
Produkt- oder Optionsfilter
Paginierungsparameter
Sortierung

Bei Listenabfragen sollten Sie immer Paginierung berücksichtigen.

Best Practices:

nicht davon ausgehen, dass alle Ergebnisse in einer Response enthalten sind
Paginierung vollständig auswerten
große Synchronisationen in Batches verarbeiten
Rate Limits beachten
Zwischenergebnisse speichern
Wiederaufnahme nach Fehlern ermöglichen

Authentifizierung in der API-Referenz

Für API-Aufrufe benötigen Sie einen API-Schlüssel.

API-Schlüssel werden im tebio Business-Portal erstellt und verwaltet.

Wenn die API-Referenz interaktives Testen unterstützt, müssen Sie den API-Schlüssel in der Oberfläche hinterlegen, bevor Requests ausgeführt werden können.

Wichtig:

Verwenden Sie für Tests nur API-Schlüssel aus der Playground-Umgebung.
Verwenden Sie keine Live-API-Schlüssel für Experimente.
Veröffentlichen Sie API-Schlüssel niemals im Frontend-Code.
Verwenden Sie unterschiedliche API-Schlüssel für unterschiedliche Systeme.
Vergeben Sie nur die Berechtigungen, die für den jeweiligen Integrationsfall erforderlich sind.

Weitere Informationen finden Sie im Artikel API-Schlüssel erstellen.

Interaktives Testen

Je nach bereitgestellter API-Referenz können API-Aufrufe direkt aus dem Browser getestet werden.

Das ist hilfreich, um:

Request Bodies zu prüfen
Pflichtfelder zu verstehen
Beispielantworten zu sehen
Statuscodes nachzuvollziehen
Fehlerantworten zu testen
Integrationsfragen schneller zu klären

Verwenden Sie interaktives Testen nur mit Testdaten und Playground-Schlüsseln.

Wichtig: Auch ein Testaufruf aus der API-Referenz kann Daten in der verbundenen Umgebung erstellen, ändern oder Prozesse auslösen.

OpenAPI-Datei nutzen

Wenn die API-Referenz als OpenAPI-Datei bereitgestellt wird, kann diese Datei auch in Entwicklungswerkzeugen verwendet werden.

Typische Einsatzmöglichkeiten:

Import in API-Clients
Generierung von Client-Code
Validierung von Requests
Erstellung typisierter Datenmodelle
Integration in CI/CD-Prozesse
Abgleich zwischen Implementierung und API-Spezifikation

Typische Werkzeuge sind zum Beispiel:

Postman
Insomnia
OpenAPI Generator
Swagger UI
Stoplight
eigene Code-Generatoren oder Validierungswerkzeuge

Die konkrete Nutzung hängt von Ihrer Entwicklungsumgebung und Programmiersprache ab.

API-Clients verwenden

API-Clients wie Postman oder Insomnia können helfen, Endpunkte manuell zu testen.

Typischer Ablauf:

OpenAPI-Spezifikation importieren.
Umgebung für Playground anlegen.
API-Schlüssel als Variable hinterlegen.
Beispielrequest auswählen.
Request Body anpassen.
Request senden.
Response und Statuscode prüfen.
Fehlerfälle gezielt testen.

API-Clients eignen sich besonders gut für Entwicklung, Fehlersuche und Abstimmung zwischen Fachbereich und Entwicklungsteam.

Code-Generatoren verwenden

Mit Code-Generatoren können aus einer OpenAPI-Spezifikation typisierte API-Clients oder Datenmodelle erzeugt werden.

Das kann hilfreich sein, wenn Ihr Entwicklungsteam:

Typsicherheit benötigt
wiederkehrende API-Aufrufe standardisieren möchte
manuelles Schreiben von Modellen vermeiden möchte
Änderungen an der API schneller erkennen möchte
Request- und Response-Strukturen automatisiert validieren möchte

Prüfen Sie generierten Code immer fachlich und technisch, bevor er produktiv eingesetzt wird.

Nicht jeder generierte Client passt ohne Anpassungen zu Ihren Architektur-, Authentifizierungs- oder Fehlerbehandlungsstandards.

Von der API-Referenz zur Implementierung

Für eine neue Integration empfiehlt sich folgender Ablauf:

Integrationsfall fachlich klären.
Passenden Konzeptartikel lesen.
Relevante Ressourcen in der API-Referenz identifizieren.
Authentifizierung und Berechtigungen prüfen.
Request- und Response-Schema analysieren.
Beispielaufruf im Playground testen.
Fehlerfälle bewusst testen.
Webhooks ergänzen, falls asynchrone Folgeprozesse relevant sind.
Idempotenz und Retry-Strategie implementieren.
Monitoring und Logging einplanen.
Integration erst danach in Live übernehmen.

Beispiel: Bestellung über API vorbereiten

Wenn ein externes System eine Bestellung über die API auslösen soll, sollten Sie in der API-Referenz mindestens die beteiligten Ressourcen prüfen.

Typische Fragen:

Wie wird der Kunde identifiziert?
Muss ein Customer vorher erstellt werden?
Welche Produkt- oder Options-ID wird benötigt?
Welche Zahlungsmethoden sind erlaubt?
Welche Pflichtfelder hat der Order-Request?
Welche Response wird nach erfolgreicher Bestellung zurückgegeben?
Gibt es asynchrone Folgeprozesse?
Welche Webhook-Ereignisse sind relevant?
Welche Fehlercodes können auftreten?

So vermeiden Sie, dass die Implementierung nur den ersten API-Aufruf berücksichtigt, aber spätere Statusänderungen, Zahlungen oder Dokumente nicht verarbeitet.

Typische Fehler vermeiden

Nur Beispiel-Payloads kopieren

Beispiel-Payloads sind hilfreich, ersetzen aber nicht die Prüfung des vollständigen Schemas.

Achten Sie immer auf Pflichtfelder, ENUM-Werte, Validierungsregeln und fachliche Abhängigkeiten.

Live-Umgebung zum Testen verwenden

Interaktive Tests und Entwicklung sollten in der Playground-Umgebung stattfinden.

Live-Schlüssel können echte Kunden, Bestellungen, Zahlungen oder Dokumente betreffen.

Response-Felder ungeprüft voraussetzen

Nicht jedes Feld ist in jeder Response enthalten. Manche Daten hängen von Konfiguration, Status, Berechtigungen oder Expand-Parametern ab.

Fehlercodes ignorieren

Statuscodes und Fehlerantworten sollten programmatisch verarbeitet werden. Andernfalls entstehen instabile Integrationen.

Asynchrone Prozesse übersehen

Ein erfolgreicher API-Aufruf bedeutet nicht immer, dass alle Folgeprozesse abgeschlossen sind.

Nutzen Sie Webhooks und Statusabfragen, wenn Ihr System auf spätere Ergebnisse reagieren muss.

API-Referenz und Portal-Konfiguration getrennt betrachten

Viele API-Aufrufe hängen von Portal-Konfigurationen ab, zum Beispiel Produkte, Preise, Steuern, Zahlungsmethoden, Rechnungseinstellungen oder Webhooks.

Prüfen Sie daher immer, ob die fachliche Konfiguration zur geplanten API-Nutzung passt.

API-Hinweis

Die API-Referenz ist die maßgebliche technische Dokumentation für Endpunkte, Parameter, Request Bodies, Response Bodies, Statuscodes, Fehlerantworten und verfügabe Expand-Optionen.

Dieser Artikel erklärt, wie Sie die API-Referenz effizient lesen und für Ihre Implementierung nutzen.

API-Referenz verwenden

Was ist die API-Referenz?

API-Referenz und Integrationsartikel unterscheiden

Aufbau der API-Referenz

Endpunkt und HTTP-Methode

Path-Parameter

Query-Parameter

Request Body

Response Body

Statuscodes und Fehlerantworten

Expand-Parameter verwenden

Search-Endpunkte und Paginierung

Authentifizierung in der API-Referenz

Interaktives Testen

OpenAPI-Datei nutzen

API-Clients verwenden

Code-Generatoren verwenden

Von der API-Referenz zur Implementierung

Beispiel: Bestellung über API vorbereiten

Typische Fehler vermeiden

Nur Beispiel-Payloads kopieren

Live-Umgebung zum Testen verwenden

Response-Felder ungeprüft voraussetzen

Fehlercodes ignorieren

Asynchrone Prozesse übersehen

API-Referenz und Portal-Konfiguration getrennt betrachten

API-Hinweis

Verwandte Themen