API: Überblick und Zugang
Eigene Systeme lesen und schreiben Sortiment und Bestellungen über die REST-API. Zugang über eine Verbindung „Eigenes System (API)“ mit Schlüsseln und Rechten.
Trade Bridge NEO hat eine REST-API. Über sie liest und schreibt ein eigenes System (die eigene Website, ein ERP, eine Kasse) das Sortiment und legt Bestellungen an. Daneben gibt es die B2B-API für Geschäftskunden, siehe B2B-API.
Zugang einrichten
- In Trade Bridge NEO unter Einstellungen → Verbindungen eine neue Verbindung Eigenes System (API) anlegen. Je angebundenem System eine eigene Verbindung.
- Präfix der Bestellnummer und Kanalname festlegen. Bestellungen über die API heißen dann Präfix + Nummer im eigenen System (Standard
API-), der Kanalname steht als Verkaufskanal an der Bestellung. - Auf der Verbindung unter Schlüssel einen Schlüssel anlegen und die Rechte wählen. Der Schlüssel erscheint nur einmal, danach ist nur noch der Anfang sichtbar.
Ein Schlüssel kann jederzeit ausgeschaltet, in seinen Rechten geändert oder gelöscht werden. Wird die Verbindung ausgeschaltet, gelten alle ihre Schlüssel nicht mehr.
Rechte
| Recht | Erlaubt |
|---|---|
catalog:read | Produkte und Varianten lesen, mit Preisen und verfügbarem Bestand |
catalog:write | Produkte und Varianten anlegen und ändern |
orders:read | Bestellungen lesen, mit Positionen und Sendungen |
orders:write | Bestellungen anlegen |
Ein Schlüssel mit orders:read sieht alle Bestellungen, nicht nur die eigenen. Am besten bekommt jedes System nur die Rechte, die es wirklich braucht.
Nicht für KI-Assistenten
Die API ist für die Anbindung von Software gedacht. KI-Assistenten und KI-Agenten (ChatGPT, Claude und andere) werden über den MCP-Server angeschlossen, siehe Anleitung: Die eigene KI per MCP anschließen. Das gilt auch für Umwege über eigene Werkzeugdefinitionen oder Automatisierungsplattformen (AGB Abschnitt 6). Anfragen aus den Netzen von KI-Anbietern lehnt die API mit 403 und dem Code ai_access_requires_mcp ab.
Adresse und Anmeldung
Die Adresse der API steht auf der Verbindung unter „Schlüssel“. Jede Anfrage schickt den Schlüssel im Header mit:
curl https://<adresse-der-api>/v1/products?limit=10 \
-H "Authorization: Bearer tb_api_…"Statt Authorization: Bearer geht auch der Header x-api-key. Anfragen und Antworten sind JSON in UTF-8.
Antworten, Seiten, Fehler
Listen kommen als { "data": [...], "pagination": { "limit", "offset", "count" } }, einzelne Datensätze als { "data": {...} }. Listen werden mit limit (höchstens 100) und offset geblättert. Mit updated_since (Zeitpunkt nach ISO 8601, z. B. 2026-10-01T00:00:00Z) kommen nur Datensätze, die sich seitdem geändert haben, für einen regelmäßigen Abgleich.
Fehler haben immer dieselbe Form:
{ "error": { "code": "missing_permission", "message": "This API key lacks the permission \"orders:write\"." } }| Status | Bedeutung |
|---|---|
| 400 | Anfrage ungültig (Feld fehlt, falscher Wert, unbekanntes Feld) |
| 401 | Schlüssel fehlt, ist falsch oder ausgeschaltet |
| 403 | Schlüssel hat das Recht nicht, ist ein B2B-Schlüssel oder die Anfrage kommt von einem KI-Dienst |
| 404 | Datensatz nicht gefunden |
| 409 | Konflikt, z. B. SKU vergeben oder zu wenig Bestand |
| 422 | Inhalt passt nicht, z. B. unbekannte SKU in einer Bestellung |
Protokoll
Jede Änderung über die API steht mit dem Namen des Schlüssels im Aktivitätsprotokoll des Datensatzes, genau wie Änderungen in der Oberfläche. Die API prüft dabei dieselben Regeln wie die Oberfläche.