Einleitung
Willkommen zur Dokumentation der Order Management API. Mit dieser API können Sie Bestellungen aufgeben, stornieren, Bestelldetails abrufen, nach Bestellungen suchen sowie Versandadressen oder Versandarten im GelatoConnect-System aktualisieren. Die API basiert auf REST-Prinzipien und verwendet standardmäßige HTTPS-Methoden zur Interaktion mit Ressourcen. Alle Antworten, einschließlich Fehlermeldungen, werden im JSON-Format zurückgegeben.
Authentifizierung
Alle Aufrufe der Order Management API erfordern eine Authentifizierung mit einem gültigen API-Schlüssel und Secret, die im Header jeder Anfrage angegeben werden. Die gesamte Kommunikation muss über HTTPS erfolgen; Anfragen über einfaches HTTP werden nicht akzeptiert.
Authentifizierungsmethode
Fügen Sie Ihrer Anfrage den Header
X-API-KEYhinzuGeben Sie den Wert im folgenden Format ein:
key:secret
Beispiel:
X-API-KEY: your-key:your-secret
Ihre persönliche API-Schlüssel und Ihr Secret erhalten Sie, wenn Sie einen Connector für Ihren Kunden einrichten.
Nutzungsbegrenzungen
Die API begrenzt, wie viele Anfragen Sie oder Ihr Client innerhalb eines bestimmten Zeitraums stellen dürfen. Alle Anfragen werden auf Ihr persönliches Limit von 100 Anfragen pro Sekunde angerechnet.
Warum es Begrenzungen für Anfragen gibt
Grenzwerte für Anfragen erfüllen mehrere wichtige Aufgaben:
Schutz vor Missbrauch oder unsachgemäßer Nutzung der API
Gerechter Zugang für alle Nutzerinnen und Nutzer
So vermeiden Sie Ausfälle durch zu viel Datenverkehr
Wiederholungsstrategie bei Überschreitung von Anfragelimits
Wenn Sie das API-Limit überschreiten, erhalten Sie einen 429-Statuscode. Um Ihre Arbeitsabläufe möglichst wenig zu beeinträchtigen, nutzen Sie bitte folgende Methoden zum erneuten Versuch:
Wiederholen: Fehlgeschlagene Anfragen werden automatisch erneut versucht. Bauen Sie eine Wiederholungslogik für alle API-Aufrufe in Ihren Anwendungscode ein.
Exponentielles Zurücksetzen: Warten Sie bei aufeinanderfolgenden Fehlermeldungen jeweils etwas länger, bevor Sie es erneut versuchen. Legen Sie ein maximales Zeitintervall für die Verzögerung und eine Höchstzahl an Wiederholungsversuchen fest – je nachdem, welche Aktion Sie durchführen.
Jitter: Fügen Sie vor dem erneuten Senden von Anfragen eine zufällige Wartezeit hinzu. So wird vermieden, dass alle Nutzer gleichzeitig erneut anfragen. Dadurch verteilt sich die Auslastung besser und wiederholte Überschneidungen werden verhindert.
Weitere Informationen zu Wiederholungsstrategien finden Sie hier:
Antwortcodes
Die Order Management API verwendet die üblichen HTTP-Antwortcodes, um anzuzeigen, ob Anfragen erfolgreich waren oder fehlgeschlagen sind:
2xx-Codes: Stehen für einen erfolgreichen Ablauf
4xx-Codes: Weisen auf strukturelle oder Datenfehler in der Anfrage hin (zum Beispiel fehlende Pflichtangaben oder nicht gefundene Bestellung)
5xx-Codes: Weisen auf Serverfehler hin (das kommt nur selten vor)
API-Endpunkte
Bestellung absenden
Geben Sie eine Bestellung mit nur einer Anfrage auf.
Endpunkt: POST /{submitOrderUrl}
Die Basis-URL und der spezifische Endpunkt werden Ihnen während der Einrichtung des Connectors bereitgestellt.
Anfrageformat
{ "orderReferenceId": "test", "orderType": "order", "currency": "EUR", "retailCurrency": "GBP", "retailShippingPriceInclVat": 6.99, "shipmentMethodUid": "normal,standard,fed_ex_2_day", "shippingAddress": { "country": "SE", "firstName": "My first name", "lastName": "My last name", "addressLine1": "17", "addressLine2": "Address 1", "city": "City", "postCode": "11111", "state": "", "email": "[email protected]", "phone": "+47222222", "companyName": "MyCompany" }, "items": [ { "itemReferenceId": "test1", "productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantity": 1, "retailPriceInclVat": 19.99, "files": [ { "type": "default", "url": "https://www.example.com/path/to/printfile.pdf" } ] } ]}Beispiel-curl-Anfrage (hier klicken)
Beispiel-curl-Anfrage (hier klicken)
curl --location --request POST 'https://api.partner-connect.io/api/your-partner-prefix/order' \--header "Content-Type: application/json" \--header "X-API-KEY: Ihr-Schlüssel:Ihr-Geheimnis" \--data-raw '{ "orderReferenceId": "test", "orderType": "order", "preventDuplicate": true, "currency": "EUR", "retailCurrency": "GBP", "retailShippingPriceInclVat": 6.99, "shipmentMethodUid": "normal,standard,fed_ex_2_day", "shippingAddress": { "country": "SE", "firstName": "My first name", "lastName": "My last name", "addressLine1": "17", "addressLine2": "Address 1", "city": "City", "postCode": "11111", "state": "", "email": "[email protected]", "phone": "+47222222", "companyName": "MyCompany" }, "items": [ { "itemReferenceId": "test1", "productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantity": 1, "retailPriceInclVat": 19.99, "files": [ { "type": "default", "url": "https://www.example.com/path/to/printfile.pdf" } ] } ]}'Wichtige Anforderungsparameter
Parameter | Typ | Erforderlich | Beschreibung |
Bestellreferenznummer | Zeichenkette | Erforderlich | Ihre interne Bestellnummer |
Bestellart | Zeichenkette | Optional | Type of order: "order" (default) or "draft" |
Währung | Zeichenkette | Erforderlich | Währung für die Bestellung (ISO-Code) |
Einzelhandelswährung | Zeichenkette | Optional | Währung für Einzelhandelspreise (bei grenzüberschreitenden Bestellungen) |
Einzelhandelspreis für Versand inkl. MwSt. | Zahl | Optional | Versandpreis ohne MwSt. (auch wenn der Parametername etwas anderes vermuten lässt) |
shipmentMethodUid | Zeichenkette | Optional | Zu verwendende Versandart(en), kann durch Kommas getrennt werden |
Lieferadresse | Gegenstand | Erforderlich | Lieferadresse des Kunden |
Artikel | Auswahl | Erforderlich | Liste der Produkte, die Sie bestellen möchten |
Doppelte Einträge vermeiden | boolesch | Optional | Wenn diese Option aktiviert ist, wird verhindert, dass doppelte Bestellungen mit derselben orderReferenceId erstellt werden. Wird ein Duplikat erkannt, erhalten Sie eine Fehlermeldung anstelle einer neuen Bestellung. |
"packagingInstructions": [ | Auswahl | Optional | Array von Verpackungsanweisungsobjekten |
Artikeleinstellungen
Parameter | Typ | Erforderlich | Beschreibung |
Artikelreferenz-ID | Zeichenkette | Erforderlich | Ihre interne Artikelnummer |
productUid | Zeichenkette | Erforderlich* | GelatoConnect Produktkennung (*Entweder productUid ODER productName+productVariant ist erforderlich) |
Produktname | Zeichenkette | Erforderlich* | Name des Kundenprodukts (*Entweder productUid ODER productName+productVariant ist erforderlich) |
Produktvariante | Gegenstand | Erforderlich* | Variantendetails für das Kundenprodukt (*erforderlich, wenn Sie productName verwenden) |
Menge | Zahl | Erforderlich | Anzahl der zu bestellenden Artikel |
Einzelhandelspreis inkl. MwSt. | Nummer | Optional | Preis ohne MwSt. (auch wenn der Parametername etwas anderes sagt) |
Dateien | Auswahl | Erforderlich | Liste der Druckdateien für das Produkt |
personalisierter Rand | Objekt | Optional | Personalisierte Randmaße für das Produkt |
Dateiparameter
Parameter | Typ | Erforderlich | Beschreibung |
Typ | Zeichenkette | Erforderlich | Dateityp. Eine Übersicht der möglichen Optionen finden Sie in der Tabelle unten. |
url | Zeichenkette | Erforderlich | Öffentlich zugängliche URL zur Druckdatei |
Dateityp
Parameter | Beschreibung |
de | Das Design wird auf der Hauptfläche des Produkts gedruckt. Bei Bekleidung ist das die Vorderseite, bei Klappkarten sind es die Umschlag- und Rückseiten.
Wenn Sie eine mehrseitige PDF-Datei bereitstellen, sollte die Seitenanzahl mit den Druckbereichen übereinstimmen, da sie für alle Bereiche verwendet wird. |
Vorderseite | Drucken Sie die Datei auf die Vorderseite des Produkts. |
Zurück | Drucken Sie die Datei auf die Rückseite des Produkts. |
Umschlag | Die Datei für einen Buchumschlag |
Hals-Innenseite | Drucken Sie die Datei auf die Innenseite am Hals des Bekleidungsprodukts. |
Hals-Außenseite | Drucken Sie die Datei auf die Außenseite des Halses des Bekleidungsprodukts. |
linker Ärmel | Drucken Sie die Datei auf den linken Ärmel des Bekleidungsprodukts. |
rechter Ärmel | Drucken Sie die Datei auf den rechten Ärmel des Bekleidungsprodukts. |
drinnen | Drucken Sie die Datei auf die Innenseiten. |
Bruststickerei links | Sticken Sie die Datei auf die linke Brustseite des Bekleidungsprodukts. |
Stickerei mittig auf der Brust | Sticken Sie die Datei auf die Mitte der Vorderseite des Bekleidungsprodukts. |
große Stickerei auf der Brust | Sticken Sie die Datei auf die Vorderseite des Bekleidungsprodukts. |
Stickerei auf dem linken Ärmel | Sticken Sie die Datei auf den linken Ärmel des Bekleidungsprodukts. |
Stickerei auf dem rechten Ärmel | Sticken Sie die Datei auf den rechten Ärmel des Bekleidungsprodukts. |
Stickerei am linken Handgelenk | Sticken Sie die Datei auf das linke Handgelenk des Bekleidungsprodukts. |
Stickerei am rechten Handgelenk | Sticken Sie die Datei auf das rechte Handgelenk des Bekleidungsprodukts. |
Flexible Dateitypen für workflowfähige Produkte
Für Produkte, die für den Workflow builder aktiviert sind, können Sie im Feld type des files-Arrays beliebige personalisierte Dateitypnamen verwenden. Diese Funktion vereinfacht API-Integrationen, da Sie Dateien nicht mehr vordefinierten Typen zuordnen müssen.
Wichtige Punkte:
Sie können Dateitypen frei benennen, zum Beispiel
default_1,default_2,cover_front,inside_pageusw.Erlaubte Zeichen: Buchstaben (A–Z, a–z), Zahlen (0–9), Unterstriche (_), Punkte (.) und Bindestriche (-)
Maximale Länge: 100 Zeichen
Die Einzigartigkeit des Dateityps bleibt bestehen – jeder
type-Wert muss innerhalb desselbenfiles-Arrays eindeutig sein.
Beispiel für die Verwendung:
{ "items": [ { "productUid": "your-workflow-enabled-product-uid", "quantity": 1, "files": [ { "type": "default_1", "url": "https://your-file-url.com/file1.pdf" }, { "type": "default_2", "url": "https://your-file-url.com/file2.pdf" }, { "type": "custom_cover", "url": "https://your-file-url.com/cover.pdf" } ] } ]}
Personalisierte Rand-Parameter
Parameter | Typ | Erforderlich | Beschreibung |
BreiteMm | Zahl | Erforderlich | Randbreite in Millimetern (*Erforderlich bei Verwendung von personalisiertem Rand) |
HöheMm | Zahl | Erforderlich | Randhöhe in Millimetern (*Erforderlich bei Verwendung von personalisiertem Rand) |
Parameter für Verpackungsanweisungen
Parameter | Typ | Erforderlich | Beschreibung |
"packageItems": [ | Auswahl | Erforderlich | Artikel, die in dieses Paket aufgenommen werden sollen |
orderItemReferenceId | Zeichenkette | Erforderlich | Verweis auf den Bestellartikel (muss mit itemReferenceId übereinstimmen) |
Menge | Zahl | Erforderlich | Menge des Artikels in diesem Paket |
"packingSlip": { | Objekt | Optional | Konfiguration des Lieferscheins |
fileUrl | Zeichenkette | Erforderlich | URL zur PDF-Packzettel-Datei |
GelatoConnect lädt Ihren Lieferschein als PDF herunter und speichert ihn, damit er während des Verpackungsprozesses jederzeit zugänglich bleibt – selbst wenn die ursprüngliche URL abläuft.
Beispiel für die Verwendung:
{ "orderReferenceId": "ORDER-12345", "orderType": "order", "currency": "USD", "shippingAddress": {...}, "items": [...], "packagingInstructions": [ { "packageItems": [ { "orderItemReferenceId": "ITEM-001", "quantity": 1 } ], "packingSlip": { "fileUrl": "https://example.com/slip.pdf" } } ]}
Migration von packzetteln auf Metadaten-Basis
Für Kundinnen und Kunden, die derzeit Metadaten verwenden, um Lieferscheine zu versenden, können Sie die folgende Vorlage nutzen, um Lieferschein-URLs aus den Metadaten zu extrahieren und sie in das packagingInstructions-Format umzuwandeln. So stellen Sie sicher, dass die Dateien dauerhaft von GelatoConnect gespeichert werden.
{%- set payload = context.payload -%}{#-- Packzettel-URL extrahieren und 'tenant-packing-slip' herausfiltern --#}{%- set ns = namespace(packing_slip_url=None) -%}{%- set filtered_metadata = [] -%}{%- for m in payload.metadata or [] %} {%- if m.key == "tenant-packing-slip" %} {%- set ns.packing_slip_url = m.value %} {%- else %} {%- set filtered_metadata = filtered_metadata + [m] %} {%- endif %} {%- endfor -%}{#-- Aktualisierte JSON-Ausgabe --#}{ {%- for key, value in payload.items() %} {%- if key != "metadata" %} "##{{ key }}": ##{{ value | tojson }}, {%- endif %} {%- endfor %} "metadata": ##{{ filtered_metadata | tojson }},Verpackungsanweisungen {Paketartikel {%- for item in payload.get("items") or [] -%} { "orderItemReferenceId": ##{{ item.itemReferenceId|js }}, "quantity": ##{{ item.quantity }} }{% if not loop.last %},{% endif %}{%- endfor %} ],Lieferschein "fileUrl": "##{{ ns.packing_slip_url }}" } } ]}
Parameter für die Versandadresse
Parameter | Typ | Erforderlich | Beschreibung |
Land | Zeichenkette | Erforderlich | Zwei-Buchstaben-Ländercode (ISO 3166-1 alpha-2) |
Vorname | Zeichenkette | Erforderlich | Vorname des Empfängers |
Nachname | Zeichenkette | Erforderlich | Nachname des Empfängers |
Adresszeile 1 | Zeichenkette | Erforderlich | Erste Zeile der Straßenadresse |
Adresszusatz | Zeichenkette | Optional | Zweite Zeile der Straßenadresse |
Stadt | Zeichenkette | Erforderlich | Stadtname |
Postleitzahl | Zeichenkette | Erforderlich | Postleitzahl |
Status | Zeichenkette | Erforderlich | Bundesland- oder Provinzcode (*Erforderlich für Adressen in den USA, Kanada und Australien) |
Zeichenkette | Erforderlich* | E-Mail-Adresse des Empfängers | |
Telefon | Zeichenkette | Erforderlich | Telefonnummer des Empfängers mit Ländervorwahl |
Firmenname | Zeichenkette | Optional | Firmenname (falls zutreffend) |
istGeschäftskunde | boolesch | Optional | Ob die Adresse geschäftlich genutzt wird |
Bundessteuer-ID | Zeichenkette | Optional | Steuerliche Identifikationsnummer für Geschäftsadressen |
Bundesstaatliche Steuer-ID | Zeichenkette | Optional | Steuer-ID für Geschäftsadressen |
Registrierungsstatus | Zeichenkette | Optional | Bundesland, in dem Ihr Unternehmen registriert ist |
Besondere Hinweise für internationale Bestellungen
Für internationale Bestellungen geben Sie bitte den Einzelhandelspreis des Produkts und die Versandkosten wie folgt an:
retailCurrency: Währung, in der die Einzelhandelspreise angegeben werdenretailShippingPriceInclVat: Versandpreis ohne MwSt. (bitte den Parameternamen ignorieren)items[i].retailPriceInclVat: Gesamtpreis des Produkts ohne MwSt. (bitte beachten Sie den Parameternamen nicht)
Ein Produkt auswählen
Die API zum Absenden von Bestellungen kann Produktinformationen auf zwei Arten erhalten:
Verwendung von
productUid:
"productUid": "frame_product_frs_10x10-inch_frc_oak_frm_wood_frp_w13xt22-mm_gt_plexiglass"
Verwendung von
productNameundproductVariant:
"productName": "Framed Poster","productVariant": { "FrameColour": "Black", "PaperSize": "A3"}Bitte verwenden Sie nicht beide Methoden in derselben Bestellanfrage.
Versandart auswählen
Das Feld shipmentMethodUid kann Folgendes akzeptieren:
Spezifische Versandmethoden-UIDs (z. B.
fed_ex_2_day)Namen von Versanddienstleistern (z. B.
DHL)Versandoptionen in verschiedenen Stufen (z. B.
Express)
Sie können mehrere Versandarten als durch Kommas getrennte Liste angeben, und das System wählt automatisch die günstigste Option aus.
Antwortformat
{ "id": "32884a3e-bd09-42be-8225-c5cea7d24611", "orderReferenceId": "test", "createdAt": "2024-07-17T10:23:28+00:00"}
Verwendung von Metadaten in ganz GelatoConnect
Metadaten, die sowohl auf Bestell- als auch auf Artikelebene in Bestellanfragen bereitgestellt werden, können von verschiedenen Tools innerhalb von GelatoConnect genutzt und auch in Rückmeldungen zurückgegeben werden. Das ist besonders hilfreich für alle, die eine durchgängige Datenverbindung zwischen ihren Systemen sicherstellen möchten.
Metadaten auf Bestellebene:
Metadaten auf Bestellebene gelten für die gesamte Bestellung und werden auf oberster Ebene der Anfrage festgelegt.
{ "orderReferenceId": "ORD-12345", "orderType": "order", "currency": "USD", "metadata": [ { "key": "campaign", "value": "summer_promo" }, { "key": "source", "value": "web" } ], "shippingAddress": {...}, "items": [...]}
Metadaten auf Artikelebene:
Metadaten auf Artikelebene beziehen sich auf einzelne Artikel und werden direkt im jeweiligen Artikel innerhalb des Artikel-Arrays festgelegt.
{ "orderReferenceId": "ORD-12345", "orderType": "order", "currency": "USD", "shippingAddress": {...}, "items": [ { "itemReferenceId": "ITEM-001", "productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantity": 1, "metadata": [ { "key": "position", "value": "A1" }, { "key": "machine", "value": "Printer3" } ], "files": [...] } ]}
Datei-Metadaten:
Dateibezogene Metadaten gelten für bestimmte Dateien und werden innerhalb jeder Datei im files-Array definiert. Im folgenden Beispiel wird dies genutzt, um Alternativtext für das Bild embroideryText festzulegen, das mit der Datei verknüpft ist.
{ "orderReferenceId": "ORD-12345", "orderType": "order", "currency": "USD", "shippingAddress": {...}, "items": [ { "itemReferenceId": "ITEM-001", "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://www.example.com/path/to/printfile.pdf", "metadata": [ { "key": "embroideryText", "value": "James" } ] } ] } ]}
Bestellung stornieren
Beenden und stornieren Sie die Produktion und den Versand eines Auftrags. Dies ist nur möglich, solange der Auftragsstatus noch nicht auf "versendet" geändert wurde.
Endpunkt: POST /{orderCancelUrl}
Dieser Endpunkt akzeptiert entweder die Bestellnummer (wie in der Antwort auf die Bestellübermittlung angegeben) oder die Bestellreferenznummer (Ihre interne Bestellnummer).
Verwendung der Bestellnummer
POST /{orderCancelUrl}/32884a3e-bd09-42be-8225-c5cea7d24611/stornierenVerwendung der Bestellreferenz-ID
POST /{orderCancelUrl}/test/stornierenAntwortformat
{ "code": 200, "message": "OK"}
Sendung aktualisieren
Ändern Sie die Versandart oder aktualisieren Sie die Lieferadresse, solange Ihre Bestellung noch nicht den Status „Versendet“ erreicht hat.
Endpunkt: PUT /{updateShipmentURL}
An diesem Endpunkt können Sie entweder die Bestellnummer oder die Bestellreferenznummer angeben.
Anfrageformat
{ "shipmentMethodUid": "fed_ex_2_day", "shippingAddress": { "country": "GB", "firstName": "Alexis", "lastName": "Apollo", "addressLine1": "Longusta str. 4", "addressLine2": "app. 144", "city": "myCity", "postCode": "111111", "state": "myState", "email": "[email protected]", "phone": "+34 111444111", "companyName": "Company_example", "isBusiness": false, "federalTaxId": "", "stateTaxId": "", "registrationState": "" }}Sie können entweder die Versandart, die Versandadresse oder beides aktualisieren. Mindestens eines dieser Felder muss in der Anfrage enthalten sein.
Anfrageparameter
Parameter | Typ | Erforderlich | Beschreibung |
shipmentMethodUid | Zeichenkette | Optional* | Neue Versandart (*Mindestens eine der folgenden Angaben ist erforderlich: shipmentMethodUid oder shippingAddress) |
Lieferadresse | Objekt | Optional* | Neue Versandadressdetails (*Mindestens eine Versandmethode oder Versandadresse muss angegeben werden) |
Antwortformat
{ "shippingAddress": { "id": "2f85d65b-4814-4b5f-90a2-a7de28250bd1", "orderId": "148c5a06-35c9-40d3-8ef7-e85eb2da317d", "country": "GB", "firstName": "Test Order", "lastName": "4", "companyName": "company_example", "addressLine1": "address example 1", "addressLine2": "address example 2", "city": "myCity", "postCode": "111111", "state": "", "email": "[email protected]", "phone": "+34 111444222", "isBusiness": false, "federalTaxId": "", "stateTaxId": "", "registrationState": "" }, "shipment": { "shipmentMethodUid": "fed_ex_2_day", "shipmentMethodName": "DHL Global Parcel", "fulfillmentCountry": "DE", "fulfillmentFacilityId": "db0622e7-d7af-4453-b39f-cdf1b67f3daa", "packageCount": 1, "initialMinDeliveryDate": "2024-11-16", "initialMaxDeliveryDate": "2024-11-16", "serviceType": "normal" }}
Bestellung erhalten
Informationen zu einer bestehenden Bestellung abrufen.
Endpunkt: GET /{getOrderURL}/{order_id}
Sie können entweder die Gelato-Bestellnummer oder Ihre eigene Bestellreferenz verwenden.
Antwortformat
Die Antwort enthält ausführliche Informationen zur Bestellung, darunter:
Bestelldetails (ID, Referenz, Status usw.)
"shippingAddress": {
Bestellte Artikel mit Produktdetails
Versandinformationen (Methode, Sendungsverfolgung und mehr)
Finanzielle Informationen
Beispielantwort (hier klicken)
Beispielantwort (hier klicken)
{ "id": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "orderReferenceId": "healthcheck_middleware_order_create_2024-12-02-11:05:06_1991", "customerReferenceId": "sandbox-customer", "fulfillmentStatus": "failed", "financialStatus": "canceled", "currency": "USD",Lieferadresse "id": "29de7336-95a9-48d2-aa85-d7d40e6ea65c", "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "country": "GB", "firstName": "TEST", "lastName": "PRINT", "companyName": "", "addressLine1": "19 June Lewis Way", "addressLine2": "", "city": "Fairford", "postCode": "GL7 4GH", "state": "", "email": "[email protected]", "phone": "1111111119", "isBusiness": false, "federalTaxId": null, "stateTaxId": null, "registrationState": null }, "items": [ { "id": "e9f6de69-670b-47c5-a953-3710cac053a1", "itemReferenceId": "1111111111", "productUid": "large-posters_pf_500x700-mm_pt_170-gsm-coated-silk_cl_4-0_ver", "storeProductVariantId": null, "storeProductId": null, "files": [ { "id": null, "type": "default", "url": "https://URLexample.com/order", "threadColors": [], "isVisible": false, "fitMethod": null, "fillMethod": null, "mimeType": "application/pdf", "metadata": [] } ], "processedFileUrl": null, "quantity": 1, "options": [], "category": "Posters", "productCategoryUid": "wall-art", "productTypeUid": "poster", "productNameUid": "classic-semi-glossy-poster", "productName": "Classic Semi-Glossy Poster", "fulfillmentStatus": "failed", "pageCount": null, "printJobs": [], "eventLog": [], "previews": [ { "type": "preview_default", "url": "https://URLexample.com/order" }, { "type": "preview_thumbnail", "url": "https://URLexample.com/order" }, { "type": "preview_flat", "url": "https://URLexample.com/order" } ], "designId": null, "productFileMimeType": "application/pdf", "finalProductUid": "large-posters_pf_500x700-mm_pt_170-gsm-coated-silk_cl_4-0_ver", "metadata": [ { "key": "unitWeight", "value": "800" }, { "key": "unitPrice", "value": "" },} "key": "supplierPartAuxiliaryId", "value": ""{} "retailPriceInclVat": null, "attributes": [ ] "name": "size", "title": "Size", "value": "500x700-mm", "formattedValue": "50 x 70 cm" } { "name": "orientation", "title": "Orientation", "value": "ver", "formattedValue": "Vertical (portrait) orientation"{} "itemReferenceName": null, "isIgnored": false, "price": 0, "customTrim": null, "fileUrl": "https://URLexample.com/order", "dpi": 0, "appServices": [], "filesSize": 3.8, "productVariant": [] ]{ "shipment": { "id": "33163694-1437-407f-99ef-57a0d579114f", "orderProductId": null, "shippingAddressId": "29de7336-95a9-48d2-aa85-d7d40e6ea65c", "promiseUid": "d_dfae1a1c58d230dbe73690a2", "packageCount": 1, "shipmentMethodUid": "dhl_global_parcel", "shipmentMethodName": "DHL Global Parcel", "isCheapest": true, "minDeliveryDays": 1, "maxDeliveryDays": 1, "minDeliveryDate": "2024-12-03", "maxDeliveryDate": "2024-12-03", "totalWeight": 139, "price": 0, "status": null, "packages": [], "fulfillmentCountry": "DE", "fulfillmentFacilityId": "db0622e7-d7af-4453-b39f-cdf1b67f3daa", "retailShippingPriceInclVat": null, "initialMinDeliveryDate": "2024-12-03", "initialMaxDeliveryDate": "2024-12-03", "serviceType": "normal", "speedType": ""} "receipts": [ }, "id": "f9f6e29a-de14-4755-bafe-7cf0cdf6e3fc", "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "type": "contract", "currency": "USD", "items": [ }, "id": "a99224b0-6e96-430e-84dd-82995f274840", "receiptId": "f9f6e29a-de14-4755-bafe-7cf0cdf6e3fc", "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "type": "product", "referenceId": "e9f6de69-670b-47c5-a953-3710cac053a1", "title": "1x large-posters_pf_500x700-mm_pt_170-gsm-coated-silk_cl_4-0_ver", "currency": "USD", "priceBase": 0, "amount": 1, "priceInitial": 0, "discount": 0, "price": 0, "vat": 0, "priceInclVat": 0, "pricePlanId": null, "createdAt": "2024-12-02T11:05:09+00:00", "updatedAt": "2024-12-02T11:05:09+00:00" ], } "id": "1d2936c3-eb3f-456d-94b9-b2be8c4eec50", "receiptId": "f9f6e29a-de14-4755-bafe-7cf0cdf6e3fc", "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "type": "shipment", "referenceId": "33163694-1437-407f-99ef-57a0d579114f", "title": "Delivery using DHL Global Parcel", "currency": "USD", "priceBase": 0, "amount": 1, "priceInitial": 0, "discount": 0, "price": 0, "vat": 0, "priceInclVat": 0, "pricePlanId": null, "createdAt": "2024-12-02T11:05:09+00:00", "updatedAt": "2024-12-02T11:05:09+00:00" { }, "id": "b7d6899c-3a00-46eb-8d14-e9b3e2bb3e4e", "receiptId": "f9f6e29a-de14-4755-bafe-7cf0cdf6e3fc", "orderId": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "type": "packaging", "referenceId": "33163694-1437-407f-99ef-57a0d579114f", "title": "Packaging", "currency": "USD", "priceBase": 0, "amount": 1, "priceInitial": 0, "discount": 0, "price": 0, "vat": 0, "priceInclVat": 0, "pricePlanId": null, "createdAt": "2024-12-02T11:05:09+00:00", "updatedAt": "2024-12-02T11:05:09+00:00" { ], "createdAt": "2024-12-02T11:05:09+00:00", "updatedAt": "2024-12-02T11:05:10+00:00", "receiptNumber": "005-0014597660", "billingEntity": { "id": 218720, "companyName": "Gelato", "companyNumber": "", "companyVatNumber": "", "companyVatNumbers": [], "countryIsoCode": "DE", "country": "DE", "recipientName": "Alex Shiltcev", "addressLine1": "Something 1", "addressLine2": "", "city": "Berlin", "postCode": "10113", "stateCode": "", "state": "", "email": "[email protected]", "phone": "", "currencyIsoCode": "EUR", "currency": "EUR", "status": 1, "iossNumber": null, "invoiceType": null } "billingTag": "gelato-norway-de", "transactionType": "purchase", "productsPriceInitial": 0, "productsPriceDiscount": 0, "productsPrice": 0, "productsPriceVat": 0, "productsPriceInclVat": 0, "digitizationPriceInitial": 0, "digitizationPriceDiscount": 0, "digitizationPrice": 0, "digitizationPriceVat": 0, "digitizationPriceInclVat": 0, "shippingPriceInitial": 0, "shippingPriceDiscount": 0, "shippingPrice": 0, "shippingPriceVat": 0, "shippingPriceInclVat": 0, "packagingPriceInitial": 0, "packagingPriceDiscount": 0, "packagingPrice": 0, "packagingPriceVat": 0, "packagingPriceInclVat": 0, "discount": 0, "discountVat": 0, "discountInclVat": 0, "totalInitial": 0, "total": 0, "totalVat": 0, "totalInclVat": 0, "isCalculated": true }, ], "createdAt": "2024-12-02T11:05:09+00:00", "refusalReason": "Order is failing as it’s going to be cross border and product retail prices are missing.", "channel": "api", "storeId": null, "orderedByUserId": null, "orderType": "order", "metadata": [ } "key": "tenant-customer-id", "value": "02be1010-5f59-4504-a669-5cf88e84f627" { }, "key": "tenant-customer-uid", "value": "sandbox-customer" { }, "billingEntity": { "id": 218720, "companyName": "Gelato", "companyNumber": "", "companyVatNumber": "", "companyVatNumbers": [], "countryIsoCode": "DE", "country": "DE", "recipientName": "Alex Shiltcev", "addressLine1": "Something 1", "addressLine2": "", "city": "Berlin", "postCode": "10113", "stateCode": "", "state": "", "email": "[email protected]", "phone": "", "currencyIsoCode": "EUR", "currency": "EUR", "status": 1, "iossNumber": null, "invoiceType": null { "retailCurrency": null, "paymentMethodType": null, "paymentMethodId": null, "prepaymentTransactionId": null, "orderedAt": "2024-12-02T11:05:07+00:00", "updatedAt": "2024-12-02T11:05:10+00:00", "connectedOrderIds": [], "discounts": [], "returnAddress": { "id": "6eeb262a-92ce-45a4-9cd6-128473a0acb0", "country": null, "addressLine1": null, "addressLine2": null, "city": null, "postCode": null, "state": null, "email": null, "phone": null, "companyName": "Gelato Connect Sandbox" { "iossNumber": null, "refusalReasonCode": "missing_retail_prices", "refusalReasonDetails": null, "comment": "Order is failing as it’s going to be cross border and product retail prices are missing.", "digitizationId": null, "appServices": [], "shipmentMethodUid": "normal" },
Bestellungen suchen
Rufen Sie eine Liste von Bestellungen ab, die bestimmten Kriterien entsprechen.
Endpunkt: POST /{searchOrdersURL}
Anfrageformat
], "fulfillmentStatus": [ "canceled", "delivered" } ],
Anfrageparameter
Parameter | Typ | Erforderlich | Beschreibung |
Erfüllungsstatus | string[] | Optional | Nach Fulfillment-Status der Bestellung filtern |
Finanzstatus | string[] | Optional | Nach finanziellem Status der Bestellung filtern |
Bestellreferenznummer | Zeichenkette | Optional | Filtern Sie nach Ihrer internen Bestellnummer |
Bestellreferenznummern | string[] | Optional | Nach mehreren internen Bestellnummern filtern |
Startdatum | Zeichenkette | Optional | Filtern Sie nach Bestellungen, die nach diesem Datum erstellt wurden (ISO 8601-Format) |
Enddatum | string[] | Optional | Filtern Sie nach Bestellungen, die vor diesem Datum erstellt wurden (ISO 8601-Format) |
Länder | Zeichenkette | Optional | Nach Versandland-Codes filtern |
Grenze | Zahl | Optional | Maximale Anzahl der anzuzeigenden Ergebnisse (Standard: 50, maximal: 100) |
Versatz | Zahl | Optional | Anzahl der Ergebnisse, die für die Seitennavigation übersprungen werden (Standard: 0) |
Antwortformat
} "orders": [ { "id": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "orderReferenceId": "orderref_123", "fulfillmentStatus": "failed", "financialStatus": "canceled", "currency": "USD", "totalInclVat": "0.00", "orderType": "order", "channel": "api", "storeId": null, "connectedOrderIds": [], "firstName": "TEST", "lastName": "PRINT", "country": "GB", "itemsCount": 1, "createdAt": "2024-12-02T11:05:09+00:00", "updatedAt": "2024-12-02T11:05:10+00:00", "orderedAt": "2024-12-02T11:05:07+00:00", "refusalReasonCode": "missing_retail_prices", "appServices": [], "customerReferenceId": "custref_456" }, { ],
Fehlerbehandlung
Wenn eine API-Anfrage fehlschlägt, enthält die Antwort einen Fehlercode und eine verständliche Nachricht, damit Sie das Problem erkennen und lösen können. Häufige Fehlersituationen sind:
400 Fehlerhafte Anfrage: Ungültige oder fehlende Angaben
401 Nicht autorisiert: Ungültige oder fehlende Anmeldedaten
404 Nicht gefunden: Die angeforderte Seite existiert nicht.
429 Zu viele Anfragen: Sie haben das Anfrage-Limit überschritten
500 Serverfehler: Auf dem Server ist etwas schiefgelaufen.
Beispiel für eine Fehlermeldung:
} "code": 400, "message": "Invalid shipping address: Email is not a valid format" {Für eine zuverlässige Integration empfehlen wir Ihnen, eine sinnvolle Fehlerbehandlung und eine Wiederholungslogik einzubauen, wie im Abschnitt zu den Rate Limits beschrieben.
Brauchen Sie Unterstützung?
Wenn Sie auf Probleme stoßen oder Fragen zur API haben, wenden Sie sich bitte an unser Support-Team unter [email protected].
Bitte geben Sie die folgenden Informationen in Ihrer Support-Anfrage an:
Der genaue API-Endpunkt, den Sie verwenden
Ihre Anfrage (sensible Informationen wurden entfernt)
Die Fehlermeldung, die Sie erhalten haben
Alle relevanten Zeitangaben
So kann unser Team Ihr Anliegen schneller und gezielter lösen.