Zum Hauptinhalt springen

[Auftragseingang – GCW] Arbeiten mit Order-API-Endpunkten

T
Verfasst von Toby Dawson
Vor über 3 Wochen aktualisiert

In diesem Leitfaden finden Sie praktische Anleitungen und Beispiele für die Arbeit mit den Order-API-Endpunkten von GelatoConnect. Wir zeigen Ihnen, wie Sie Bestellungen aufgeben, stornieren, Versandinformationen aktualisieren, Bestelldetails abrufen und Bestellungen über die API suchen können.

Voraussetzungen

Bevor Sie mit diesen Endpunkten arbeiten, stellen Sie bitte sicher, dass Sie Folgendes haben:

  • Ihr API-Schlüssel und Ihr Geheimnis (werden bereitgestellt, wenn Sie einen Connector für Ihren Kunden einrichten)

  • Die Basis-URL für Ihre API-Endpunkte

  • Grundkenntnisse im Umgang mit HTTP-Anfragen per curl oder einem anderen bevorzugten Tool

Bestellung absenden

Mit dem Submit Order-Endpunkt können Sie in GelatoConnect eine neue Bestellung aufgeben.

Endpunkt: POST /{submitOrderUrl}

Beispiel anfordern

# Bestellung einfach aufgebencurl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \--header 'Content-Type: application/json' \--header "X-API-KEY: Ihr-Schlüssel:Ihr-Geheimnis" \--data '{ "orderReferenceId": "IHRE-BESTELLUNG-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": "123-456-7890" }, "items": [ { "itemReferenceId": "ITEM-001", "productUid": "flat_product_pf_a4_pt_200-g-m2-unbeschichtet_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantity": 1, "Dateien": [ { "type": "Standard", "url": "https://example.com/files/printfile.pdf" } ] } ]}'

Beispiel für eine Antwort

{ "id": "32884a3e-bd09-42be-8225-c5cea7d24611", "orderReferenceId": "IHRE-BESTELLUNG-123", "createdAt": "13.04.2025 10:23:28"}

Verwendung von personalisierten Produkten

Anstatt eine productUid anzugeben, können Sie auch Kundenprodukte mit productName und productVariant verwenden:

curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \--header "Content-Type: application/json" \--header "X-API-KEY: Ihr-Schlüssel:Ihr-Geheimnis" \--data '{ "orderReferenceId": "IHRE-BESTELLUNG-124", "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": "123-456-7890" }, "items": [ { "itemReferenceId": "ITEM-001", "productName": "Visitenkarte", "productVariant": { "Größe": "Standard", "Paper": "Premium Matt", "Farbe": "Beidseitig vollfarbig" }, "quantity": 100, "Dateien": [ { "type": "Vorderseite", "url": "https://example.com/files/front.pdf" }, { "type": "Rückseite", "url": "https://example.com/files/back.pdf" } ] } ]}'

Internationale Bestellungen

Für internationale Bestellungen geben Sie bitte die Einzelhandelspreise für die Zollanmeldung an:

curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \--header "Content-Type: application/json" \--header "X-API-KEY: your-key:your-secret" \--data '{ "orderReferenceId": "INTL-ORDER-456", "orderType": "Bestellung", "currency": "EUR", "retailCurrency": "GBP", "retailShippingPriceInclVat": 6,99, "shippingAddress": { "country": "DE", "firstName": "Hans", "lastName": "Schmidt", "addressLine1": "Unter den Linden 10", "city": "Berlin", "postCode": "10117", "email": "[email protected]", "phone": "+49123456789" }, "items": [ { "itemReferenceId": "ITEM-001", "productUid": "flat_product_pf_a4_pt_200-g-m2-unbeschichtet_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "Menge": 1, "retailPriceInclVat": 19,99, "Dateien": [ { "type": "Standard", "url": "https://example.com/files/printfile.pdf" } ] } ]}'

Häufige Probleme

  1. Fehlende Pflichtfelder: Bitte stellen Sie sicher, dass alle erforderlichen Felder in Ihrer Anfrage ausgefüllt sind.

  2. Ungültige Dateiadressen: Bitte stellen Sie sicher, dass Ihre Dateiadressen öffentlich zugänglich sind.

  3. Unbekannte Produkt-UID: Bitte prüfen Sie, ob die Produkt-UID existiert, oder verwenden Sie personalisierte Produkte.

  4. Doppelte Bestellreferenz-ID: Verwenden Sie für jede Bestellung eine eindeutige Bestellreferenz-ID.

Bestellung stornieren

Mit dem Endpunkt „Bestellung stornieren“ können Sie die Produktion und den Versand einer Bestellung stoppen, solange diese noch nicht versendet wurde.

Endpunkt: POST /{orderCancelUrl}/{orderId}/cancel

Beispiel für eine Anfrage

# Stornieren mit Gelato-Bestellnummercurl --location --request POST 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611/cancel' \--header 'X-API-KEY: your-key:your-secret'# Stornieren Sie mit Ihrer Bestellreferenzcurl --location --request POST 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123/cancel' \--header 'X-API-KEY: your-key:your-secret'

Beispiel für eine Antwort

{ "code": 200, "message": "Alles klar"}

Häufige Probleme

  1. Bestellung bereits versendet: Bestellungen, die schon auf dem Weg zu Ihnen sind, können nicht mehr storniert werden.

  2. Bestellung nicht gefunden: Bitte prüfen Sie, ob die Bestellnummer oder Referenznummer korrekt ist.

  3. Probleme bei der Anmeldung: Bitte überprüfen Sie, ob Ihr API-Schlüssel und Ihr Geheimnis korrekt sind.

Sendung aktualisieren

Mit der Update Shipment-Schnittstelle können Sie die Versandart ändern oder die Lieferadresse für eine Bestellung anpassen, die noch nicht versendet wurde.

Endpunkt: POST /{updateShipmentURL}/{orderId}

Beispiel anfordern

# Versanddetails aktualisierencurl --location --request PUT 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \--header "Content-Type: application/json" \--header 'X-API-KEY: your-key:your-secret' \--data '{ "shipmentMethodUid": "fed_ex_2_day", "shippingAddress": { "country": "US", "firstName": "Jane", "lastName": "Smith", "addressLine1": "Parkallee 456", "city": "New York", "postCode": "10022", "state": "NY", "email": "[email protected]", "phone": "987-654-3210" }}'# Nur die Versandart aktualisierencurl --location --request PUT 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \--header 'Content-Type: application/json' \--header "X-API-KEY: Ihr-Schlüssel:Ihr-Geheimnis" \--data '{ "shipmentMethodUid": "fed_ex_2_day"}'

Beispiel für eine Antwort

{ "shippingAddress": { "id": "2f85d65b-4814-4b5f-90a2-a7de28250bd1", "orderId": "32884a3e-bd09-42be-8225-c5cea7d24611", "country": "US", "firstName": "Jane", "lastName": "Smith", "addressLine1": "Parkallee 456", "city": "New York", "postCode": "10022", "state": "NY", "email": "[email protected]", "Telefon": "987-654-3210" }, "shipment": { "shipmentMethodUid": "fed_ex_2_day", "shipmentMethodName": "FedEx 2Day", "fulfillmentCountry": "US", "fulfillmentFacilityId": "db0622e7-d7af-4453-b39f-cdf1b67f3daa", "packageCount": 1, "initialMinDeliveryDate": "15.04.2025", "initialMaxDeliveryDate": "15.04.2025", "serviceType": "normal" }}

Häufige Probleme

  1. Bestellung bereits versendet: Versanddetails für bereits versendete Bestellungen können nicht mehr geändert werden.

  2. Fehlende Pflichtfelder: Bitte stellen Sie sicher, dass alle erforderlichen Felder in der Versandadresse ausgefüllt sind.

  3. Ungültige Versandart: Bitte prüfen Sie, ob die Versandart-UID gültig ist.

  4. Bestellung nicht gefunden: Bitte prüfen Sie, ob die Bestellnummer oder Referenznummer korrekt ist.

Bestellung erhalten

Mit dem Get Order-Endpunkt können Sie detaillierte Informationen zu einer bestehenden Bestellung abrufen.

Endpunkt: POST /{getOrderURL}/{orderId}

Beispiel anfordern

# Bestellung mit Gelato-Bestellnummer abrufencurl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \--header "X-API-KEY: your-key:your-secret"# Bestellung mit Ihrer Bestellreferenz-ID abrufencurl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123' \--header 'X-API-KEY: your-key:your-secret'

Beispiel für eine Antwort

Die Antwort enthält ausführliche Informationen zur Bestellung, unter anderem:

  • Bestelldetails (ID, Referenz, Status, Zeitangaben)

  • Lieferadresse

  • Bestellte Artikel

  • Versandinformationen

  • Finanzielle Informationen

Da die Antwort sehr umfangreich ist, finden Sie die vollständige Struktur in der API-Dokumentation.

So nutzen Sie die Antwortdaten

Die Antwort auf die Get Order-Anfrage liefert Ihnen wertvolle Informationen, die Sie nutzen können, um:

  1. Bestellstatus anzeigen: Zeigen Sie Ihren Kundinnen und Kunden, wie es um ihre Bestellungen steht.

  2. Sendungen verfolgen: Rufen Sie Tracking-Informationen ab, um Ihre Sendungen im Blick zu behalten.

  3. Bestelldetails überprüfen: Stellen Sie sicher, dass alle Angaben zur Bestellung korrekt sind.

  4. Bestellhistorie analysieren: Erstellen Sie Berichte und Auswertungen auf Basis Ihrer Bestelldaten.

Häufige Probleme

  1. Bestellung nicht gefunden: Bitte prüfen Sie, ob die Bestellnummer oder Referenznummer korrekt ist.

  2. Authentifizierungsprobleme: Bitte überprüfen Sie, ob Ihr API-Schlüssel und Ihr Geheimnis korrekt sind.

Bestellungen suchen

Mit der Search Orders-Schnittstelle können Sie eine Liste von Bestellungen abrufen, die bestimmten Kriterien entsprechen.

Endpunkt: POST /{searchOrdersURL}

Beispiel für eine Anfrage

# Nach Fulfillment-Status suchencurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header "Content-Type: application/json" \--header 'X-API-KEY: your-key:your-secret' \--data '{ "fulfillmentStatus": ["versendet", "zugestellt"]}'# Nach Zeitraum suchencurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header "Content-Type: application/json" \--header 'X-API-KEY: Ihr-Schlüssel:Ihr-Geheimnis' \--data '{ "startDate": "2025-01-01T00:00:00+00:00", "endDate": "2025-04-13T23:59:59+00:00"}'# Nach Bestellreferenz-ID suchencurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \--data '{ "orderReferenceId": "IHRE-BESTELLUNG-123"}'# Suche mit Seitennavigationcurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: Ihr-Schlüssel:Ihr-Geheimnis' \--data '{ "fulfillmentStatus": ["erstellt", "gedruckt"], "limit": 50, "offset": 0}'

Beispiel für eine Antwort

{ "orders": [ { "id": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "orderReferenceId": "IHRE-BESTELLUNG-123", "fulfillmentStatus": "versendet", "financialStatus": "bezahlt", "currency": "USD", "totalInclVat": "33,45", "orderType": "Bestellung", "channel": "api", "firstName": "John", "lastName": "Doe", "country": "US", "itemsCount": 1, "createdAt": "2025-04-10T11:05:09+00:00", "updatedAt": "2025-04-10T14:05:10+00:00", "orderedAt": "2025-04-10T11:05:07+00:00", "customerReferenceId": "CUST-456" }, // Weitere Bestellungen... ]}

Seitennummerierung

Der Endpunkt „Bestellungen suchen“ unterstützt die Seitennavigation, damit Sie auch große Ergebnismengen bequem verwalten können:

# Erste Seite (50 Artikel)curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: Ihr-Schlüssel:Ihr-Geheimnis' \--data '{ "fulfillmentStatus": ["versendet"], "Limit": 50, "offset": 0}'# Zweite Seite (nächste 50 Einträge)curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: Ihr-Schlüssel:Ihr-Geheimnis' \--data '{ "fulfillmentStatus": ["versendet"], "limit": 50, "offset": 50}'

Typische Suchsituationen

  1. Bestellungen nach Status:

    { "fulfillmentStatus": ["erstellt", "gedruckt"] }

  2. Bestellungen nach Zeitraum:

    { "startDate": "01.04.2025T00:00:00+00:00", "endDate": "2025-04-13T23:59:59+00:00"}

  3. Bestellungen nach Land:

    { "countries": ["US", "CA"] }

  4. Kriterien kombinieren:

    { "fulfillmentStatus": ["versendet"], "countries": ["US"], "startDate": "01.04.2025T00:00:00+00:00"}

Häufige Probleme

  1. Keine Ergebnisse: Überprüfen Sie, ob Ihre Suchkriterien nicht zu eingeschränkt sind.

  2. Zu viele Ergebnisse: Verwenden Sie die Seitennavigation und/oder zusätzliche Filter, um Ihre Suche einzugrenzen.

  3. Ungültiges Format: Bitte stellen Sie sicher, dass das Datumsformat dem ISO 8601-Standard (YYYY-MM-DDTHH:MM:SS+00:00) entspricht.

Vorlagen mit API-Endpunkten verbinden

Wenn Sie Bestellungen über die API einreichen, müssen Sie die Daten häufig zwischen Ihrem Format und dem Format von GelatoConnect umwandeln. Vorlagen übernehmen diese Umwandlung, aber Sie müssen Ihre Vorlage ausdrücklich mit dem API-Endpunkt verknüpfen, damit sie angewendet wird.

So verknüpfen Sie eine Vorlage mit einer Bestellübermittlung:

  1. Wechseln Sie zu Ihrer Connector-Liste und klicken Sie auf den Hyperlink Bearbeiten neben dem Submit-Order-Endpunkt.

  2. Gehen Sie auf der Seite zur Endpunkt-Konfiguration zum Abschnitt Endpunktvorlage.

  3. Wählen Sie Ihre Vorlage für die Auftragsübermittlung im Dropdown-Menü aus

  4. Klicken Sie oben rechts auf der Seite auf die Schaltfläche Endpunkt festlegen.

  5. Klicken Sie oben rechts auf Änderungen speichern, um Ihre Konfiguration zu übernehmen.

Nachdem Sie diese Schritte abgeschlossen haben, werden alle an diesen Endpunkt gesendeten Bestellungen mithilfe Ihrer Vorlage umgewandelt, bevor sie verarbeitet werden. So wird sichergestellt, dass das Format Ihres Systems korrekt in das von GelatoConnect erwartete Format umgewandelt wird.

Ohne diese Konfiguration wird Ihre Vorlage nicht angewendet, selbst wenn sie existiert und korrekt gestaltet ist. Das kann dazu führen, dass Ihre Bestellung nicht geprüft werden kann, wenn Ihr Datenformat nicht genau den Anforderungen von GelatoConnect entspricht.

Best Practices für eine gelungene Integration

Wenn Sie die Order-API-Endpunkte integrieren, beachten Sie bitte diese bewährten Methoden:

1. Bestell-IDs des Shops

Speichern Sie immer sowohl Ihre Bestellreferenz-ID als auch die Gelato-Bestell-ID, die Sie in der Antwort erhalten. So behalten Sie in beiden Systemen den Überblick und können Bestellungen leichter nachverfolgen.

2. Gehen Sie mit Fehlern souverän um

Setzen Sie eine zuverlässige Fehlerbehandlung für jede API-Anfrage um. Analysieren Sie die Fehlermeldung aus der Antwort, um den Nutzern hilfreiches Feedback zu geben, und sorgen Sie für passende Möglichkeiten zur Fehlerbehebung.

Für Tipps zur effektiven Fehlerbehandlung schauen Sie sich den Abschnitt „Best Practices für Fehlerbehandlung“ in der Order Management API Dokumentation an.

3. Idempotenz umsetzen

Erstellen Sie für jede Bestellung eine eindeutige Bestellreferenz-ID und nutzen Sie den Parameter preventDuplicate, damit eine Bestellung auch bei Netzwerkproblemen nicht doppelt aufgegeben wird.

4. Verwenden Sie Webhook-Benachrichtigungen

Statt regelmäßig nach neuen Bestellstatus zu suchen, richten Sie Webhook-Benachrichtigungen ein, um sofort informiert zu werden, sobald sich der Status einer Bestellung ändert.

5. Daten vor dem Absenden prüfen

Prüfen Sie die Bestelldaten vor dem Senden an die API auf Ihrer Seite, um offensichtliche Fehler frühzeitig zu erkennen und das Nutzererlebnis zu verbessern.

6. Wiederholungsversuche einbauen

Fügen Sie eine Wiederholungslogik mit exponentiellem Backoff für vorübergehende Fehler hinzu, insbesondere bei Rate-Limit-Antworten (429).

Weitere Informationen zur Implementierung von exponentiellem Backoff und Jitter finden Sie im Abschnitt „Best Practices für Rate Limits“ in der Order Management API Dokumentation oder im AWS-Blogbeitrag zu exponentiellem Backoff und Jitter.

7. Suchanfragen optimieren

Geben Sie möglichst genaue Suchkriterien an, um die Anzahl der Ergebnisse zu verringern und die Leistung zu verbessern.

8. Referenzdaten zwischenspeichern

Speichern Sie Produkt-UIDs und andere Referenzdaten zwischen, um weniger API-Anfragen stellen zu müssen.

Fazit

Die GelatoConnect Order API bietet Ihnen eine leistungsstarke Auswahl an Endpunkten, mit denen Sie den gesamten Bestellprozess steuern können. Wenn Sie wissen, wie Sie diese Endpunkte optimal nutzen, schaffen Sie eine reibungslose Verbindung zwischen Ihren Systemen und GelatoConnect.

Für ausführlichere Informationen werfen Sie einen Blick in die Order Management API Dokumentation.

Verwandte Artikel
[Auftragseingang – GCW] API-Dokumentation für das Auftragsmanagement
[Auftragseingang – GCW] Verwendung von Kundenprodukten vs. ProductUID bei API-Bestellungen
[Order Intake - GCW] So nutzen Sie die kundenunabhängigen Order-API-Endpunkte
[Auftragseingang – GCW] GelatoConnect API-Grundlagen
[Order Intake - GCW] GelatoConnect in Redbubble integrieren
Hat dies deine Frage beantwortet?