Was sind Lookups und warum sind sie wichtig?
Lookups in GelatoConnect funktionieren wie Übersetzungstabellen, die Daten aus Ihrem System in ein Format umwandeln, das Gelato versteht. Sie sind unverzichtbar für eine reibungslose API-Integration, insbesondere wenn es darum geht, Folgendes zuzuordnen:
Produkt-IDs/SKUs: Wandeln Sie Ihre personalisierten Produktkennungen in die standardisierten Produkt-UIDs von Gelato um
Versandarten: Ordnen Sie Ihre Versandartnamen den Carrier-Codes von Gelato zu
Trägerkennungen: Übersetzen Sie die Namen der Versanddienstleister zwischen den Systemen
Weitere personalisierte Zuordnungen: Jeder Wert, der zwischen Systemen einheitlich übersetzt werden muss
Ohne Lookups kann es passieren, dass Bestellungen fehlschlagen, wenn die Kennungen Ihres Systems nicht mit den erwarteten Werten von Gelato übereinstimmen. Lookups schaffen hier eine verlässliche Verbindung und sorgen dafür, dass Ihre Bestellungen reibungslos verarbeitet werden.
Die wichtigsten Vorteile von Lookups
✅ Mit Lookups stellen Sie sicher, dass Ihre Daten für das Gelato-System einheitlich sind. So vermeiden Sie, dass es zu Abweichungen zwischen kundenspezifischen und Gelato-kompatiblen Werten kommt.
✅ Sie ermöglichen Ersatzwerte, damit bei fehlenden Zuordnungen keine Fehler auftreten.
✅ Mit dem Hochladen von CSV-Dateien in großen Mengen behalten Sie auch bei vielen Zuordnungen ganz einfach den Überblick.
Lookups einrichten: Schritt-für-Schritt-Anleitung
1. Öffnen Sie die Seite „Lookups“
Melden Sie sich bei Ihrem GelatoConnect-Konto an
Wechseln Sie im linken Menü zu Workflow > Auftragseingang
Klicken Sie auf Lookups, um vorhandene Zuordnungen anzusehen oder neue zu erstellen.
2. Neue Nachschlagetabelle erstellen
Option A: Manuelle Erstellung
Klicken Sie oben auf der Seite auf die Schaltfläche Erstellen.
Geben Sie einen aussagekräftigen Namen für Ihre Suche ein (zum Beispiel "Artikelnummer-Zuordnung")
Wählen Sie den Kunden aus der Dropdown-Liste aus, für den diese Suche gelten soll.
Fügen Sie eine Beschreibung hinzu (optional, aber empfohlen), um den Zweck der Suche leichter zu erkennen.
Geben Sie ein Vorlagenfeld ein – dies ist die Referenz, die im Template Mapper-Code verwendet wird, um auf dieses Lookup zuzugreifen. Das Lookup-Vorlagenfeld muss von doppelten geschweiften Klammern umgeben sein (z. B. ##{{sku}}).
Fügen Sie Zuordnungen hinzu, indem Sie auf das +-Symbol klicken:
Wichtig: Geben Sie den Wert aus Ihrem System ein (zum Beispiel Ihre Artikelnummer oder Ihren Code).
Wert: Geben Sie den passenden Gelato-Wert ein (zum Beispiel die Produkt-UID von Gelato).
Wiederholen Sie diesen Schritt für alle Werte, die zugeordnet werden müssen.
Klicken Sie auf Änderungen speichern, um die Konfiguration zu übernehmen.
Option B: Massenimport (empfohlen bei vielen Werten)
Bereiten Sie eine Excel- oder CSV-Datei mit zwei Spalten vor:
Spalte A: Überschrift „Lookup key“, gefolgt von den Werten Ihres Systems
Spalte B: Überschrift „Product UID“, gefolgt von den entsprechenden Werten von Gelato
Klicken Sie auf Erstellen, um eine neue Suche zu starten
Tragen Sie den Namen, den Kunden, die Beschreibung und das Vorlagenfeld wie oben ein.
Klicken Sie auf Importieren, anstatt die Einträge mühsam von Hand hinzuzufügen.
Wählen Sie Ihre vorbereitete Excel- oder CSV-Datei aus
Überprüfen Sie die importierten Zuordnungen
Klicken Sie auf Änderungen speichern, um die Einrichtung abzuschließen.
Videoanleitung
3. Verwenden Sie Nachschlagefunktionen in Ihrem Template Mapper
Nachdem Sie Ihre Lookup-Tabellen eingerichtet haben, müssen Sie diese in Ihrem Template-Mapper-Code (mit Jinja2) einbinden:
Gehen Sie zu Workflow > Auftragseingang > Vorlagen
Bearbeiten Sie die Vorlage, in der Sie Nachschlagen verwenden möchten
Im Bereich Template Mapper können Sie die Funktion
lookups()nutzen, um auf Ihre Zuordnungstabellen zuzugreifen.Grundlegende Syntax:
##{{ lookups({"alias": value_to_lookup}, strict=False, default="fallback_value")|js }}
Beispiel 1: Produkt-UID-Zuordnung
{% set productUid = lookups({"sku": item.sku}, strict=False, default=item.sku) %}"productUid": ##{{ productUid|js }},Beispiel 2: Zuordnung der Versandmethode
"shipmentMethodUid": ##{{ lookups({"shipping_code": order.shipping.method}, strict=False, default="normal")|js }},Der Parameter strict=False sorgt dafür, dass kein Fehler auftritt, wenn keine Übereinstimmung gefunden wird. Mit dem Parameter default können Sie einen Ersatzwert festlegen.
So testen Sie Ihre Suchfunktionen
Testen Sie Ihre Suchabfragen immer, bevor Sie sie im Live-Betrieb einsetzen:
Gehen Sie zu Ihrer Vorlage im Bereich Vorlagen.
Wechseln Sie zum Tab Vorlagen-Test
Nutzen Sie das Testformular, um zu prüfen, ob Ihre Abfragen die Werte richtig übersetzen.
Prüfen Sie, ob fehlende Schlüssel automatisch mit Ihrem Standardwert ersetzt werden
Geben Sie eine Testbestellung auf und prüfen Sie, ob alles wie erwartet abläuft.
Typische Anwendungsfälle
Artikelnummer-zu-Gelato-UID-Zuordnung
Ordnen Sie Ihre internen Produktcodes den Produkt-UIDs von Gelato zu:
{% set productUid = lookups({"sku": item.sku}, strict=False, default=item.sku) %}"productUid": ##{{ productUid|js }},
Übersetzung der Versandmethode
Wandeln Sie Ihre Versandartnamen in die UID der Gelato-Versandmethode um:
{% set shipMethod = lookups({"shipping_method": order.shipping_type}, strict=False, default="normal") %} "shipmentMethodUid": ##{{ shipMethod|js }},
Versanddienstleister-Zuordnung
Verknüpfen Sie die Versanddienstleister-IDs zwischen den Systemen:
{% set carrier = lookups({"carrier_code": shipment.carrier}, strict=False, default=shipment.carrier) %} "carrier": ##{{ carrier|js }},
Länderspezifische Zuordnung von Bundesland-Codes
Gehen Sie auf besondere Fälle bei den Ländercodes in bestimmten Ländern ein:
{% set stateCode = shipTo.state %}{% if shipTo.country|upper == "US" %} {% set stateCode = lookups({"us_state": shipTo.state}, strict=False, default=shipTo.state) %}{% endif %}"state": ##{{ stateCode|js }},
Fehlerbehebung bei Suchvorgängen
Wenn Ihre Suchvorgänge nicht wie gewünscht funktionieren:
Prüfen Sie auf exakte Übereinstimmungen: Die Schlüssel unterscheiden zwischen Groß- und Kleinschreibung und müssen exakt mit den Angaben in Ihren API-Daten übereinstimmen.
Vorlagenfeldnamen überprüfen: Stellen Sie sicher, dass das Feld in Ihrer Suche mit dem im Template verwendeten Namen übereinstimmt.
Verwenden Sie
strict=False: So vermeiden Sie Fehler, wenn ein Suchbegriff fehltImmer mit sinnvollen Voreinstellungen arbeiten: Legen Sie passende Standardwerte fest, um fehlende Zuordnungen abzufangen.
Sehen Sie sich die vollständigen Anfragedaten an: Nutzen Sie die Seite "Anfragen", um die verarbeiteten Daten im Detail zu prüfen.
Empfohlene Vorgehensweisen
Verwenden Sie aussagekräftige Namen: Benennen Sie Lookups so, dass ihr Zweck klar erkennbar ist
Beschreibungen hinzufügen: Geben Sie an, wann und wo jede Abfrage verwendet wird
Halten Sie Ihre Zuordnungen aktuell: Überprüfen und aktualisieren Sie Ihre Suchzuordnungen regelmäßig, wenn sich Produkte oder Dienstleistungen ändern.
Nutzen Sie den Massenimport für große Datensätze: Sparen Sie Zeit, indem Sie mehrere Einträge auf einmal importieren
Gründlich testen: Probieren Sie Suchvorgänge immer mit passenden und nicht passenden Werten aus.
Dokumentieren Sie Ihre Nachschlagen: Halten Sie fest, welche Nachschlagen in welchen Vorlagen verwendet werden
Möchten Sie mehr erfahren?
Jetzt, wo Sie die Suchfunktionen für Ihre API-Integration eingerichtet haben, könnten Sie Folgendes tun:
Erfahren Sie mehr darüber, wie Sie eine Vorlage für den Auftragseingang erstellen können: Vorlage für den Auftragseingang erstellen
Richten Sie Postbacks ein, um Ihre Kundinnen und Kunden auf dem Laufenden zu halten