Einleitung
Die GelatoConnect API ermöglicht es Ihnen, Ihre Systeme direkt mit GelatoConnect zu verbinden, um Bestellungen aufzugeben, deren Status zu verfolgen und Versanddetails zu verwalten. In diesem Leitfaden erfahren Sie, wie Sie mit der API Erste Schritte machen und Ihre erste Integration umsetzen.
Voraussetzungen
Bevor Sie mit der GelatoConnect API arbeiten, sollten Sie Folgendes bereithalten:
Ihr API-Schlüssel und Ihr Secret (beides erhalten Sie, wenn Sie einen Connector für Ihren Kunden einrichten)
Grundlegendes Verständnis von REST-APIs und HTTP-Methoden
Vertrautheit mit dem JSON-Datenformat
Eine Entwicklungsumgebung, mit der Sie HTTP-Anfragen stellen können
API-Grundlagen
Die GelatoConnect Order Management API basiert auf REST-Prinzipien und verwendet standardisierte HTTP-Methoden, um mit Ressourcen zu interagieren. Alle API-Anfragen müssen über HTTPS erfolgen, und alle Antworten – einschließlich Fehlermeldungen – werden im JSON-Format zurückgegeben.
Basis-URL
Die Basis-URL für die GelatoConnect API lautet:
https://api.partner-connect.io/api/{partner-prefix}/Ihr individueller Partner-Präfix wird Ihnen während des Onboardings mitgeteilt.
Authentifizierung
Alle API-Anfragen müssen Ihre Authentifizierungsdaten im Header enthalten. So authentifizieren Sie sich:
Fügen Sie Ihrer Anfrage den Header
X-API-KEYhinzuGeben Sie Ihren Schlüssel und Ihr Geheimnis im Format
key:secretein.
Beispiel:
X-API-KEY: your-api-key:your-api-secret
So gelingt Ihre erste API-Anfrage
Gehen wir gemeinsam Schritt für Schritt durch, wie Sie mit einer einfachen API-Anfrage eine Bestellung aufgeben können.
1. Bereiten Sie Ihre Bestelldaten vor
Erstellen Sie ein JSON-Objekt mit den Bestelldetails. Hier ist ein einfaches Beispiel:
{"orderReferenceId": "your-order-ref-123","orderType": "Bestellung","currency": "USD","shippingAddress": {"country": "US","firstName": "John","lastName": "Doe","addressLine1": "123 Hauptstraße","city": "New York","postCode": "10001","state": "NY","email": "[email protected]","Telefon": "1234567890"},"Artikel": [{"itemReferenceId": "item-123","productUid": "flat_product_pf_a4_pt_200-g/m²-unbeschichtet_cl_4-0_ct_none_prt_none_sft_none_set_none_hor","Menge": 1,"Dateien": [{"type": "Standard","url": "https://example.com/path/to/printfile.pdf"}]}]}2. Bestellung aufgeben
Senden Sie eine POST-Anfrage an den Endpunkt zum Bestellen:
POST https://api.partner-connect.io/api/{partner-prefix}/orderFügen Sie Ihren Authentifizierungs-Header und die JSON-Bestelldaten in den Anfrage-Body ein.
3. So gehen Sie mit der Antwort um
Wenn alles klappt, erhalten Sie eine Antwort wie diese:
{"id": "32884a3e-bd09-42be-8225-c5cea7d24611","orderReferenceId": "your-order-ref-123","createdAt": "2025-04-12T10:23:28+00:00"}Das Feld id enthält die GelatoConnect-Bestellnummer, die Sie für spätere Rückfragen aufbewahren sollten.
Häufige API-Aktionen
Sobald Sie sich mit der grundlegenden Auftragserstellung sicher fühlen, können Sie weitere API-Funktionen entdecken:
Bestelldetails abrufen
Informationen zu einer bestehenden Bestellung abrufen:
GET https://api.partner-connect.io/api/{partner-prefix}/{orderId}Eine Bestellung stornieren
Stornieren Sie eine Bestellung, die noch nicht versendet wurde:
POST https://api.partner-connect.io/api/{partner-prefix}/{orderId}/cancelBestellungen suchen
Finden Sie Bestellungen anhand bestimmter Kriterien:
POST https://api.partner-connect.io/api/{partner-prefix}/searchVersand aktualisieren
Versanddetails für eine Bestellung ändern:
PUT https://api.partner-connect.io/api/{partner-prefix}/{orderId}Kundenprodukte umsetzen
Statt Produkt-UIDs zu verwenden, können Sie Kundenprodukte nutzen – das ist eine verständlichere und benutzerfreundlichere Lösung:
{"productName": "Visitenkarte","productVariant": {"Größe": "Standard","Papier": "Premium-Matt","Farbe": "Beidseitig vollfarbig"}}Dafür müssen Sie zunächst Kundenprodukte in GelatoConnect einrichten, bevor Sie sie in API-Aufrufen verwenden können.
So testen Sie Ihre Integration
Bevor Sie Ihre Integration veröffentlichen, testen Sie sie gründlich mit diesen Methoden:
Mit Beispielbestellungen testen: Legen Sie Testbestellungen mit kleinen Mengen an und prüfen Sie, ob diese korrekt in GelatoConnect angezeigt werden.
Bestellstatus-Updates überprüfen: Verfolgen Sie Ihre Bestellungen vom Anfang bis zum Ende, damit Ihr System alle Statusänderungen zuverlässig empfängt und verarbeitet.
Fehlerbehandlung: Erstellen Sie absichtlich ungültige Bestellungen, um Ihre Fehlerbehandlung zu testen.
End-to-End-Tests: Durchlaufen Sie den gesamten Bestellprozess von der Aufgabe bis zur Lieferung mit einer kleinen Auswahl an Testbestellungen.
Empfohlene Vorgehensweisen
Um eine optimale Integration mit der GelatoConnect API zu gewährleisten:
Bestell-IDs speichern: Speichern Sie immer die GelatoConnect-Bestell-ID, die Sie als Antwort auf die Auftragserstellung erhalten.
Fehlerbehandlung umsetzen: Sorgen Sie für eine zuverlässige Fehlerbehandlung, damit unerwartete Antworten oder Ausfälle der API souverän gemeistert werden.
Idempotenz nutzen: Erstellen Sie eindeutige Bestellreferenz-IDs, um doppelte Bestellungen zu vermeiden.
Exponential Backoff anwenden: Wenn Sie auf Fehler wegen zu vieler Anfragen (429) stoßen, warten Sie bei jedem weiteren Versuch etwas länger.
API-Nutzung überwachen: Behalten Sie Ihre API-Nutzung im Blick, damit Sie nicht an die Nutzungsgrenzen stoßen.
Häufige Probleme einfach lösen
Authentifizierungsfehler
Wenn Sie eine Fehlermeldung 401 "Nicht autorisiert" erhalten, prüfen Sie bitte Folgendes:
Ihr API-Schlüssel und Ihr Geheimnis sind korrekt.
Das Format ist
key:secretim X-API-KEY-Header.Sie verwenden HTTPS, nicht HTTP
Fehler bei ungültigen Anfragen
Wenn Sie eine 400 Bad Request-Fehlermeldung erhalten:
Prüfen Sie die Fehlermeldung auf Hinweise zu bestimmten Feldern
Stellen Sie sicher, dass alle erforderlichen Felder ausgefüllt sind
Bestätigen Sie, dass das JSON-Format gültig ist
Fehlermeldungen wegen zu vieler Anfragen
Wenn Sie die Fehlermeldung 429 "Zu viele Anfragen" erhalten:
Setzen Sie eine Pausenstrategie ein, um Anfragen mit Abstand zu senden
Wenn möglich, fassen Sie Anfragen zusammen
Überprüfen Sie Ihre Integration auf unnötige Wiederholungen
Nächster Schritt
Jetzt, da Sie die Grundlagen der GelatoConnect API verstanden haben, sind Sie bereit, die vollständige API-Dokumentation mit allen Details zu den Endpunkten zu lesen 🔗 [Auftragseingang – GCW] Order Management API Dokumentation