Las plantillas son piezas clave en GelatoConnect que gestionan tanto la entrada como la salida de datos. Se encargan de transformar los datos que recibes de tus clientes en formatos que tu flujo de trabajo puede manejar, y también preparan los datos que salen de GelatoConnect para que encajen con lo que necesita el sistema de tus clientes. En esta guía te acompañaremos paso a paso para crear, probar e implementar plantillas en ambos sentidos del intercambio de datos dentro de la gestión de tus pedidos.
Entender las plantillas en GelatoConnect
Las plantillas en GelatoConnect funcionan como planos que definen cómo debe organizarse, procesarse y presentarse la información. Se encargan de dos flujos de datos fundamentales:
Plantillas de datos entrantes
Estas plantillas convierten los datos que llegan desde los sistemas de tus clientes en formatos que GelatoConnect puede procesar:
Solicitud de envío de pedido: Convierte los datos del pedido del cliente al formato interno de GelatoConnect
Cancelar solicitud: Da formato a las solicitudes de cancelación para que GelatoConnect las entienda
Plantillas de datos salientes
Estas plantillas dan forma a los datos que GelatoConnect envía de vuelta a tus clientes o a sus sistemas:
Formato de respuesta: Da estructura a las respuestas de la API para pedidos realizados o cancelados
Notificaciones de eventos: Crea mensajes claros y uniformes para mantenerte al tanto del estado de tus pedidos
Postbacks: Da forma a los datos que se envían a sistemas externos cuando cambian los estados de los pedidos
Todas las plantillas utilizan el lenguaje de plantillas Jinja2, que ofrece herramientas muy potentes para transformar datos, aplicar lógica condicional y crear contenido dinámico.
Tipos de plantillas que puedes crear
GelatoConnect admite varios tipos de plantillas para diferentes direcciones de flujo de datos:
Plantillas de datos entrantes (Cliente → GelatoConnect)
Solicitud de envío de pedido: Convierte los datos del pedido del cliente al formato de GelatoConnect
Cancelar solicitud: Convierte las solicitudes de cancelación de los clientes al formato de GelatoConnect
Plantillas de datos salientes (GelatoConnect → Cliente)
Enviar respuesta: Da formato a las respuestas enviadas tras realizar un pedido
Respuesta de cancelación: Da formato a las respuestas enviadas tras solicitudes de cancelación
Webhook: Crea paquetes JSON para notificar a sistemas externos cuando cambia el estado de un pedido
Email: Da forma a las notificaciones por correo electrónico para diferentes eventos de pedido
Entender hacia dónde fluye la información es clave al crear plantillas, ya que esto define qué datos tienes a mano y cómo organizarlos.
Guía paso a paso para crear una plantilla
1. Ve a la sección de plantillas
Inicia sesión en tu cuenta de GelatoConnect
Ve a Flujo de trabajo > Recepción de pedidos > Plantillas
Haz clic en el botón Añadir plantilla para empezar a crear una nueva plantilla
2. Elige el tipo de plantilla
Elige el tipo de plantilla que quieres crear:
Para las integraciones de API, normalmente necesitarás las plantillas de Order Submit Request, Submit Response y Cancel Response.
Para las notificaciones, elige Webhook o Correo electrónico
3. Define el formato de la plantilla
Elige el formato para tu plantilla:
JSON: Lo más habitual para integraciones de API y webhooks
XML: Se utiliza en algunos sistemas antiguos
Texto sin formato: Suele usarse para plantillas de correo electrónico
4. Genera un ejemplo de datos de entrada
Para crear una plantilla eficaz, primero tienes que saber qué datos tendrás disponibles:
Haz clic en el botón Generar plantilla
Selecciona Añadir entrada de muestra para añadir datos de prueba
Elige el tipo de evento adecuado en el menú desplegable:
Pedido recibido
Pedido no realizado
Pedido cancelado
Pedido devuelto
Pedido producido
Pedido entregado
Orden enviada
Pedido en camino
El sistema rellenará un ejemplo de carga con datos habituales para ese evento, que puedes usar como referencia al crear tu plantilla.
5. Crea tu asignador de plantillas
El Template Mapper es el lugar donde decides cómo se transforma la información entre diferentes formatos:
En la sección Template Mapper, escribe tu plantilla usando la sintaxis de Jinja2
Consulta los datos de referencia del contenido recibido usando llaves dobles:
####{{ variable }}Añade filtros de formato usando el símbolo de barra vertical:
####{{ variable|js }}(el filtrojsadapta las cadenas para JSON)Utiliza estructuras de control como
{% if %},{% for %}y{% set %}para lógica condicional y bucles
Aspectos a tener en cuenta sobre la orientación de la plantilla
El contenido de tu plantilla cambiará según si gestionas datos entrantes o salientes:
Para las plantillas de datos entrantes (Cliente → GelatoConnect):
Concéntrate en extraer datos de formatos personalizados para cada cliente
Asocia los nombres de campos personalizados con los nombres estándar de campos de GelatoConnect
Valida y transforma los datos para que cumplan con los requisitos de GelatoConnect
Gestiona cualquier formato especial o necesidad de conversión de datos
Para las plantillas de datos salientes (GelatoConnect → Cliente):
Organiza los datos según lo que espera el sistema del cliente
Incluye todos los campos necesarios para la integración del cliente
Da formato a las fechas, los valores de moneda y otros datos según las preferencias del cliente
Añade cualquier identificador o referencia específico del cliente
Ejemplo: plantilla de Webhook para pedido recibido
Aquí tienes una plantilla de ejemplo para un webhook de "Pedido recibido":
{ "event": "Pedido recibido", "orderId": "####{{ orderId }}", "orderReferenceId": "####{{ orderReferenceId }}", "timestamp": "####{{ created }}", "status": "####{{ fulfillmentStatus }}", "items": [ {% for item in items %} { "itemReferenceId": "####{{ item.itemReferenceId }}", "status": "####{{ item.fulfillmentStatus }}" }{% if not loop.last %},{% endif %} {% endfor %} ], "message": "Hemos recibido tu pedido."}Esta plantilla crea una estructura JSON con los detalles del pedido y recorre todos los artículos del pedido.
6. Renderiza y comprueba la plantilla
Después de crear tu plantilla:
Haz clic en el botón Render para compilar la plantilla
Revisa el resultado en el panel de vista previa
Comprueba que todos los datos estén bien formateados y que no haya errores de sintaxis
Comprueba si faltan campos o si alguno está mal rellenado
7. Prueba tu plantilla
Probar es fundamental para asegurarte de que tu plantilla funciona correctamente:
Ponle un nombre a tu prueba en la sección Plantilla de prueba
Haz clic en Ejecutar prueba para poner a prueba la plantilla con los datos de ejemplo
Comprueba que el Estado aparezca como Aprobado
Revisa el resultado para asegurarte de que cumple con lo que esperabas
8. Guarda tu plantilla
Cuando estés contento con la plantilla:
Ponle un nombre que lo describa bien a tu plantilla
Haz clic en Añadir plantilla o Guardar cambios para guardarlo
La plantilla ya estará disponible para usar en los disparadores y en la configuración de flujos de trabajo.
Cómo usar plantillas con activadores
Los templates se suelen usar con triggers para automatizar notificaciones cuando ocurren eventos concretos:
1. Crea un disparador
Ve a Flujo de trabajo > Recepción de pedidos > Disparadores
Haz clic en Añadir desencadenador
Selecciona el cliente al que se aplica este desencadenante
Ponle un nombre a tu activador (por ejemplo, "Notificación de pedido recibido")
Selecciona el evento que activará el disparador (por ejemplo, "Pedido recibido")
2. Configura el método de entrega
Elige cómo quieres recibir las notificaciones:
URL: Envía un webhook a un sistema externo
Indica la URL de destino
Elige el método POST o GET
Elige el formato JSON o XML
Configura las opciones de reintento si lo deseas
Email: Envía una notificación por correo electrónico
Introduce las direcciones de correo electrónico de los destinatarios
Añade una línea de asunto
Indica el nombre y la dirección del remitente
3. Elige tu plantilla
En el menú desplegable de Plantilla, selecciona la plantilla que creaste antes.
Si no existe ninguna plantilla, puedes crear una directamente en la configuración del disparador usando la misma interfaz que te hemos mostrado arriba.
Crea plantillas directamente desde los desencadenantes
Para que te resulte más fácil, también puedes crear plantillas mientras configuras los desencadenantes:
Al crear un trigger, en vez de elegir una plantilla existente, haz clic en Crear plantilla.
Define el formato de la plantilla (JSON, XML o texto sin formato)
Usa el editor de plantillas para crear tu plantilla como te hemos explicado arriba.
Guarda la plantilla y se seleccionará automáticamente para este disparador.
Este método es muy útil para crear una plantilla rápidamente cuando ya estás configurando un disparador.
Vincular plantillas con los endpoints de la API
Al enviar pedidos a través de la API, a menudo tendrás que adaptar los datos entre tu formato y el formato de GelatoConnect. Las plantillas se encargan de esta transformación, pero debes vincular tu plantilla al endpoint de la API para que se aplique correctamente.
Cómo vincular una plantilla a un endpoint de envío de pedidos:
Ve a tu lista de conectores y haz clic en el enlace Editar que está junto al endpoint de envío de pedidos.
En la página de configuración del endpoint, busca la sección Plantilla de endpoint
Elige tu plantilla para enviar pedidos en el menú desplegable
Haz clic en el botón Establecer endpoint en la esquina superior derecha de la página
Haz clic en Guardar cambios en la parte superior derecha para aplicar tu configuración
Después de completar estos pasos, todos los pedidos enviados a este endpoint usarán tu plantilla para transformar los datos antes de procesarlos. Así te aseguras de que el formato de tu sistema se convierta correctamente al formato que espera GelatoConnect.
Sin esta configuración, tu plantilla no se aplicará aunque exista y esté bien diseñada, lo que puede provocar errores al validar pedidos si el formato de tus datos no coincide exactamente con los requisitos de GelatoConnect.
Técnicas avanzadas de plantillas
Cómo usar las búsquedas
Las búsquedas son especialmente útiles para mapear datos en ambas direcciones entre sistemas. Funcionan de manera diferente según la dirección de la plantilla:
Para plantillas entrantes (cliente → GelatoConnect):
Asocia los valores personalizados de tus clientes con los valores estándar de GelatoConnect:
{% set shipMethod = lookups({"shipping_code": order.shipping.method}, strict=False, default="normal") %} "shipmentMethodUid": ####{{ shipMethod|js }},Para las plantillas salientes (GelatoConnect → Cliente):
Convierte los valores internos de GelatoConnect en formatos que tus clientes esperan:
{% set customerShippingCode = lookups({"gelatoShipMethod": shipment.shipmentMethodUid}, strict=False, default=shipment.shipmentMethodUid) %} "shipping_method": ####{{ customerShippingCode|js }},Lógica condicional
Usa condiciones para incluir o dar formato a los datos de manera diferente según la situación:
{% if item.fulfillmentStatus == "shipped" %} "trackingNumber": "####{{ item.trackingCode }}", "trackingUrl": "####{{ item.trackingUrl }}",{% endif %}Asignación de variables
Crea variables para que las expresiones complejas sean pan comido:
{% set fullName = customer.firstName + " " + customer.lastName %} "recipientName": "####{{ fullName }}",Bucles con objetos complejos
Navega por estructuras de datos anidadas:
"items": [ {% for item in items %} { "sku": "####{{ item.sku }}", "quantity": ####{{ item.quantity }}, "opciones": [ {% for option in item.options %} { "name": "####{{ option.name }}", "value": "####{{ option.value }}" }{% if not loop.last %},{% endif %} {% endfor %} ] }{% if not loop.last %},{% endif %} {% endfor %}]Buenas prácticas para plantillas
Convenciones de nombres según la dirección
Usa nombres claros y descriptivos que indiquen tanto el propósito como la dirección del flujo de datos
Para las plantillas entrantes: incluye prefijos como "IN_" o sufijos como "_Request"
Para las plantillas salientes: utiliza prefijos como "OUT_" o sufijos como "_Response" o "_Notification"
Incluye el nombre del cliente para plantillas personalizadas para cada cliente
Usa nombres coherentes para que encontrar las plantillas sea pan comido
Gestión de errores
Establece valores predeterminados para evitar errores por referencias nulas
Utiliza el filtro
defaultpara los valores que faltan:####{{ variable|default('N/A') }}Utiliza bloques
try/exceptpara las partes del código que puedan dar problemas
Mantenimiento
Añade comentarios para explicar la lógica compleja:
{# Esto gestiona el caso especial de los pedidos internacionales #}Mantén las plantillas modulares y centradas en objetivos concretos
Actualiza las plantillas cuando cambien las estructuras de datos o los requisitos
Probando
Haz pruebas con diferentes situaciones de datos, incluso las más extremas
Verifica las plantillas con datos reales de producción siempre que puedas
Crea pruebas completas para las plantillas más importantes
Solucionar problemas con las plantillas
Problemas habituales y cómo solucionarlos
Problema | Posible motivo | Solución |
Error de sintaxis | Paréntesis o comillas que no encajan | Revisa bien la sintaxis de la plantilla; asegúrate de que todas las etiquetas de apertura tengan su etiqueta de cierre correspondiente. |
Faltan datos | Hablando de campos que no existen | Comprueba que los nombres de los campos coincidan con los del contenido recibido y añade valores predeterminados para los campos opcionales. |
Problemas de formato | Uso incorrecto del filtro | Confirma que estás usando correctamente los filtros como |
Plantilla no aplicada | Plantilla no vinculada al desencadenante | Verifica la configuración del disparador y la selección de la plantilla |
Errores al acceder a datos anidados | Ruta incorrecta a las propiedades anidadas | Revisa la estructura de los datos y ajusta las rutas de las propiedades según sea necesario |
Errores al asignar campos | Nombres de campos incorrectos para los datos entrantes o salientes | Para las plantillas entrantes, revisa los nombres de los campos de cliente; para las plantillas salientes, asegúrate de que el formato de respuesta sea el esperado. |
Problemas al transformar los datos | Formatos de datos incompatibles | Asegúrate de convertir correctamente los tipos de datos entre sistemas (fechas, números, etc.). |
Consejos para resolver problemas
Usa el botón Render a menudo mientras desarrollas para detectar errores cuanto antes.
Añade una salida temporal de depuración para ver los valores de las variables
Revisa si hay errores de escritura en los nombres de los campos, ya que suelen ser una fuente habitual de problemas.
Recuerda que Jinja2 distingue entre mayúsculas y minúsculas al referirse a las variables.