Passer au contenu principal

[Order Intake - GCW] Configurer les Lookups pour l'intégration API

Écrit par Kyle Sawyer

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

✅ Standardisation : Garantit la cohérence des données entre votre système et Gelato
✅ Prévention des erreurs : Réduit les échecs dus à des identifiants incompatibles
✅ Protection de secours : Fournit des valeurs par défaut si aucune correspondance exacte n'est trouvée
✅ Évolutivité : Facilite la gestion de l'ajout de nouveaux produits ou méthodes d'expédition
✅ Maintenance : Gestion centralisée des mappings pour des mises à jour plus faciles

Configuration des recherches : guide étape par étape

1. Accéder à la page des consultations

  1. Connectez-vous à votre compte GelatoConnect

  2. Naviguez vers Flux de travail > Réception des commandes dans le menu de gauche

  3. 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

  1. Cliquez sur le bouton Create en haut de la page

  2. Saisissez un Nom descriptif pour votre recherche (par ex., « Correspondance des UGS de produits »)

  3. Sélectionnez le client auquel ce lookup s'appliquera dans le menu déroulant

  4. Ajoutez une Description (facultative mais recommandée) pour aider à identifier l'objectif du lookup

  5. Saisissez un champ de modèle - il s'agit de la référence utilisée dans le code du mappeur de modèle pour accéder à ce lookup

  6. Ajoutez des mappages en cliquant sur l'icône + :

    • Clé : Saisissez la valeur de votre système (par exemple, votre UGS de produit ou code)

    • Valeur : Saisissez la valeur Gelato correspondante (par exemple, l'UID du produit Gelato)

  7. Répétez pour toutes les valeurs qui nécessitent un mappage

  8. Cliquez sur Enregistrer les modifications pour appliquer la configuration

Option B : Import en masse (recommandé pour de nombreuses valeurs)

  1. Préparez un fichier Excel ou CSV avec deux colonnes :

    • Colonne A : En-tête « lookup key » suivi des valeurs de votre système

    • Colonne B : En-tête « UID produit » suivi des valeurs correspondantes de Gelato

  2. Cliquez sur Créer pour commencer une nouvelle recherche

  3. Remplissez le Nom, le Client, la Description et le Champ de modèle comme ci-dessus

  4. Cliquez sur Importer au lieu d'ajouter manuellement des entrées

  5. Sélectionnez votre fichier Excel/CSV préparé

  6. Vérifiez les correspondances importées

  7. Cliquez sur Enregistrer les modifications pour terminer la configuration

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) :

  1. Allez à Flux de travail > Réception des commandes > Modèles

  2. Modifiez le modèle où vous souhaitez utiliser des recherches

  3. Dans la section Mappeur de modèles, utilisez la fonction lookups() pour accéder à vos tables de correspondance

  4. Syntaxe 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 :

  1. Allez à votre modèle dans la section Templates

  2. Accédez à l'onglet Test de modèle

  3. Utilisez le formulaire de test pour vérifier que vos recherches traduisent correctement les valeurs.

  4. Vérifiez que les clés manquantes utilisent bien votre valeur par défaut.

  5. 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

Prochaines étapes

Maintenant que vous avez configuré les recherches pour l'intégration de votre API, vous pourriez vouloir :

  1. Découvrez comment créer un modèle pour Order Intake

  2. Découvrez les techniques avancées de Template Mapper

  3. Configurer les Postbacks automatiques pour mettre à jour les clients

Besoin d'aide supplémentaire ? Contactez notre équipe d'assistance à l'adresse [email protected]

Articles connexes
Avez-vous trouvé la réponse à votre question ?