¿Qué son los mapeadores de plantillas?

Los mapeadores de plantillas en GelatoConnect son herramientas potentes que transforman los datos entre el formato de tu sistema y el de GelatoConnect. Funcionan como traductores, asegurando que la información fluya sin obstáculos entre distintos sistemas, sin importar cómo organice cada uno sus datos.

Tanto si envías pedidos a GelatoConnect como si recibes actualizaciones sobre cambios en el estado de los pedidos, los mapeadores de plantillas te permiten convertir formatos de datos sin tener que modificar tus sistemas actuales.

¿Por qué elegir los Template Mappers?

Los mapeadores de plantillas resuelven varios de los retos más habituales a la hora de integrar sistemas:

Diferentes estructuras de datos: Tu sistema y GelatoConnect pueden organizar la misma información de formas distintas.
Diferencias en los nombres de los campos: Puede que tu sistema llame a la dirección de envío "delivery_address", mientras que GelatoConnect la llama "shippingAddress".
Conversiones de formato: Puede que necesites adaptar los formatos de los datos, como cambiar la forma en que se muestran las fechas o transformar las unidades de medida.
Mapeo selectivo de campos: Puede que solo quieras incluir ciertos campos de tus datos al enviarlos a GelatoConnect.
Lógica condicional: Puede que necesites aplicar diferentes reglas de asignación según ciertas condiciones, como el tipo de pedido o el país de destino.

Cómo funcionan los Template Mappers

GelatoConnect utiliza el lenguaje de plantillas Jinja2 para sus mapeadores de plantillas. Este lenguaje, potente y flexible, te permite:

Extrae valores: Obtén datos de tu formato de entrada
Transforma los datos: Aplica funciones y lógica para modificar la información
Resultado final: Prepara el resultado final en el formato que espera GelatoConnect

Un mapeador de plantillas toma una entrada (tus datos) y genera una salida (datos compatibles con GelatoConnect) según las reglas de transformación que definas.

Componentes del asignador de plantillas

Un mapeador de plantillas típico en GelatoConnect se compone de estos elementos:

1. Introduce los datos

Estos son los datos originales que quieres transformar. Puede ser:

Datos de pedidos de tu sistema de comercio electrónico
Información de clientes de tu CRM
Detalles del producto de tu catálogo

2. Definición de plantilla

Aquí es donde decides cómo transformar los datos de entrada. Usando la sintaxis de Jinja2, puedes indicar:

Qué campos quieres extraer de la entrada
¿Quieres hacer algún cambio?
La estructura del resultado

3. Formato de salida

El resultado del procesamiento de la plantilla, normalmente en formato JSON que cumple con los requisitos de la API de GelatoConnect.

Ejemplo básico de asignación de plantillas

Veamos un ejemplo sencillo que transforma un pedido del formato de tu sistema al formato de GelatoConnect:

Los datos de tus pedidos en el sistema:

{"order_id": "ORD-12345","customer": {"name": "John Doe","email": "[email protected]"},"entrega": {"street": "Calle Principal 123","city": "Nueva York","zip": "10001","country": "EE. UU."},"productos": [{"sku": "POSTER-A4-MATTE","qty": 2,"image_url": "https://example.com/images/poster1.jpg"}]}

Mapeador de plantillas:

{"orderReferenceId": "####{{ order_id }}","orderType": "pedido","currency": "USD","shippingAddress": {"firstName": "####{{ customer.name.split(' ')[0] }}","lastName": "####{{ customer.name.split(' ')[1] }}","addressLine1": "####{{ delivery.street }}","city": "####{{ delivery.city }}","postCode": "####{{ delivery.zip }}","country": "####{{ delivery.country }}","email": "####{{ customer.email }}","teléfono": "+1234567890"},"items": [{% for product in products %}{"itemReferenceId": "####{{ order_id }}-####{{ loop.index }}","productUid": "####{{ lookups({'sku': product.sku}, strict=False, default='') }}","quantity": ####{{ product.qty }},"archivos": [{"type": "default","url": "####{{ product.image_url }}"}]}{% if not loop.last %},{% endif %}{% endfor %}]}

Pedido compatible con GelatoConnect resultante:

{"orderReferenceId": "ORD-12345","orderType": "pedido","currency": "USD","shippingAddress": {"firstName": "John","lastName": "Doe","addressLine1": "Calle Principal 123","city": "Nueva York","postCode": "10001","country": "US","email": "[email protected]","teléfono": "+1234567890"},"items": [{"itemReferenceId": "ORD-12345-1","productUid": "flat_product_pf_a4_pt_200-gsm-no estucado_cl_4-0_ct_none_prt_none_sft_none_set_none_hor","cantidad": 2,"archivos": [{"type": "default","url": "https://example.com/images/poster1.jpg"}]}]}

Funciones clave del asignador de plantillas

Interpolación de variables

Utiliza llaves dobles para insertar valores de los datos de entrada:

jinja"orderReferenceId": "####{{ order_id }}"

Filtros

Aplica transformaciones a los valores usando filtros (indicados por el símbolo de barra vertical):

jinja"firstName": "####{{ customer.name | title }}"

Los filtros más habituales son:

upper: Convertir a mayúsculas
lower: Convertir a minúsculas
title: Pon la primera letra de cada palabra en mayúscula
Acabado de bordes: Elimina los espacios en blanco al principio y al final
default: Proporciona un valor predeterminado si la variable no está definida
js: Asegúrate de que el valor esté bien formateado para JSON

Estructuras de control

Utiliza la lógica para mostrar contenido solo cuando lo necesites o para recorrer listas:

{% for product in products %}// Procesa cada producto{% endfor %}{% if customer.type == "business" %}// Incluye campos específicos del negocio{% else %}// Incluye los campos individuales del cliente{% endif %}

Búsquedas

Utiliza la función lookups() para relacionar valores entre sistemas, por ejemplo, para convertir los SKUs de tus productos en los UIDs de productos de GelatoConnect:

jinja"productUid": "####{{ lookups({'sku': product.sku}, strict=False, default='') }}"

La función de búsqueda requiere configurar tablas de búsqueda en GelatoConnect, que relacionan los valores de tu sistema con los valores de GelatoConnect.

Crear y probar mapeadores de plantillas

GelatoConnect te ofrece una interfaz fácil de usar para crear y probar mapeadores de plantillas:

Crea una plantilla: Ve a la sección de plantillas y crea una nueva plantilla.
Elige el tipo de plantilla: Selecciona el tipo de plantilla que mejor se adapte a lo que necesitas (por ejemplo, solicitud de envío de pedido, notificación de pedido recibido).
Define la plantilla: Escribe tu plantilla Jinja2 en el editor.
Prueba con datos de ejemplo: Añade datos de muestra y visualiza la plantilla para ver el resultado.
Prueba y mejora: Ajusta tu plantilla según lo que veas en el resultado final.
Guardar y activar: Cuando tu plantilla funcione correctamente, guárdala para usarla en tu integración.

Usos habituales de los mapeadores de plantillas

1. Mapeo de envío de pedidos

Convierte los pedidos del formato de tu sistema al formato de la API de GelatoConnect.

2. Notificaciones de actualización de estado

Crea plantillas para los distintos estados de pedido (recibido, enviado, entregado) y mantén a tus sistemas siempre al tanto.

3. Webhooks personalizados

Da forma a los datos para enviarlos a sistemas de terceros cuando ocurren eventos concretos.

4. Normalización de datos

Estandariza los datos de varias fuentes antes de procesarlos.

Buenas prácticas para quienes crean plantillas personalizadas

Empieza por lo sencillo: Comienza con una plantilla básica y ve añadiendo detalles poco a poco.
Usa comentarios: Añade comentarios para explicar transformaciones complejas.
```
jinja{# Esto extrae el nombre y los apellidos del nombre completo #}
```
Gestiona los datos que faltan: Asegúrate siempre de poner valores por defecto o comprobar los campos opcionales.
```
jinja"additionalInfo": "####{{ customer.notes | default('') }}"
```
Pon a prueba los casos límite: Asegúrate de que tus plantillas puedan con formatos o valores inesperados.
Utiliza búsquedas para asignaciones complejas: En lugar de poner las asignaciones directamente en tu plantilla, aprovecha la funcionalidad de búsquedas.
Mantén las plantillas enfocadas: Crea plantillas diferentes para cada objetivo en lugar de una sola plantilla complicada.
Valida el resultado: Comprueba siempre que la salida de tu plantilla cumpla con los requisitos de la API de GelatoConnect.

Técnicas avanzadas para mapear plantillas

A medida que te familiarices con los mapeadores de plantillas, podrás aprovechar funciones avanzadas:

Macros

Define bloques reutilizables de código de plantilla:

{% macro format_address(address) %}{"addressLine1": "####{{ address.street }}","city": "####{{ address.city }}","postCode": "####{{ address.zip }}","country": "####{{ address.country }}"}{% endmacro %}// Luego úsalo así:"shippingAddress": ####{{ format_address(delivery) }}

Establecer declaraciones

Crea variables dentro de tu plantilla:

{% set full_name = customer.firstName + ' ' + customer.lastName %}"recipientName": "####{{ full_name }}"

Filtros y funciones personalizadas

GelatoConnect admite varios filtros y funciones personalizados además de los estándar de Jinja2:

lookups(): Para conectar diferentes sistemas de valores
js: Para un escape correcto de JSON
Varias funciones para dar formato a fechas

¿Deseas saber más?

Ahora que ya tienes claro lo esencial sobre los Template Mappers en GelatoConnect, estás listo para:

Más información sobre cómo crear plantillas para la recepción de pedidos
Descubre ejemplos de plantillas Jinja2
Configura los disparadores de postback que utilizan tus plantillas

[Recepción de pedidos - GCW] Introducción a los mapeadores de plantillas