¿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

✅ Estandarización: Garantiza la coherencia de los datos entre tu sistema y Gelato
✅ Prevención de errores: reduce los fallos debidos a identificadores que no coinciden
✅ Protección de respaldo: Proporciona valores predeterminados si no se encuentran coincidencias exactas
✅ Escalabilidad: facilita la gestión a la hora de añadir nuevos productos o métodos de envío
✅ Mantenimiento : gestión centralizada de asignaciones para facilitar las actualizaciones

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 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á este lookup en la lista desplegable
Añade una descripción (opcional pero recomendable) para ayudarte a identificar la finalidad del Lookup
Introduzca un campo de plantilla; es la referencia que se utiliza en el código del asignador de plantillas para acceder a este Lookup
Añade asignaciones haciendo clic en el icono +:
- Clave : Introduce el valor de tu sistema (por ejemplo, el SKU o código de tu producto)
- Valor: Introduzca el valor correspondiente de Gelato (por ejemplo, el UID de producto de Gelato)
Repita esto 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

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úsqueda
Siempre 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

Próximos pasos

Ahora que ya has configurado las búsquedas para la integración de tu API, quizá te interese:

Aprenda a crear una plantilla para Order intake
Descubre técnicas avanzadas de Template Mapper
Configura Postbacks automáticos para mantener a tus clientes al día

¿Necesita más ayuda? Póngase en contacto con nuestro equipo de asistencia en [email protected]

[Order Intake - GCW] Configurar Lookups para la integración de API