Que sont les recherches et pourquoi sont-elles importantes ?
Les recherches dans GelatoConnect servent de tables de correspondance qui transforment les données de votre système dans des formats compréhensibles par Gelato. Elles sont essentielles pour une intégration API fluide, notamment pour faire le lien entre :
Identifiants de produits/UGS : Convertissez vos identifiants de produits Personnalisés en UIDs de produits standardisés de Gelato
Méthodes d'expédition : Associez les noms de vos méthodes d'expédition aux codes transporteur de Gelato
Identifiants de transporteur : Traduire les noms de transporteurs entre les systèmes
Autres mappages personnalisés : Toute valeur nécessitant une traduction cohérente entre les systèmes
Sans recherches, les commandes risquent d'échouer lorsque les identifiants de votre système ne correspondent pas aux valeurs attendues par Gelato. Les recherches offrent un moyen fiable de combler cet écart, garantissant ainsi un traitement des commandes cohérent.
Principaux avantages de l’utilisation des recherches
✅ Les recherches garantissent que les données sont standardisées pour le système de Gelato. Cela évite les écarts entre les valeurs propres à chaque client et celles compatibles avec Gelato.
✅ Ils permettent des valeurs de secours pour éviter les erreurs en cas de mappages manquants.
✅ Les téléchargements CSV en masse facilitent la gestion des mappages à grande échelle.
Configuration des recherches : guide étape par étape
1. Accéder à la page des consultations
Connectez-vous à votre compte GelatoConnect
Naviguez vers Flux de travail > Réception des commandes dans le menu de gauche
Cliquez sur Lookups pour consulter les mappages existants ou en créer de nouveaux
2. Créer un nouveau tableau de consultation
Option A : Création manuelle
Cliquez sur le bouton Créer en haut de la page.
Saisissez un Nom descriptif pour votre recherche (par ex., « Correspondance des UGS de produits »)
Sélectionnez le Client auquel cette recherche s'appliquera dans le menu déroulant.
Ajoutez une Description (facultative mais recommandée) pour faciliter l'identification de l'objectif de la recherche.
Saisissez un Champ de modèle - il s'agit de la référence utilisée dans le code du mappeur de modèles pour accéder à cette recherche. Le champ de modèle de recherche doit être entouré de doubles accolades (par exemple, ##{{sku}}).
Ajoutez des mappages en cliquant sur l'icône + :
Clé : Saisissez la valeur de votre système (par ex., votre UGS ou code produit).
Valeur : Saisissez la valeur Gelato correspondante (par ex., l'UID du produit Gelato).
Répétez pour toutes les valeurs qui nécessitent un mappage.
Cliquez sur Enregistrer les modifications pour appliquer la configuration.
Option B : Import en masse (recommandé pour de nombreuses valeurs)
Préparez un fichier Excel ou CSV avec deux colonnes :
Colonne A : En-tête « Clé de recherche » suivi des valeurs de votre système
Colonne B : En-tête \"UID du produit\" suivi des valeurs correspondantes de Gelato
Cliquez sur Créer pour commencer une nouvelle recherche
Remplissez le Nom, le Client, la Description et le Champ de modèle comme ci-dessus
Cliquez sur Importer au lieu d'ajouter manuellement des entrées
Sélectionnez votre fichier Excel/CSV préparé
Vérifiez les correspondances importées
Cliquez sur Enregistrer les modifications pour terminer la configuration
Guide vidéo
3. Mettre en œuvre les recherches dans votre mappeur de modèles
Après avoir configuré vos tables de correspondance, vous devez les référencer dans le code de votre modèle de mappage (en utilisant Jinja2) :
Allez à Flux de travail > Réception des commandes > Modèles
Modifiez le modèle où vous souhaitez utiliser des recherches
Dans la section Mappeur de modèles, utilisez la fonction
lookups()pour accéder à vos tables de correspondanceSyntaxe de base :
##{{ lookups({\"alias\": value_to_lookup}, strict=False, default=\"fallback_value\")|js }}
Exemple 1 : correspondance des UID de produit
{% set productUid = lookups({\"sku\": item.sku}, strict=False, default=item.sku) %}\"productUid\": ##{{ productUid|js }},Exemple 2 : Mappage des méthodes d'expédition
"shipmentMethodUid": ##{{ lookups({"shipping_code": order.shipping.method}, strict=False, default="normal")|js }},Le paramètre strict=False garantit que le code ne produira pas d’erreur si aucune correspondance n’est trouvée, et le paramètre default permet d’indiquer une valeur de remplacement.
Test de vos recherches
Testez toujours vos recherches avant de les utiliser en production :
Allez à votre modèle dans la section Templates
Accédez à l'onglet Test de modèle
Utilisez le formulaire de test pour vérifier que vos recherches traduisent correctement les valeurs.
Vérifiez que les clés manquantes utilisent bien votre valeur par défaut.
Passez une commande test et vérifiez que tout se déroule comme prévu.
Cas d'utilisation courants
Correspondance entre UGS produit et UID Gelato
Associez vos codes produits internes aux UID de Gelato :
{% set productUid = lookups({\"sku\": item.sku}, strict=False, default=item.sku) %}"productUid": ##{{ productUid|js }},
Traduction du mode d'expédition
Convertissez les noms de vos modes d'expédition en UID de méthode d'expédition Gelato :
{% set shipMethod = lookups({\"shipping_method\": order.shipping_type}, strict=False, default=\"normal\") %} \"shipmentMethodUid\": ##{{ shipMethod|js }},
Cartographie des transporteurs
Associer les identifiants de transporteur entre les systèmes :
{% set carrier = lookups({\"carrier_code\": shipment.carrier}, strict=False, default=shipment.carrier) %} \"carrier\": ##{{ carrier|js }},
Correspondance des codes régionaux par pays
Gérer les cas particuliers pour les codes d'état dans des pays spécifiques :
{% 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 }},
Dépannage des recherches
Si vos recherches ne fonctionnent pas comme prévu :
Vérifiez les correspondances exactes : Les clés sont sensibles à la casse et doivent correspondre exactement à ce qui se trouve dans vos données API
Vérifiez les noms des champs du modèle : Assurez-vous que le champ du modèle dans votre recherche correspond à ce qui est indiqué dans votre modèle
Utilisez
strict=False: Cela évite les erreurs si une clé de recherche manque.Toujours fournir des valeurs par défaut : Définissez des valeurs par défaut appropriées pour gérer les mappages manquants
Vérifiez la charge utile complète de la requête : Utilisez la page Requêtes pour examiner la charge utile en cours de traitement
Bonnes pratiques
Utilisez des noms explicites : Donnez des noms clairs aux recherches pour indiquer leur objectif
Ajouter des descriptions : Incluez des détails sur quand et où chaque recherche est utilisée
Maintenir les mappages à jour : Examinez et mettez à jour régulièrement les correspondances lorsque les produits ou services changent
Utilisez l'importation en masse pour les grands ensembles de données : Gagnez du temps en important des recherches en masse
Testez en profondeur : Vérifiez toujours les recherches avec des valeurs qui correspondent et d'autres qui ne correspondent pas.
Notez vos recherches : Gardez une trace des recherches utilisées dans chaque modèle
Vous souhaitez en savoir plus ?
Maintenant que vous avez configuré les recherches pour l'intégration de votre API, vous pourriez vouloir :
Découvrez comment créer un modèle pour la saisie de commandes
Configurez les postbacks pour tenir vos clients informés