Zum Hauptinhalt springen

[Erste Schritte - GCW] Erste Schritte mit der GelatoConnect API

Verfasst von Kyle Sawyer

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:

  1. Fügen Sie Ihrer Anfrage den Header X-API-KEY hinzu

  2. Geben Sie Ihren Schlüssel und Ihr Geheimnis im Format key:secret ein.

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": "order",
  "currency": "USD",
  "shippingAddress": {
    "country": "US",
    "firstName": "John",
    "lastName": "Doe",
    "addressLine1": "123 Main St",
    "city": "New York",
    "postCode": "10001",
    "state": "NY",
    "email": "[email protected]",
    "phone": "1234567890"
  },
  "items": [
    {
      "itemReferenceId": "item-123",
      "productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor",
      "quantity": 1,
      "files": [
        {
          "type": "default",
          "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}/order

Fü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-Bestell-ID, die du für spätere Referenz speichern solltest.

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}/cancel

Bestellungen suchen

Finden Sie Bestellungen anhand bestimmter Kriterien:

POST https://api.partner-connect.io/api/{partner-prefix}/search

Versand 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": "Business Card",
  "productVariant": {
    "Size": "Standard",
    "Paper": "Premium Matte",
    "Color": "Full Color Both Sides"
  }
}

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:

  1. Test mit Beispielaufträgen : Erstellen Sie Testaufträge mit kleinen Auflagen und überprüfen Sie, ob sie korrekt in GelatoConnect angezeigt werden.

  2. 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.

  3. Fehlerbehandlung: Erstellen Sie absichtlich ungültige Bestellungen, um Ihre Fehlerbehandlung zu testen.

  4. 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:secret im 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ächste Schritte

Jetzt, da du die Grundlagen der GelatoConnect API verstanden hast, bist du bereit, Folgendes zu tun:

  1. Lesen Sie die vollständige API-Dokumentation für detaillierte Informationen zu den Endpunkten

  2. Erfahren Sie mehr über API‑Best Practices für Authentifizierung, Rate Limits und Fehlerbehandlung

  3. Entdecken Sie die Arbeit mit API-Endpunkten für detaillierte Anwendungsbeispiele

Für zusätzliche Unterstützung bei Ihrer API-Integration wenden Sie sich an unser Support-Team unter [email protected].

Verwandte Artikel
Hat dies deine Frage beantwortet?