O que são mapeadores de modelos?

Os mapeadores de modelos no GelatoConnect são ferramentas poderosas que transformam dados entre o formato do seu sistema e o formato do GelatoConnect. Eles funcionam como tradutores, garantindo que as informações circulem sem obstáculos entre diferentes sistemas, independentemente de como cada um organiza seus dados.

Seja você enviando pedidos para o GelatoConnect ou recebendo atualizações sobre mudanças no status do pedido, os mapeadores de modelo tornam possível converter formatos de dados sem exigir alterações em seus sistemas existentes.

Por que usar mapeadores de modelos?

Os mapeadores de modelos resolvem vários desafios comuns de integração:

Estruturas de Dados Diferentes: O seu sistema e o GelatoConnect podem organizar as mesmas informações de maneiras diferentes.
Diferenças na nomenclatura dos campos: O seu sistema pode chamar o endereço de entrega de "delivery_address", enquanto o GelatoConnect usa "shippingAddress".
Conversões de formato: Você pode precisar converter formatos de dados, como alterar formatos de data ou transformar unidades de medida.
Mapeamento seletivo de campos: Você pode querer incluir apenas alguns campos específicos dos seus dados ao enviar para o GelatoConnect.
Lógica condicional: Pode ser necessário aplicar regras de mapeamento diferentes dependendo de certas condições, como o tipo de pedido ou o país de destino.

Como funcionam os Template Mappers

O GelatoConnect usa a linguagem de template Jinja2 para seus mapeadores de template. Essa linguagem poderosa e flexível permite que você:

Extrair valores: Obtenha dados do seu formato de entrada
Transformar dados: Aplique funções e lógica para modificar os dados
Gerar saída: Construa o resultado final no formato esperado pelo GelatoConnect

Um mapeador de modelo recebe uma entrada (seus dados) e produz uma saída (dados compatíveis com GelatoConnect) com base em um conjunto de regras de transformação que você define.

Componentes do Mapeador de Modelos

Um mapeador de modelo típico no GelatoConnect consiste nestes componentes:

1. Inserir dados

Estes são os dados de origem que você deseja transformar. Podem ser:

Dados de pedidos do seu sistema de e-commerce
Informações do cliente do seu CRM
Detalhes do produto do seu catálogo

2. Definição do Modelo

É aqui que você define como transformar os dados de entrada. Usando a sintaxe Jinja2, você especifica:

Quais campos extrair da entrada
Alguma transformação para aplicar
A estrutura da saída

3. Formato de saída

O resultado do processamento do modelo, normalmente em formato JSON, que atende aos requisitos da API do GelatoConnect.

Exemplo Básico do Mapeador de Modelos

Vamos analisar um exemplo simples que converte um pedido do formato do seu sistema para o formato do GelatoConnect:

Os dados de pedidos do seu sistema:

{"order_id": "ORD-12345",\"cliente\": {\"name\": \"John Doe\","email": "[email protected]"},"entrega": {"street": "Rua Principal, 123",\"cidade\": \"Nova York\",\"zip\": \"10001\","country": "US"},"produtos": [{"sku": "POSTER-A4-MATTE",\"qtd\": 2,"image_url": "https://example.com/images/poster1.jpg"}]}

Mapeador de Modelos:

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

Pedido compatível com o GelatoConnect gerado:

{\"orderReferenceId\": \"ORD-12345\","orderType": "order","currency": "USD","shippingAddress": {"firstName": "John","lastName": "Doe","addressLine1": "Rua Principal, 123","city": "Nova York","postCode": "10001","country": "US","email": "[email protected]","phone": "+1234567890"},\"items\": [{\"itemReferenceId\": \"ORD-12345-1\",\"productUid\": \"flat_product_pf_a4_pt_200-g/m² (Gramatura)-não revestido_cl_4-0_ct_none_prt_none_sft_none_set_none_hor\",\"quantidade\": 2,"arquivos": [{\"type\": \"default\","url": "https://example.com/images/poster1.jpg"}]}]}

Principais recursos do Template Mapper

Interpolação de variáveis

Use duas chaves duplas para inserir valores dos dados de entrada:

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

Filtros

Aplique transformações aos valores com filtros (indicados pelo símbolo de barra vertical):

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

Filtros comuns incluem:

upper: Converter para maiúsculas
lower: Converter para minúsculas
title: Coloque a primeira letra de cada palavra em maiúscula
borda: Remove espaços em branco do início e do fim
default: Forneça um valor padrão se a variável não estiver definida
js: Certifique-se de que o valor esteja formatado corretamente para JSON

Estruturas de controle

Use a lógica para incluir conteúdo condicionalmente ou iterar sobre matrizes:

{% for product in products %}// Processar cada produto{% endfor %}{% if customer.type == "business" %}// Incluir campos específicos do negócio{% else %}// Incluir campos individuais do cliente{% endif %}

Consultas

Use a função lookups() para mapear valores entre sistemas, como converter seus SKUs de produtos para UIDs de produtos do GelatoConnect:

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

A funcionalidade de pesquisa requer a configuração de tabelas de pesquisa no GelatoConnect, que mapeiam os valores do seu sistema para os valores do GelatoConnect.

Criando e testando mapeadores de modelos

O GelatoConnect oferece uma interface intuitiva para criar e testar mapeadores de modelos:

Criar um modelo: Navegue até a seção Modelos e crie um novo modelo.
Escolha o tipo de modelo: Selecione o tipo de modelo adequado (por exemplo, solicitação de envio de pedido, notificação de pedido recebido).
Defina o modelo: Escreva seu modelo Jinja2 no editor.
Teste com dados de amostra: Forneça dados de entrada de amostra e renderize o modelo para ver o resultado.
Depurar e refinar: Ajuste seu modelo conforme necessário com base na saída renderizada.
Salvar e ativar: Depois que seu modelo estiver funcionando corretamente, salve-o para uso em sua integração.

Principais usos para mapeadores de modelos

1. Mapeamento do envio de pedidos

Transforme os pedidos do formato do seu sistema para o formato da API do GelatoConnect.

2. Notificações de Atualização de Status

Crie modelos para diferentes eventos de status de pedido (recebido, enviado, entregue) e mantenha seus sistemas sempre informados.

3. Webhooks personalizados

Formate os dados para enviar a sistemas de terceiros quando eventos específicos acontecerem.

4. Normalização de Dados

Padronize dados de múltiplas fontes antes do processamento.

Melhores práticas para mapeadores de modelos

Comece pelo básico: Escolha um modelo simples e vá adicionando mais detalhes aos poucos.
Use Comentários: Adicione comentários para explicar transformações complexas.
```
jinja{# Isso extrai o primeiro e o último nome do nome completo #}
```
Lide com dados ausentes: Sempre forneça valores padrão ou verifique campos opcionais.
```
jinja\"additionalInfo\": \"##{{ customer.notes | default('') }}\"
```
Teste situações-limite: Certifique-se de que seus modelos lidam bem com formatos ou valores inesperados.
Use pesquisas para mapeamentos complexos: Em vez de inserir os mapeamentos manualmente no seu modelo, utilize a funcionalidade de pesquisas.
Mantenha os modelos focados: Crie modelos separados para diferentes finalidades em vez de um modelo complexo.
Validar saída: Sempre verifique se a saída do seu modelo atende aos requisitos da API do GelatoConnect.

Técnicas Avançadas do Mapeador de Modelos

À medida que você se torna mais familiarizado com os mapeadores de modelo, você pode utilizar recursos avançados:

Macros

Defina blocos reutilizáveis de código de modelo:

{% macro format_address(address) %}{\"addressLine1\": \"##{{ address.street }}\",\"cidade\": \"##{{ address.city }}\","postCode": "##{{ address.zip }}",\"country\": \"##{{ address.country }}\"}{% endmacro %}// Depois, use assim:"shippingAddress": ##{{ format_address(delivery) }}

Definir declarações

Crie variáveis dentro do seu modelo:

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

Filtros e funções personalizadas

O GelatoConnect oferece vários filtros e funções personalizados além dos padrões do Jinja2:

lookups(): Para mapeamento entre sistemas de valores
js: Para a formatação correta do JSON
Diversas funções de formatação de data

Quer saber mais?

Agora que você entende o básico dos Mapeadores de Modelo no GelatoConnect, você está pronto para:

Saiba mais sobre como criar modelos para recebimento de pedidos
Explore exemplos de modelos Jinja2
Configure os gatilhos de postback que utilizam seus modelos

[Entrada de Pedidos - GCW] Introdução aos Mapeadores de Modelos