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
✅ Standardisierung: Stellt die Datenkonsistenz zwischen Ihrem System und Gelato sicher
✅ Fehlervermeidung: Reduziert Ausfälle durch nicht übereinstimmende Kennungen
✅ Fallback-Schutz: Liefert Standardwerte, wenn keine exakten Übereinstimmungen gefunden werden
✅ Skalierbarkeit: macht es leichter, neue Produkte oder Versandmethoden zu verwalten
✅ Wartung: Zentrale Verwaltung von Zuordnungen für einfachere Aktualisierungen
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
Klicke oben auf der Seite auf die Schaltfläche Create
Geben Sie einen aussagekräftigen Namen für Ihre Suche ein (zum Beispiel "Artikelnummer-Zuordnung")
Wählen Sie im Dropdown den Customer aus, auf den dieses Lookup angewendet wird
Fügen Sie eine Beschreibung hinzu (optional, aber empfohlen), damit Sie den Zweck des Lookups leichter erkennen können
Geben Sie ein Vorlagenfeld ein – dies ist die Referenz, die im Template-Mapper-Code verwendet wird, um auf dieses Lookup zuzugreifen.
Fügen Sie Zuordnungen hinzu, indem Sie auf das +-Symbol klicken:
Schlüssel : Geben Sie den Wert aus Ihrem System ein (z. B. Ihre Produkt-Artikelnummer oder Ihr Produktcode)
Wert: Geben Sie den entsprechenden Gelato-Wert ein (z. B. die Produkt-UID von Gelato)
Wiederholen Sie dies für alle Werte, die zugeordnet werden müssen
Klicken Sie auf Änderungen speichern, um die Konfiguration anzuwenden
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.
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
Nächste Schritte
Jetzt, wo Sie die Suchfunktionen für Ihre API-Integration eingerichtet haben, könnten Sie Folgendes tun:
Erfahren Sie, wie Sie eine Vorlage für Order intake erstellen
Entdecken Sie fortgeschrittene Template-Mapper-Techniken
Automatische Postbacks einrichten, um Kund:innen zu informieren
Sie brauchen weitere Hilfe? Kontaktieren Sie unser Support-Team unter [email protected]