¿Qué son las búsquedas y por qué son importantes?
Las búsquedas en GelatoConnect funcionan como tablas de traducción que convierten los datos de tu sistema en formatos que Gelato puede entender. Son clave para una integración fluida de la API, especialmente para mapear:
IDs de producto/SKUs: Convierte tus identificadores de producto personalizados en los UID de producto estandarizados de Gelato
Métodos de envío: Asocia los nombres de tus métodos de envío con los códigos de transportista de Gelato
Identificadores de transportista: Traduce los nombres de los transportistas entre sistemas
Otros mapeos personalizados: Cualquier valor que deba traducirse de forma coherente entre sistemas
Sin búsquedas, los pedidos pueden fallar si los identificadores de tu sistema no coinciden con los valores que espera Gelato. Las búsquedas son el puente seguro que conecta ambos mundos y garantizan que el procesamiento de pedidos sea siempre fluido.
Ventajas principales de usar búsquedas
✅ Las búsquedas garantizan que los datos estén estandarizados para el sistema de Gelato. Así evitamos que haya diferencias entre los valores personalizados de los clientes y los compatibles con Gelato.
✅ Permiten usar valores alternativos para evitar errores si faltan asignaciones.
✅ Las subidas masivas de archivos CSV te ayudan a gestionar grandes volúmenes de asignaciones sin complicaciones.
Cómo configurar búsquedas: guía paso a paso
1. Entra en la página de búsquedas
Inicia sesión en tu cuenta de GelatoConnect
Ve al menú de la izquierda y selecciona Workflow > Order Intake
Haz clic en Lookups para ver los mapeos existentes o crear otros nuevos
2. Crea una nueva tabla de búsqueda
Opción A: Creación manual
Haz clic en el botón Crear que está en la parte superior de la página.
Introduce un nombre descriptivo para tu búsqueda (por ejemplo, "Asignación de SKU de producto")
Selecciona el cliente al que se aplicará esta búsqueda en el menú desplegable.
Añade una Descripción (opcional, pero recomendable) para que sea más fácil identificar el propósito de la búsqueda.
Introduce un campo de plantilla: esta será la referencia que se usará en el código del asignador de plantillas para acceder a esta búsqueda. El campo de plantilla de búsqueda debe ir entre dos llaves dobles (por ejemplo, ##{{sku}}).
Añade asignaciones haciendo clic en el icono +:
Clave: Escribe el valor de tu sistema (por ejemplo, el SKU o el código de tu producto).
Valor: Introduce el valor correspondiente de Gelato (por ejemplo, el UID del producto de Gelato).
Repite este proceso para todos los valores que necesiten asignarse.
Haz clic en Guardar cambios para aplicar la configuración.
Opción B: Importación masiva (recomendado si tienes muchos valores)
Prepara un archivo Excel o CSV con dos columnas:
Columna A: Encabezado "Lookup key" seguido de los valores de tu sistema
Columna B: Encabezado "Product UID" seguido de los valores correspondientes de Gelato
Haz clic en Crear para empezar una nueva búsqueda
Rellena el nombre, el cliente, la descripción y el campo de plantilla como antes.
Haz clic en Importar en vez de añadir las entradas una a una
Selecciona tu archivo Excel o CSV preparado
Revisa las asignaciones importadas
Haz clic en Guardar cambios para terminar la configuración
Guía en vídeo
3. Implementa búsquedas en tu asignador de plantillas
Después de configurar tus tablas de búsqueda, tienes que referenciarlas en el código de tu plantilla mapper (usando Jinja2):
Ve a Workflow > Order Intake > Templates
Edita la plantilla donde quieras usar búsquedas
En la sección de Template Mapper, utiliza la función
lookups()para acceder a tus tablas de mapeo.Sintaxis básica:
##{{ lookups({"alias": value_to_lookup}, strict=False, default="fallback_value")|js }}
Ejemplo 1: Mapeo de UID de producto
{% set productUid = lookups({"sku": item.sku}, strict=False, default=item.sku) %}"productUid": ##{{ productUid|js }},Ejemplo 2: cómo asignar el método de envío
"shipmentMethodUid": ##{{ lookups({"shipping_code": order.shipping.method}, strict=False, default="normal")|js }},El parámetro strict=False asegura que el código no dará error si no se encuentra una coincidencia, y el parámetro default ofrece un valor alternativo por si acaso.
Pon a prueba tus búsquedas
Prueba siempre tus búsquedas antes de usarlas en producción:
Ve a tu plantilla en la sección de Plantillas
Ve a la pestaña Template Testing
Utiliza el formulario de prueba para comprobar que tus búsquedas están traduciendo los valores correctamente.
Comprueba que las claves que faltan utilicen correctamente tu valor predeterminado
Haz un pedido de prueba y comprueba que se procesa como esperas
Usos habituales
Relación entre el SKU del producto y el UID de Gelato
Relaciona tus códigos internos de producto con los UID de producto de Gelato:
{% set productUid = lookups({"sku": item.sku}, strict=False, default=item.sku) %}"productUid": ##{{ productUid|js }},
Traducción del método de envío
Convierte los nombres de tus métodos de envío en los UID de los métodos de envío de Gelato:
{% set shipMethod = lookups({"shipping_method": order.shipping_type}, strict=False, default="normal") %} "shipmentMethodUid": ##{{ shipMethod|js }},
Asignación de transportistas
Relaciona los identificadores de transportista entre sistemas:
{% set carrier = lookups({"carrier_code": shipment.carrier}, strict=False, default=shipment.carrier) %} "carrier": ##{{ carrier|js }},
Correspondencia de códigos de estado según el país
Gestiona los casos especiales de códigos de estado en países concretos:
{% 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 }},
Solución de problemas en las búsquedas
Si tus búsquedas no funcionan como esperabas:
Comprueba si hay coincidencias exactas: Las claves distinguen entre mayúsculas y minúsculas y deben coincidir exactamente con lo que tienes en tus datos de la API.
Verifica los nombres de los campos de la plantilla: Asegúrate de que el campo de la plantilla en tu búsqueda coincida con lo que aparece en tu plantilla
Usa
strict=False: Así evitas errores si falta una clave de búsquedaSiempre ofrece opciones predeterminadas: Establece valores predeterminados adecuados para gestionar los casos en los que falten asignaciones
Consulta toda la información de la solicitud: Ve a la página de Requests para revisar los datos que se están procesando.
Buenas prácticas
Usa nombres descriptivos: Pon nombres claros a las búsquedas para que se entienda su propósito
Añade descripciones: Incluye detalles sobre cuándo y dónde se utiliza cada búsqueda
Mantén los mapeos actualizados: Revisa y actualiza las búsquedas con frecuencia a medida que los productos o servicios cambian
Usa la importación masiva para grandes volúmenes de datos: Ahorra tiempo importando búsquedas de una sola vez
Haz pruebas a fondo: Comprueba siempre las búsquedas tanto con valores que coincidan como con los que no.
Documenta tus búsquedas: Lleva un registro de qué búsquedas utilizas en cada plantilla
¿Quieres saber más?
Ahora que ya has configurado las búsquedas para la integración de tu API, quizá te interese:
Descubre cómo crear una plantilla para la recepción de pedidos
Configura los postbacks para mantener informados a tus clientes