Este guia traz exemplos práticos de mapeadores de templates Jinja2 no GelatoConnect para ajudar você a implementar cenários comuns de transformação de dados. Seja mapeando dados de pedidos, transformando notificações ou implementando Lookups, estes exemplos vão oferecer uma base sólida para começar.
Exemplo básico de envio de pedido
Este exemplo mostra como enviar um pedido padrão:
Dados 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\": { "destinatário": { "first_name": "John", \"last_name\": \"Smith\" }, "endereço": { \"line1\": \"123 Main St\", "line2": "Apto 4B", "city": "Nova York", "postal_code": "10001", "country": "EUA", "state": "NY" }, "phone": "212-555-1234" } }}
Mapeador de Modelos:
{ "orderReferenceId": "##{{ order.id }}", \"orderType\": \"order\", "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 }}" }, "itens": [ {% for item in order.items %} { "itemReferenceId": "##{{ item.id }}", "productUid": "##{{ lookups({'product_code': item.product_code}, strict=False, default='') }}", "quantity": ##{{ item.quantity }}, "arquivos": [ { "type": "padrão", "url": "##{{ item.file_url }}" } ] }{% if not loop.last %},{% endif %} {% endfor %} ]}
Trabalhando com vários arquivos de produtos
Este exemplo trata de produtos com múltiplos arquivos (frente e verso):
Dados 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 }}, "arquivos": [ { "type": "padrão", "url": "##{{ item.file_url }}" } ] }{% if not loop.last %},{% endif %} {% endfor %} ]}
Mapeador de Modelos:
{ "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 }}\" }, "itens": [ {% for product in products %} { "itemReferenceId": "##{{ product.productId }}", "productUid": "##{{ lookups({'sku': product.sku}, strict=False, default='') }}", "quantity": ##{{ product.qty }}, "arquivos": [ { \"type\": \"front\", \"url\": \"##{{ product.files.front }}\"" }, { "type": "voltar", "url": "##{{ product.files.back }}" } ] }{% if not loop.last %},{% endif %} {% endfor %} ]}
Exemplo de Lógica Condicional
Este exemplo mostra como usar lógica condicional para lidar com diferentes tipos de produtos:
Dados de entrada:
{ "orderId": "ORD-5555", \"customer\": { "name": "Alice Johnson", "email": "[email protected]", \"telefone\": \"555-123-4567\" }, "shipping": { "address": "789 Rua Pine", \"apartamento\": \"\", \"city\": \"Boston\", \"state\": \"MA\", \"zipCode\": \"02108\", "country": "EUA" }, \"items\": [ { "id": "ITEM-A", "type": "pôster", "sku": "POSTER-LG", "quantity": 1, "image": "https://example.com/files/poster.jpg" }, { "id": "ITEM-B", "type": "cartão", "sku": "CARD-SM", "quantity": 100, "frontImage": "https://example.com/files/card-front.jpg", "backImage": "https://example.com/files/card-back.jpg" } ]}
Mapeador de modelos:
{ "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 }}\" }, "itens": [ {% for item in items %} { "itemReferenceId": "##{{ item.id }}", "productUid": "##{{ lookups({'sku': item.sku}, strict=False, default='') }}", "quantity": ##{{ item.quantity }}, \"files\": [ {% if item.type == 'poster' %} { \"type\": \"default\", "url": "##{{ item.image }}" } {% elif item.type == 'card' %} { "type": "frente", "url": "##{{ item.frontImage }}" }, { \"type\": \"back\", "url": "##{{ item.backImage }}" } {% endif %} ] }{% if not loop.last %},{% endif %} {% endfor %} ]}
Exemplo de postback de atualização de status do pedido
Este exemplo mostra como formatar uma notificação de postback para mudanças no status do pedido:
Dados de entrada:
{ "orderId": "a6a1f9ce-2bdd-4a9e-9f8d-0009df0e24d9", "orderReferenceId": "J123X456", "customerReferenceId": "CUST-789", "fulfillmentStatus": "enviado", "created": "2023-04-12T10:26:52+00:00", "itens": [ { "itemReferenceId": "123", "fulfillmentStatus": "enviado", "atendimentosDePedidos": [ { "trackingCode": "TRK123456789", \"trackingUrl\": \"https://example.com/tracking?code=TRK123456789\", "carrierName": "FedEx", \"carrierUid\": \"fed_ex_ground\", "fulfillmentCountry": "EUA", "fulfillmentStateProvince": "NY" } ] } ]}
Mapeador de Modelos:
{ "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 %} ] }}
Exemplo de pesquisas avançadas
Este exemplo demonstra consultas complexas para mapeamento de produtos e seleção de transportadoras:
Dados de entrada:
{ "reference": "PEDIDO-8888", \"recipient\": { \"fullName\": \"Robert Brown\", "emailAddress": "[email protected]", \"phoneNumber\": \"888-555-1212\", "shippingInformation": { \"streetAddress\": \"321 Oak Ave\", "city": "Chicago", "state": "IL", "postalCode": "60601", "countryCode": "US" } }, "orderItems": [ { "lineItemId": "LI-001", \"productReference\": { \"code\": \"BK-HCVR-A5\", \"type\": \"hardcover_book\", "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": "padrão", "region": "américa do norte"}
Mapeador de Modelos:
{% 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\": \"book_product_pf_a5_pt_premium_cl_4-4_hcvr\", "BK-HCVR-A5-standard": "livro_produto_pf_a5_pt_padrão_cl_4-4_hcvr", \"BK-SCVR-A5-premium\": \"book_product_pf_a5_pt_premium_cl_4-4_scvr\", "BK-SCVR-A5-standard": "livro_produto_pf_a5_pt_padrão_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 }}" }, "itens": [ {% 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 }}, "arquivos": [ { "type": "capa", "url": "##{{ item.assetUrls.coverFile }}" }, { "type": "interno", "url": "##{{ item.assetUrls.interiorFile }}" } ] }{% if not loop.last %},{% endif %} {% endfor %} ]}
Trabalhando com Datas e Formatação
Este exemplo mostra como formatar datas e manipular textos:
Dados de Entrada:
{ "orderNum": "INV-20230412-001", \"datePlaced\": \"2023-04-12T14:30:00Z\", \"clientDetails\": { "id": "CLIENT001", "contactInfo": { "name": "SARAH WILLIAMS", \"email\": \"[email protected]\", \"telephone\": \"1.212.555.7890\" }, "deliveryAddress": { \"line1\": \"555 Broadway\", "line2": "10º andar", \"city\": \"Nova York\", "region": "Nova York", "code": "10012", "country": "Estados Unidos" } }, "lineItems": [ { "refCode": "LI-001-A", \"productIdentifier\": \"BROCHURE-A4-GLOSSY\", "amount": 250, \"artwork\": \"https://example.com/files/brochure.pdf\" } ]}
Mapeador de Modelos:
{% set country_codes = { \"Estados Unidos\": \"US\", "Reino Unido": "GB", \"Canadá\": \"CA\", "Austrália": "AU", \"Alemanha\": \"DE\", "França": "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": "dataDoPedido", "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 }}, "arquivos": [ { "type": "padrão", "url": "##{{ item.arte }}" } ] }{% if not loop.last %},{% endif %} {% endfor %} ]}
Tratamento de erros e valores padrão
Este exemplo mostra como lidar com erros de forma eficiente, usando valores padrão:
Dados de entrada:
{ "id": "ORD-91011", "comprador": { "name": "Michael Johnson" // Campo de e-mail ausente }, "shipping": { \"name\": \"Michael Johnson\", \"address\": \"111 River Rd\", // Cidade ausente "province": "Ontário", "postal": "M5V 2H1", \"country\": \"CA\" }, "itens": [ { \"id\": \"ITEM-001\", "sku": "CALENDAR-WALL", \"quantidade\": 1, "assets": { "main": "https://example.com/files/calendar.pdf" } }, { // Item incompleto "id": "ITEM-002" } ]}
Mapeador de modelos:
{ "orderReferenceId": "##{{ id }}", \"orderType\": \"order\", "currency": "CAD", \"shippingAddress\": { {% set recipient = shipping.name | default('') %} {% set name_parts = recipient.split(' ') if recipient else ['', ''] %} "firstName": "##{{ name_parts[0] | default('Desconhecido') }}", "lastName": "##{{ name_parts[1:] | join(' ') | default('Cliente') }}", "addressLine1": "##{{ shipping.address | default('Endereço ausente') }}", "city": "##{{ shipping.city | default('Toronto') }}", "state": "##{{ shipping.province | default('ON') }}", "postCode": "##{{ shipping.postal | default('') }}", "country": "##{{ shipping.country | default('BR') }}", "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 }}, \"files\": [ { "type": "padrão", \"url\": \"##{{ item.assets.main | default('') }}\" } ] }{% if not loop.last %},{% endif %} {% endif %} {% endfor %} ]}
Combinando várias fontes
Este exemplo reúne dados de várias fontes:
Dados de entrada:
{ "order": { "id": "PO-12345", "type": "padrão" }, "customer": { "id": "CUST-789", "segment": "negócio" }, "destinatário": { "first": "David", "last": "Miller", "email": "[email protected]", "phone": "303-555-1212", "entrega": { "address": "987 State St", "suite": "Sala 500", "city": "Denver", "state": "CO", "zip": "80202", "country": "EUA" } }, "produtos": [ { "id": "PROD-A1", \"code\": \"FLYER-A4-FULL\", \"count\": 500, "arte": "https://example.com/files/flyer.pdf" } ], "shipping": { "method": "terrestre", "expectedDays": 3 }, "promocional": { "campaign": "SPRING2023", \"source\": \"email\" }}
Mapeador de Modelos:
{% set shipping_method_map = { "overnight": "fed_ex_priority_overnight", "express": "fed_ex_2_day", "ground": "fed_ex_ground"} %}{ "orderReferenceId": "##{{ order.id }}", "orderType": "##{{ 'rascunho' if order.type == 'preorder' else 'pedido' }}", "currency": "USD", "customerReferenceId": "##{{ customer.id }}", "shipmentMethodUid": "##{{ shipping_method_map.get(shipping.method, 'normal') }}", "metadata": [ { "key": "campanha", "value": "##{{ promotional.campaign }}" }, { "key": "fonte", "value": "##{{ promotional.source }}" }, { "key": "segment", "value": "##{{ customer.segment }}" }, { "key": "previsaoDeEntrega", "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='') }}\", \"quantity\": ##{{ product.count }}, \"files\": [ { \"type\": \"default\", "url": "##{{ product.artwork }}" } ] }{% if not loop.last %},{% endif %} {% endfor %} ]}
Trabalhando com Estruturas Aninhadas Complexas
Este exemplo mostra como lidar com estruturas de dados profundamente aninhadas:
Dados de entrada:
{ "data": { "transaction": { "identifiers": { \"internalRef\": \"TX-44556\", \"customerRef\": \"CUST-ABC123\" }, \"metadata\": { \"createdAt\": \"2023-04-12T09:15:00Z\", "source": "web", \"etiquetas\": [\"prioridade\", \"corporativo\"] } }, "partes": { "remetente": { "organization": "Acme Corp", "contact": { \"person\": { "givenName": "Thomas", \"familyName\": \"Anderson\" }, "details": { \"email\": { \"address\": \"[email protected]\" }, "phone": { "number": "415-555-9876", \"extension\": \"123\" } } } }, \"recipient\": { "person": { "givenName": "Sarah", "familyName": "Connor" }, "contactDetails": { \"emailAddress\": \"[email protected]\", \"phoneNumber\": \"213-555-4321\" }, \"location\": { \"address\": { "street": "1984 Tech Blvd", "unit": "#42", "locality": "Los Angeles", "region": "Califórnia", \"postalCode\": \"90210\", \"country\": \"EUA\" } } } }, \"contents\": { "items": [ { \"descriptor\": { \"id\": \"ITM-X789\", "type": "brochura", \"specifications\": { "format": "A4", \"paperType\": \"Brilhante\", \"colorProfile\": \"CMYK\" } }, \"quantity\": { "value": 1000, \"unit\": \"pcs\" }, \"digitalAssets\": { \"printable\": { \"fileLocation\": \"https://example.com/files/brochure-complex.pdf\" } } } ] } }}
Mapeador de modelos:
{% set country_map = { "EUA": "US", "Estados Unidos": "US", \"Estados Unidos da América\": \"US\", "Reino Unido": "GB", \"Reino Unido\": \"GB\", "Inglaterra": "GB"} %}{ "orderReferenceId": "##{{ data.transaction.identifiers.internalRef }}", \"orderType\": \"order\", "currency": "USD", "customerReferenceId": "##{{ data.transaction.identifiers.customerRef }}", "metadata": [ { \"key\": \"createdAt\", "value": "##{{ data.transaction.metadata.createdAt }}" }, { \"key\": \"source\", "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 }}" }, "itens": [ {% for item in data.contents.items %} { "itemReferenceId": "##{{ item.descriptor.id }}", \"productUid\": \"##{{ lookups({" 'type': item.descriptor.type, 'format': item.descriptor.specifications.format, 'paper': 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 %} ]}
Dicas para mapeadores de modelos eficazes
Ao trabalhar com Mapeadores de Modelo Jinja2 no GelatoConnect, considere estas dicas práticas:
Use técnicas de depuração:
Adicionar campos temporários para mostrar valores intermediários
Use o filtro {% raw %}##{{ variable | tojson }}{% endraw %} para depurar objetos complexos
Combine as instruções de conjunto com condicionais:
jinja{% set shipping_type = 'expresso' if order.priority == 'alta' else 'padrão' %}Lide com dados ausentes ou aninhados:
jinja##{{ data.get('nested', {}).get('deeply', {}).get('property', 'default_value') }}Crie dicionários de mapeamento para associações comuns:
{% set status_map = {'NEW': 'received', 'SHIPPED': 'shipped', 'DELIVERED': 'delivered'} %}"status": "##{{ status_map.get(input_status, 'desconhecido') }}"Coloque lógicas reutilizáveis em macros:
{% macro format_phone(phone) %}##{{ phone | replace(' ', '') | replace('.', '-') }}{% endmacro %}Use filtros para transformar dados:
borda: Remover espaços em brancosubstituir: Trocar textoupper/lower/title: Alterar caixadefault: Forneça valores de reservatojson: Formatar como uma string JSON
Considere o desempenho para grandes conjuntos de dados:
Calcule os valores antes dos loops
Use instruções de definição fora dos loops
Mantenha os modelos focados e específicos
Próximos passos
Agora que você viu esses exemplos práticos, pode:
Adapte estes modelos às suas necessidades específicas de integração
Crie transformações mais complexas combinando técnicas
Teste seus modelos com dados reais para garantir que tudo funcione perfeitamente
Configure gatilhos de postback usando estes modelos
Implemente pesquisas para mapear valores de forma eficiente