Ir al contenido principal

[Recepción de pedidos - GCW] Ejemplos de mapeo de plantillas

T
Escrito por Toby Dawson
Actualizado hace más de 3 semanas

Esta guía te ofrece ejemplos prácticos de mapeadores de plantillas Jinja2 en GelatoConnect para que puedas poner en marcha transformaciones de datos habituales. Ya sea que estés organizando datos de pedidos, adaptando notificaciones o configurando búsquedas, estos ejemplos te servirán como punto de partida sólido.

Ejemplo sencillo de envío de pedido

Este ejemplo muestra cómo gestionar un pedido estándar:

Datos de entrada:

{ "order": { "id": "12345", "customer_email": "[email protected]", "items": [ { "id": "item-1", "product_code": "POSTER-A3", "quantity": 2, "file_url": "https://example.com/files/poster.pdf" } ], "shipping": { "recipient": { "first_name": "John", "last_name": "Smith" }, "address": { "line1": "Calle Principal 123", "line2": "Apto. 4B", "city": "Nueva York", "postal_code": "10001", "country": "EE. UU.", "state": "NY" }, "phone": "212-555-1234" } }}

Mapeador de plantillas:

{ "orderReferenceId": "####{{ order.id }}", "orderType": "pedido", "currency": "USD", "shippingAddress": { "firstName": "####{{ order.shipping.recipient.first_name }}", "lastName": "####{{ order.shipping.recipient.last_name }}", "addressLine1": "####{{ order.shipping.address.line1 }}", "addressLine2": "####{{ order.shipping.address.line2 }}", "city": "####{{ order.shipping.address.city }}", "postCode": "####{{ order.shipping.address.postal_code }}", "country": "####{{ order.shipping.address.country }}", "state": "####{{ order.shipping.address.state }}", "email": "####{{ order.customer_email }}", "phone": "####{{ order.shipping.phone }}" }, "items": [ {% for item in order.items %} { "itemReferenceId": "####{{ item.id }}", "productUid": "####{{ lookups({'product_code': item.product_code}, strict=False, default='') }}", "quantity": ####{{ item.quantity }}, "files": [ { "type": "predeterminado", "url": "####{{ item.file_url }}" } ] }{% if not loop.last %},{% endif %} {% endfor %} ]}

Trabajar con varios archivos de producto

Este ejemplo muestra cómo gestionar productos con varios archivos (anverso y reverso):

Datos de entrada:

{ "orderReferenceId": "####{{ order.id }}", "orderType": "pedido", "currency": "USD", "shippingAddress": { "firstName": "####{{ order.shipping.recipient.first_name }}", "lastName": "####{{ order.shipping.recipient.last_name }}", "addressLine1": "####{{ order.shipping.address.line1 }}", "addressLine2": "####{{ order.shipping.address.line2 }}", "city": "####{{ order.shipping.address.city }}", "postCode": "####{{ order.shipping.address.postal_code }}", "country": "####{{ order.shipping.address.country }}", "state": "####{{ order.shipping.address.state }}", "email": "####{{ order.customer_email }}", "phone": "####{{ order.shipping.phone }}" }, "items": [ {% for item in order.items %} { "itemReferenceId": "####{{ item.id }}", "productUid": "####{{ lookups({'product_code': item.product_code}, strict=False, default='') }}", "quantity": ####{{ item.quantity }}, "archivos": [ { "type": "predeterminado", "url": "####{{ item.file_url }}" } ] }{% if not loop.last %},{% endif %} {% endfor %} ]}

Mapeador de plantillas:

{ "orderReferenceId": "####{{ orderNumber }}", "orderType": "pedido", "currency": "USD", "shippingAddress": { {% set nameParts = deliveryDetails.contactName.split(' ') %} "firstName": "####{{ nameParts[0] }}", "lastName": "####{{ nameParts[1:] | join(' ') }}", "addressLine1": "####{{ deliveryDetails.address.street }}", "city": "####{{ deliveryDetails.address.city }}", "state": "####{{ deliveryDetails.address.state }}", "postCode": "####{{ deliveryDetails.address.zip }}", "country": "####{{ deliveryDetails.address.country }}", "email": "####{{ deliveryDetails.email }}", "phone": "####{{ deliveryDetails.phone }}" }, "items": [ {% for product in products %} { "itemReferenceId": "####{{ product.productId }}", "productUid": "####{{ lookups({'sku': product.sku}, strict=False, default='') }}", "quantity": ####{{ product.qty }}, "files": [ { "type": "frontal", "url": "####{{ product.files.front }}" }, { "type": "atrás", "url": "####{{ product.files.back }}" } ] }{% if not loop.last %},{% endif %} {% endfor %} ]}

Ejemplo de lógica condicional

Este ejemplo muestra cómo usar lógica condicional para gestionar distintos tipos de productos:

Datos de entrada:

{ "orderId": "ORD-5555", "customer": { "name": "Alice Johnson", "email": "[email protected]", "phone": "555-123-4567" }, "shipping": { "address": "Calle Pino 789", "apartment": "apartamento", "city": "Boston", "state": "MA", "zipCode": "02108", "country": "US" }, "items": [ { "id": "ITEM-A", "type": "póster", "sku": "POSTER-LG", "quantity": 1, "image": "https://example.com/files/poster.jpg" }, { "id": "ITEM-B", "type": "tarjeta", "sku": "CARD-SM", "quantity": 100, "frontImage": "https://example.com/files/card-front.jpg", "backImage": "https://example.com/files/card-back.jpg" } ]}

Mapeador de plantillas:

{ "orderReferenceId": "####{{ orderId }}", "orderType": "pedido", "currency": "USD", "shippingAddress": { {% set nameParts = customer.name.split(' ') %} "firstName": "####{{ nameParts[0] }}", "lastName": "####{{ nameParts[1:] | join(' ') }}", "addressLine1": "####{{ shipping.address }}", {% if shipping.apartment %} "addressLine2": "####{{ shipping.apartment }}", {% endif %} "city": "####{{ shipping.city }}", "state": "####{{ shipping.state }}", "postCode": "####{{ shipping.zipCode }}", "country": "####{{ shipping.country }}", "email": "####{{ customer.email }}", "phone": "####{{ customer.phone }}" }, "items": [ {% for item in items %} { "itemReferenceId": "####{{ item.id }}", "productUid": "####{{ lookups({'sku': item.sku}, strict=False, default='') }}", "quantity": ####{{ item.quantity }}, "files": [ {% if item.type == 'poster' %} { "type": "predeterminado", "url": "####{{ item.image }}" } {% elif item.type == 'card' %} { "type": "frontal", "url": "####{{ item.frontImage }}" }, { "type": "atrás", "url": "####{{ item.backImage }}" } {% endif %} ] }{% if not loop.last %},{% endif %} {% endfor %} ]}

Ejemplo de actualización del estado del pedido

Este ejemplo muestra cómo se envía una notificación cuando cambia el estado de un pedido:

Datos de entrada:

{ "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9", "orderReferenceId": "J123X456", "customerReferenceId": "CUST-789", "fulfillmentStatus": "enviado", "created": "12/04/2023 10:26:52", "items": [ { "itemReferenceId": "123", "fulfillmentStatus": "enviado", "fulfillments": [ { "trackingCode": "TRK123456789", "trackingUrl": "https://example.com/tracking?code=TRK123456789", "carrierName": "FedEx", "carrierUid": "fed_ex_ground", "fulfillmentCountry": "US", "fulfillmentStateProvince": "NY" } ] } ]}

Mapeador de plantillas:

{ "event": "PEDIDO_ENVIADO", "timestamp": "####{{ created }}", "order": { "id": "####{{ orderReferenceId }}", "customer_id": "####{{ customerReferenceId }}", "status": "####{{ fulfillmentStatus | upper }}", "shipped_items": [ {% for item in items %} {% if item.fulfillmentStatus == 'shipped' %} { "item_id": "####{{ item.itemReferenceId }}", "tracking": { {% for fulfillment in item.fulfillments %} "carrier": "####{{ fulfillment.carrierName }}", "tracking_number": "####{{ fulfillment.trackingCode }}", "tracking_url": "####{{ fulfillment.trackingUrl }}", "shipped_from": { "country": "####{{ fulfillment.fulfillmentCountry }}", "state": "####{{ fulfillment.fulfillmentStateProvince }}" } {% endfor %} } }{% if not loop.last %},{% endif %} {% endif %} {% endfor %} ] }}

Ejemplo de búsquedas avanzadas

Este ejemplo muestra cómo buscar y elegir productos y transportistas de forma avanzada:

Datos de entrada:

{ "reference": "PEDIDO-8888", "recipient": { "fullName": "Robert Brown", "emailAddress": "[email protected]", "phoneNumber": "888-555-1212", "shippingInformation": { "streetAddress": "Av. Roble 321", "city": "Chicago", "state": "IL", "postalCode": "60601", "countryCode": "US" } }, "orderItems": [ { "lineItemId": "LI-001", "productReference": { "code": "BK-HCVR-A5", "type": "libro de tapa dura", "size": "A5" }, "quantity": 1, "assetUrls": { "coverFile": "https://example.com/files/book-cover.pdf", "interiorFile": "https://example.com/files/book-interior.pdf" }, "additionalAttributes": { "pageCount": 120, "paperType": "premium" } } ], "shippingPreference": "estándar", "region": "norteamérica"}

Mapeador de plantillas:

{% set shipping_lookup = { "express_north_america": "fed_ex_2_day", "express_europe": "dhl_express_eu", "standard_north_america": "UPS Ground", "standard_europe": "dhl_parcel_eu"} %}{% set product_lookup = {} %}{% set product_lookup = product_lookup.update({ "BK-HCVR-A5-premium": "producto_preparación_pf_a5_pt_premium_cl_4-4_hcvr", "BK-HCVR-A5-standard": "libro_producto_pf_a5_pt_estándar_cl_4-4_hcvr", "BK-SCVR-A5-premium": "libro_producto_pf_a5_pt_premium_cl_4-4_scvr", "BK-SCVR-A5-standard": "libro_producto_pf_a5_pt_estándar_cl_4-4_scvr"}) %}{ "orderReferenceId": "####{{ reference }}", "orderType": "pedido", "currency": "USD", {% set shipping_key = shippingPreference + '_' + region %} "shipmentMethodUid": "####{{ shipping_lookup.get(shipping_key, 'normal') }}", "shippingAddress": { {% set name_parts = recipient.fullName.split(' ') %} "firstName": "####{{ name_parts[0] }}", "lastName": "####{{ name_parts[1:] | join(' ') }}", "addressLine1": "####{{ recipient.shippingInformation.streetAddress }}", "city": "####{{ recipient.shippingInformation.city }}", "state": "####{{ recipient.shippingInformation.state }}", "postCode": "####{{ recipient.shippingInformation.postalCode }}", "country": "####{{ recipient.shippingInformation.countryCode }}", "email": "####{{ recipient.emailAddress }}", "phone": "####{{ recipient.phoneNumber }}" }, "items": [ {% for item in orderItems %} { "itemReferenceId": "####{{ item.lineItemId }}", {% set product_key = item.productReference.code + '-' + item.additionalAttributes.paperType %} "productUid": "####{{ product_lookup.get(product_key, lookups({'code': item.productReference.code, 'paper': item.additionalAttributes.paperType}, strict=False, default='')) }}", "quantity": ####{{ item.quantity }}, "pageCount": ####{{ item.additionalAttributes.pageCount }}, "archivos": [ { "type": "portada", "url": "####{{ item.assetUrls.coverFile }}" }, { "type": "interior", "url": "####{{ item.assetUrls.interiorFile }}" } ] }{% if not loop.last %},{% endif %} {% endfor %} ]}

Trabajar con fechas y formatos

Este ejemplo muestra cómo dar formato a las fechas y jugar con los textos:

Datos de entrada:

{ "orderNum": "INV-20230412-001", "datePlaced": "12/04/2023 16:30", "clientDetails": { "id": "CLIENT001", "contactInfo": { "name": "SARAH WILLIAMS", "email": "[email protected]", "telephone": "1.212.555.7890" }, "deliveryAddress": { "line1": "555 Broadway", "line2": "Planta 10", "city": "Nueva York", "region": "Nueva York", "code": "10012", "country": "Estados Unidos" } }, "lineItems": [ { "refCode": "LI-001-A", "productIdentifier": "FOLLETO-A4-BRILLANTE", "amount": 250, "creación artística": "https://example.com/files/folleto.pdf" } ]}

Mapeador de plantillas:

{% set country_codes = { "Estados Unidos": "US", "Reino Unido": "GB", "Canadá": "CA", "Australia": "AU", "Alemania": "DE", "Francia": "FR"} %}{% set date_parts = datePlaced.split('T')[0].split('-') %}{% set formatted_date = date_parts[2] + '/' + date_parts[1] + '/' + date_parts[0] %}{ "orderReferenceId": "####{{ orderNum }}", "orderType": "pedido", "currency": "USD", "metadata": [ { "key": "clientId", "value": "####{{ clientDetails.id }}" }, { "key": "orderDate", "value": "####{{ formatted_date }}" } ], "shippingAddress": { {% set name_parts = clientDetails.contactInfo.name | lower | title | split(' ') %} "firstName": "####{{ name_parts[0] }}", "lastName": "####{{ name_parts[1:] | join(' ') }}", "addressLine1": "####{{ clientDetails.deliveryAddress.line1 }}", "addressLine2": "####{{ clientDetails.deliveryAddress.line2 }}", "city": "####{{ clientDetails.deliveryAddress.city }}", "state": "####{{ clientDetails.deliveryAddress.region }}", "postCode": "####{{ clientDetails.deliveryAddress.code }}", "country": "####{{ country_codes.get(clientDetails.deliveryAddress.country, 'US') }}", "email": "####{{ clientDetails.contactInfo.email }}", "phone": "####{{ clientDetails.contactInfo.telephone | replace('.', '-') }}" }, "items": [ {% for item in lineItems %} { "itemReferenceId": "####{{ item.refCode }}", "productUid": "####{{ lookups({'product_id': item.productIdentifier}, strict=False, default='') }}", "quantity": ####{{ item.amount }}, "files": [ { "type": "predeterminado", "url": "####{{ item.creación artística }}" } ] }{% if not loop.last %},{% endif %} {% endfor %} ]}

Gestión de errores y valores predeterminados

Este ejemplo muestra cómo manejar errores de forma sólida usando valores predeterminados:

Datos de entrada:

{ "id": "ORD-91011", "buyer": { "name": "Michael Johnson" // Falta el campo de correo electrónico }, "shipping": { "name": "Michael Johnson", "address": "111 River Rd", // Falta la ciudad "province": "Ontario", "postal": "M5V 2H1", "country": "CA" }, "items": [ { "id": "ITEM-001", "sku": "CALENDAR-WALL", "quantity": 1, "assets": { "main": "https://example.com/files/calendario.pdf" } }, { // Elemento incompleto "id": "ITEM-002" } ]}

Mapeador de plantillas:

{ "orderReferenceId": "####{{ id }}", "orderType": "pedido", "currency": "CAD", "shippingAddress": { {% set recipient = shipping.name | default('') %} {% set name_parts = recipient.split(' ') if recipient else ['', ''] %} "firstName": "####{{ name_parts[0] | default('Desconocido') }}", "lastName": "####{{ name_parts[1:] | join(' ') | default('Cliente') }}", "addressLine1": "####{{ shipping.address | default('Dirección no disponible') }}", "city": "####{{ shipping.city | default('Toronto') }}", "state": "####{{ shipping.province | default('ON') }}", "postCode": "####{{ shipping.postal | default('') }}", "country": "####{{ shipping.country | default('CA') }}", "email": "####{{ buyer.email | default('[email protected]') }}", "phone": "####{{ buyer.phone | default('000-000-0000') }}" }, "items": [ {% for item in items %} {% if item.id and item.sku and item.quantity %} { "itemReferenceId": "####{{ item.id }}", "productUid": "####{{ lookups({'sku': item.sku}, strict=False, default='') }}", "quantity": ####{{ item.quantity }}, "archivos": [ { "type": "predeterminado", "url": "####{{ item.assets.main | default('') }}" } ] }{% if not loop.last %},{% endif %} {% endif %} {% endfor %} ]}

Combinando varias fuentes

Este ejemplo reúne datos de varias fuentes:

Datos de entrada:

{ "order": { "id": "PO-12345", "type": "estándar" }, "customer": { "id": "CUST-789", "segment": "negocio" }, "recipient": { "first": "David", "last": "Miller", "email": "[email protected]", "phone": "303-555-1212", "delivery": { "address": "987 State St", "suite": "Suite 500", "city": "Denver", "state": "CO", "zip": "80202", "country": "US" } }, "productos": [ { "id": "PROD-A1", "code": "FLYER-A4-FULL", "count": 500, "creación artística": "https://example.com/files/flyer.pdf" } ], "shipping": { "method": "terrestre", "expectedDays": 3 }, "promocional": { "campaign": "SPRING2023", "source": "correo electrónico" }}

Mapeador de plantillas:

{% set shipping_method_map = { "overnight": "fed_ex_priority_overnight", "express": "fed_ex_2_day", "ground": "fed_ex_ground"} %}{ "orderReferenceId": "####{{ order.id }}", "orderType": "####{{ 'borrador' if order.type == 'preorder' else 'pedido' }}", "currency": "USD", "customerReferenceId": "####{{ customer.id }}", "shipmentMethodUid": "####{{ shipping_method_map.get(shipping.method, 'normal') }}", "metadata": [ { "key": "campaña", "value": "####{{ promotional.campaign }}" }, { "key": "fuente", "value": "####{{ promotional.source }}" }, { "key": "segment", "value": "####{{ customer.segment }}" }, { "key": "fechaDeEntregaEstimada", "value": "####{{ shipping.expectedDays }}" } ], "shippingAddress": { "firstName": "####{{ recipient.first }}", "lastName": "####{{ recipient.last }}", "addressLine1": "####{{ recipient.delivery.address }}", "addressLine2": "####{{ recipient.delivery.suite }}", "city": "####{{ recipient.delivery.city }}", "state": "####{{ recipient.delivery.state }}", "postCode": "####{{ recipient.delivery.zip }}", "country": "####{{ recipient.delivery.country }}", "email": "####{{ recipient.email }}", "phone": "####{{ recipient.phone }}" }, "items": [ {% for product in products %} { "itemReferenceId": "####{{ product.id }}", "productUid": "####{{ lookups({'product_code': product.code}, strict=False, default='') }}", "cantidad": ####{{ product.count }}, "archivos": [ { "type": "default", "url": "####{{ product.artwork }}" } ] }{% if not loop.last %},{% endif %} {% endfor %} ]}

Cómo desenvolverse con estructuras anidadas complejas

Este ejemplo muestra cómo manejar estructuras de datos muy anidadas:

Datos de entrada:

{ "data": { "transaction": { "identifiers": { "internalRef": "TX-44556", "customerRef": "CUST-ABC123" }, "metadata": { "createdAt": "12/04/2023 11:15", "source": "web", "etiquetas": ["prioridad", "corporativo"] } }, "parties": { "sender": { "organization": "Acme Corp", "contacto": { "person": { "givenName": "Thomas", "familyName": "Anderson" }, "details": { "email": { "address": "[email protected]" }, "phone": { "number": "415-555-9876", "extensión": "123" } } } }, "recipient": { "person": { "givenName": "Sarah", "familyName": "Connor" }, "contactDetails": { "emailAddress": "[email protected]", "phoneNumber": "213-555-4321" }, "location": { "address": { "street": "Bulevar Tech 1984", "unit": "#42", "locality": "Los Ángeles", "region": "California", "postalCode": "90210", "country": "Estados Unidos" } } } }, "contents": { "items": [ { "descriptor": { "id": "ITM-X789", "type": "folleto", "especificaciones": { "format": "A4", "paperType": "Brillante", "colorProfile": "CMYK" } }, "quantity": { "value": 1000, "unit": "uds" }, "digitalAssets": { "printable": { "fileLocation": "https://example.com/files/folleto-complex.pdf" } } } ] } }}

Mapeador de plantillas:

{% set country_map = { "USA": "EE. UU.", "Estados Unidos": "US", "Estados Unidos de América": "US", "UK": "GB", "Reino Unido": "GB", "Inglaterra": "GB"} %}{ "orderReferenceId": "####{{ data.transaction.identifiers.internalRef }}", "orderType": "pedido", "currency": "USD", "customerReferenceId": "####{{ data.transaction.identifiers.customerRef }}", "metadata": [ { "key": "createdAt", "value": "####{{ data.transaction.metadata.createdAt }}" }, { "key": "fuente", "value": "####{{ data.transaction.metadata.source }}" }, {% for tag in data.transaction.metadata.etiquetas %} { "key": "etiqueta_####{{ loop.index }}", "value": "####{{ tag }}" }{% if not loop.last %},{% endif %} {% endfor %} ], "shippingAddress": { "firstName": "####{{ data.parties.recipient.person.givenName }}", "lastName": "####{{ data.parties.recipient.person.familyName }}", "addressLine1": "####{{ data.parties.recipient.location.address.street }}", "addressLine2": "####{{ data.parties.recipient.location.address.unit }}", "city": "####{{ data.parties.recipient.location.address.locality }}", "state": "####{{ data.parties.recipient.location.address.region }}", "postCode": "####{{ data.parties.recipient.location.address.postalCode }}", "country": "####{{ country_map.get(data.parties.recipient.location.address.country, data.parties.recipient.location.address.country) }}", "email": "####{{ data.parties.recipient.contactDetails.emailAddress }}", "phone": "####{{ data.parties.recipient.contactDetails.phoneNumber }}" }, "items": [ {% for item in data.contents.items %} { "itemReferenceId": "####{{ item.descriptor.id }}", "productUid": "####{{ lookups({ 'type': item.descriptor.type, 'formato': item.descriptor.specifications.format, 'papel': item.descriptor.specifications.paperType }, strict=False, default='') }}", "quantity": ####{{ item.quantity.value }}, "files": [ { "type": "default", "url": "####{{ item.digitalAssets.printable.fileLocation }}" } ] }{% if not loop.last %},{% endif %} {% endfor %} ]}

Consejos para sacar el máximo partido a los creadores de plantillas

Cuando trabajes con los mapeadores de plantillas Jinja2 en GelatoConnect, ten en cuenta estos consejos prácticos:

  1. Utiliza técnicas de depuración:

    • Añade campos temporales para mostrar valores intermedios

    • Usa el filtro {% raw %}####{{ variable | tojson }}{% endraw %} para analizar objetos complejos

  2. Combina las sentencias Set con condicionales:

    jinja{% set shipping_type = 'exprés' if order.priority == 'alta' else 'estándar' %}

  3. Gestiona datos que faltan o están anidados:

    jinja####{{ data.get('nested', {}).get('deeply', {}).get('property', 'default_value') }}

  4. Crea diccionarios de mapas para asociaciones habituales:

    {% set status_map = {'NEW': 'recibido', 'SHIPPED': 'enviado', 'DELIVERED': 'entregado'} %}"status": "####{{ status_map.get(input_status, 'desconocido') }}"

  5. Guarda la lógica reutilizable en macros:

    {% macro format_phone(phone) %}####{{ phone | replace(' ', '') | replace('.', '-') }}{% endmacro %}

  6. Usa filtros para transformar datos:

    • trim: Elimina los espacios en blanco

    • replace: Sustituir texto

    • upper/lower/title: Cambiar mayúsculas y minúsculas

    • default: Proporciona valores alternativos

    • tojson: Formatea como una cadena JSON

  7. Ten en cuenta el rendimiento con grandes volúmenes de datos:

    • Calcula los valores antes de los bucles

    • Utiliza las sentencias set fuera de los bucles

    • Mantén las plantillas claras y concretas

Próximos pasos

Ahora que has visto estos ejemplos prácticos, puedes:

  1. Adapta estas plantillas a las necesidades específicas de tu integración

  2. Crea transformaciones más complejas combinando diferentes técnicas

  3. Pon a prueba tus plantillas con datos reales para asegurarte de que todo funciona como esperas

  4. Configura los disparadores de postback usando estas plantillas

  5. Implementa búsquedas para asignar valores de forma eficiente

Artículos relacionados
[Recepción de pedidos - GCW] Documentación de la API de gestión de pedidos
[Recepción de pedidos - GCW] Trabajando con los puntos finales de la API de pedidos
[Recepción de pedidos - GCW] Usar productos del cliente vs. ProductUID en pedidos de la API
[Recepción de pedidos - GCW] Crear plantillas para la recepción de pedidos
[Recepción de pedidos - GCW] Introducción a los mapeadores de plantillas
¿Ha quedado contestada tu pregunta?