Wenn Sie Bestellungen über die API an GelatoConnect übermitteln, haben Sie zwei Möglichkeiten, Produkte anzugeben: Sie können entweder Produkt-UIDs oder personalisierte Kundenprodukte verwenden. In diesem Leitfaden erklären wir beide Ansätze, ihre Vorteile und wann Sie welche Option am besten nutzen.
Produkt-UID-Ansatz
Der Produkt-UID-Ansatz bedeutet, dass Sie für Ihre Bestellungen eindeutige Produktkennungen (UIDs) verwenden, um Produkte genau zu bestimmen.
So funktioniert es
Wenn Sie Produkt-UIDs verwenden, fügen Sie den Parameter productUid zu Ihrem Bestellartikel hinzu:
{ "itemReferenceId": "ITEM-001", "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/files/printfile.pdf" } ]}Aufbau der Produkt-UID
Eine Produkt-UID ist eine strukturierte Zeichenfolge, die Produkteigenschaften verschlüsselt. Zum Beispiel in flat_product_pf_a4_pt_200-g/m²-unbeschichtet_cl_4-0_ct_none_prt_none_sft_none_set_none_hor:
flat_product: Produkttyppf_a4: Papierformat (A4-Größe)pt_200-gsm-uncoated: Papiersorte (200 g/m² unbeschichtetes Papier)cl_4-0: Farbkonfiguration (4-Farbdruck auf der Vorderseite, keine Farben auf der Rückseite)ct_none: Schneiden (kein Zuschnitt)prt_none: Besondere Druckeffekte (keine)sft_none: Oberflächenbehandlungen (keine)set_none: Spezialeffekte (keine)hor: Ausrichtung (horizontal)
Kundenorientierter Produktansatz
Der Ansatz für Kundenprodukte besteht darin, in GelatoConnect personalisierte Produktdefinitionen zu erstellen und diese in Ihren Bestellungen anhand von Name und Variante zu verwenden.
So funktioniert es
Zuerst legen Sie in GelatoConnect Ihre Kundenprodukte an und definieren die Produktnamen sowie die Variantenoptionen. Wenn Sie dann Bestellungen aufgeben, verweisen Sie auf diese Produkte mit den Parametern productName und productVariant:
{ "itemReferenceId": "ITEM-001", "productName": "Visitenkarte", "productVariant": { "Size": "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" } ]}Kundenprodukte einrichten
Bevor Sie personalisierte Produkte in Ihren API-Bestellungen verwenden, müssen Sie diese zuerst in GelatoConnect einrichten:
Wechseln Sie zum Bereich Produkte in GelatoConnect
Erstellen Sie Kundenprodukte mit individuellen Namen und Variantenoptionen
Ordnen Sie diese Kundenprodukte den Produktspezifikationen von Gelato zu.
Wann Sie welche Methode wählen sollten
Verwenden Sie Produkt-UIDs in folgenden Fällen:
Sie stehen ganz am Anfang mit GelatoConnect
Sie haben nur wenige festgelegte Produkte.
Sie möchten schnell loslegen, ohne zusätzlichen Aufwand.
Sie erstellen gerade einen Prototyp oder eine Testversion.
Verwenden Sie Kundenprodukte, wenn:
Sie verfügen über einen umfangreichen Produktkatalog
Sie möchten, dass die Produktbezeichnungen in Ihrem Code leichter verständlich sind.
Ihre Produktnamen weichen von den Namenskonventionen von Gelato ab
Produktkonfigurationen können sich im Laufe der Zeit ändern
Beispiele für die Umsetzung
Beispiel für Produkt-UID
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": "ORDER-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]", "phone": "123-456-7890" }, "Artikel": [ { "itemReferenceId": "ITEM-001", "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/files/printfile.pdf" } ] } ]}'Beispiel für Kundenprodukte
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": "ORDER-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]", "phone": "123-456-7890" }, "items": [ { "itemReferenceId": "ITEM-001", "productName": "Flyer", "productVariant": { "Size": "A4", "Paper": "Unbeschichtet 200 g/m²", "Printing": "Vollfarbdruck einseitig" }, "quantity": 100, "files": [ { "type": "Standard", "url": "https://example.com/files/flyer.pdf" } ] } ]}'Empfohlene Vorgehensweisen
Egal, für welchen Weg Sie sich entscheiden, beachten Sie bitte diese bewährten Methoden:
Konsistenz: Bleiben Sie bei einer Herangehensweise während der gesamten Umsetzung
Dokumentation: Halten Sie eine übersichtliche Dokumentation Ihrer Produktzuordnungen bereit
Validierung: Prüfen Sie die Produktkennungen, bevor Sie Bestellungen absenden
Testen: Probieren Sie alles mit Musterbestellungen aus, bevor Sie richtig starten
Fehlerbehandlung: Sorgen Sie für eine zuverlässige Fehlerbehandlung bei ungültigen Produkten
Wechsel zwischen verschiedenen Herangehensweisen
Wenn Sie zunächst mit Produkt-UIDs starten und später auf Kundenprodukte umsteigen möchten:
Richten Sie Ihre Kundenprodukte in GelatoConnect ein
Ordnen Sie sie den Produkt-UIDs zu, die Sie bereits verwendet haben.
Aktualisieren Sie Ihre API-Implementierung, damit sie productName und productVariant verwendet.
Testen Sie alles gründlich, bevor Sie es live schalten.
Der umgekehrte Wechsel ist ebenfalls möglich, kommt aber seltener vor.
Fazit
Beide Ansätze haben ihre Vorteile – welche Sie wählen, hängt ganz von Ihren individuellen Anforderungen und Rahmenbedingungen ab. Produkt-UIDs sind einfach und ermöglichen einen direkten Zugriff auf den Gelato-Katalog, während Kundenprodukte mehr Übersicht, Flexibilität und eine zentrale Verwaltung bieten.
Für die meisten langfristigen Umsetzungen bieten Customer Products Vorteile in Bezug auf Wartungsfreundlichkeit und Übersichtlichkeit. Für schnelle Lösungen oder besondere Anwendungsfälle können jedoch Product UIDs die bessere Wahl sein.
Weitere Informationen zur Einrichtung von Kundenprodukten in GelatoConnect finden Sie im Leitfaden Kundenprodukte erstellen.