Passar para o conteúdo principal

[Entrada de Pedidos - GCW] Criando Modelos para Entrada de Pedidos

T
Escrito por Toby Dawson
Atualizado há mais de 2 semanas

Os templates são componentes essenciais no GelatoConnect que gerenciam tanto os fluxos de dados de entrada quanto de saída. Eles transformam os dados recebidos dos clientes em formatos que o seu fluxo de trabalho pode processar e formatam os dados enviados pelo GelatoConnect para atender aos requisitos dos sistemas dos seus clientes. Este guia vai mostrar, passo a passo, como criar, testar e implementar templates para ambos os sentidos da troca de dados nos seus fluxos de gestão de pedidos.

Entendendo os modelos no GelatoConnect

Os modelos no GelatoConnect servem como plantas que definem como os dados devem ser estruturados, processados e apresentados. Eles gerenciam dois fluxos de dados críticos:

Modelos de dados recebidos

Estes modelos transformam os dados vindos dos sistemas dos seus clientes em formatos que o GelatoConnect consegue processar:

  • Solicitação de envio de pedido: Converte os dados do pedido do cliente para o formato interno do GelatoConnect

  • Cancelar solicitação: Formata os pedidos de cancelamento para que sejam compreendidos pelo GelatoConnect

Modelos de dados de saída

Estes modelos formatam os dados que são enviados do GelatoConnect de volta para os seus clientes ou para os sistemas deles:

  • Formatação de resposta: Estrutura as respostas da API para envios ou cancelamentos de pedidos

  • Notificações de eventos: Cria mensagens padronizadas para atualizações de status de pedidos

  • Postbacks: Formata os dados enviados para sistemas externos quando o status dos pedidos muda

Todos os modelos utilizam a linguagem de template Jinja2, que oferece recursos avançados para transformar dados, aplicar lógica condicional e criar conteúdos dinâmicos.

Tipos de modelos que você pode criar

O GelatoConnect oferece suporte a vários tipos de modelos para diferentes direções de fluxo de dados:

Modelos de Dados de Entrada (Cliente → GelatoConnect)

  • Solicitação de envio de pedido: Transforma os dados do pedido do cliente no formato do GelatoConnect

  • Cancelar solicitação: Converte os pedidos de cancelamento dos clientes para o formato do GelatoConnect

Modelos de dados de saída (GelatoConnect → Cliente)

  • Enviar resposta: Formata as respostas enviadas após o envio do pedido

  • Cancelar resposta: Formata as respostas enviadas após solicitações de cancelamento

  • Webhook: Cria cargas JSON para notificar sistemas externos sobre mudanças no status do pedido

  • E-mail: Formata notificações por e-mail para diferentes eventos de pedidos

Entender a direção do fluxo de dados é fundamental ao criar modelos, pois isso define quais dados estarão disponíveis e como devem ser organizados.

Guia passo a passo para criar um modelo

1. Acesse a seção de modelos

  1. Acesse sua conta GelatoConnect

  2. Vá para Fluxo de trabalho > Entrada de pedidos > Modelos

  3. Clique no botão Adicionar modelo para começar a criar um novo modelo

2. Escolha o tipo de modelo

Selecione o tipo de modelo que você quer criar:

  • Para integrações de API, normalmente você vai precisar dos modelos de Order Submit Request, Submit Response e Cancel Response.

  • Para notificações, selecione Webhook ou Email

3. Defina o formato do modelo

Escolha o formato para o seu modelo:

  • JSON: Mais comum para integrações de API e Webhook

  • XML: Usado em alguns sistemas antigos

  • Texto simples: Normalmente usado para modelos de e-mail

4. Gere um exemplo de payload de entrada

Para criar um modelo eficaz, é importante entender quais dados estarão disponíveis:

  1. Clique no botão Gerar Modelo

  2. Selecione Adicionar carga útil de entrada de amostra para fornecer dados de teste

  3. Escolha o tipo de evento apropriado no menu suspenso:

    • Pedido recebido

    • Pedido Falhou

    • Pedido cancelado

    • Pedido devolvido

    • Pedido produzido

    • Pedido Entregue

    • Encomenda enviada

    • Pedido em trânsito

O sistema vai preencher um exemplo de payload com dados típicos desse evento, que você pode usar como referência ao criar seu modelo.

5. Crie o seu Template Mapper

O Mapeador de Modelos é onde você define como os dados são transformados entre formatos:

  1. Na seção Template Mapper, escreva o seu modelo usando a sintaxe Jinja2

  2. Consulte os dados de referência do payload de entrada usando chaves duplas: ##{{ variable }}

  3. Adicione filtros de formatação com o símbolo de pipe: ##{{ variable|js }} (o filtro js escapa strings para JSON)

  4. Use estruturas de controle como {% if %}, {% for %} e {% set %} para lógica condicional e loops

Considerações sobre a orientação do modelo

O conteúdo do seu modelo irá variar dependendo se você está lidando com dados de entrada ou saída:

Para modelos de dados recebidos (Cliente → GelatoConnect):

  • Concentre-se na extração de dados de formatos personalizados específicos do cliente

  • Mapeie os nomes de campos personalizados para os nomes de campos padrão do GelatoConnect

  • Valide e transforme os dados para atender aos requisitos do GelatoConnect

  • Lidar com quaisquer necessidades especiais de formatação ou conversão de dados

Para Modelos de Dados de Saída (GelatoConnect → Cliente):

  • Estruture os dados conforme o que o sistema do cliente espera

  • Inclua todos os campos obrigatórios para a integração do cliente

  • Formate datas, valores monetários e outros dados de acordo com as preferências do cliente

  • Adicione quaisquer identificadores ou referências específicas do cliente

Exemplo: modelo de Webhook de pedido recebido

Aqui está um modelo de exemplo para um webhook de "Pedido Recebido":

{  "event": "Pedido recebido",  \"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": "O pedido foi recebido."}

Este modelo cria uma estrutura JSON com os detalhes do pedido e percorre todos os itens do pedido.

6. Renderize e verifique o modelo

Após criar seu modelo:

  1. Clique no botão Renderizar para compilar o modelo

  2. Revise o resultado no painel de visualização

  3. Verifique se todos os dados estão formatados corretamente e se não há erros de sintaxe

  4. Verifique se há campos ausentes ou preenchidos de forma incorreta

7. Teste seu modelo

Testar é fundamental para garantir que o seu modelo funcione corretamente:

  1. Atribua um nome ao seu teste na seção Modelo de Teste

  2. Clique em Executar teste para aplicar o modelo aos dados de exemplo

  3. Verifique se o Status aparece como Aprovado

  4. Revise o resultado para garantir que ele atenda às suas expectativas

8. Salve seu modelo

Quando você estiver satisfeito com o modelo:

  1. Dê ao seu modelo um nome descritivo

  2. Clique em Adicionar modelo ou Salvar alterações para salvá-lo

  3. O modelo agora estará disponível para uso em gatilhos e configurações de fluxo de trabalho

Usando modelos com gatilhos

Os modelos são geralmente usados com gatilhos para automatizar notificações quando determinados eventos acontecem:

1. Crie um gatilho

  1. Acesse Workflow > Recebimento de pedidos > Gatilhos

  2. Clique em Adicionar Gatilho

  3. Selecione o cliente para o qual este gatilho se aplica

  4. Dê um nome ao seu gatilho (exemplo: "Notificação de pedido recebido")

  5. Selecione o evento que vai ativar o gatilho (por exemplo, "Pedido recebido")

2. Configure o método de entrega

Escolha como as notificações devem ser entregues:

  • URL: Envie um Webhook para um sistema externo

    • Informe a URL de destino

    • Selecione o método POST ou GET

    • Escolha o formato JSON ou XML

    • Configure as opções de nova tentativa, se desejar

  • E-mail: Enviar uma notificação por e-mail

    • Insira os endereços de e-mail dos destinatários

    • Adicione uma linha de assunto

    • Informe o nome e o endereço do remetente

3. Selecione o seu modelo

  1. No menu suspenso Modelo, selecione o modelo que você criou anteriormente

  2. Se não existir um modelo, você pode criar um diretamente na configuração do gatilho usando a mesma interface descrita acima

Criando modelos diretamente a partir de gatilhos

Para sua conveniência, você também pode criar modelos enquanto configura os gatilhos:

  1. Ao criar um gatilho, em vez de selecionar um modelo existente, clique em Criar modelo

  2. Defina o formato do modelo (JSON, XML ou texto simples)

  3. Use o editor de modelos para criar seu modelo conforme descrito acima

  4. Salve o modelo e ele será selecionado automaticamente para este gatilho

Essa abordagem é útil para a criação rápida de modelos quando você já está configurando um gatilho.

Vinculando modelos personalizados a endpoints de API

Ao enviar pedidos pela API, muitas vezes será necessário adaptar os dados do seu formato para o formato do GelatoConnect. Os templates fazem essa transformação, mas é preciso vincular explicitamente o seu template ao endpoint da API para que ele seja aplicado.

Como vincular um modelo a um endpoint de envio de pedido:

  1. Navegue até sua lista de conectores e clique no hiperlink Editar ao lado do endpoint de envio de pedido.

  2. Na página de configuração do endpoint, localize a seção Modelo de endpoint

  3. Selecione o seu modelo de envio de pedido no menu suspenso

  4. Clique no botão Definir endpoint no canto superior direito da página

  5. Clique em Salvar alterações no canto superior direito para aplicar sua configuração

Após concluir estas etapas, todos os envios de pedidos feitos para este endpoint usarão o seu modelo para transformar os dados antes do processamento. Assim, o formato do seu sistema será convertido corretamente para o formato esperado pelo GelatoConnect.

Sem essa configuração, o seu modelo não será aplicado, mesmo que exista e esteja corretamente criado. Isso pode causar falhas na validação do pedido se o formato dos seus dados não estiver exatamente de acordo com os requisitos do GelatoConnect.

Técnicas avançadas de template

Usando Consultas

As pesquisas são especialmente valiosas para o mapeamento bidirecional de dados entre sistemas. Elas funcionam de maneiras diferentes, dependendo da direção do modelo:

Para modelos recebidos (Cliente → GelatoConnect):

Mapeie valores específicos do cliente para os valores padronizados do GelatoConnect:

{% set shipMethod = lookups({"shipping_code": order.shipping.method}, strict=False, default="normal") %} "shipmentMethodUid": ##{{ shipMethod|js }},

Para modelos de saída (GelatoConnect → Cliente):

Transforme os valores internos do GelatoConnect para os formatos esperados pelo cliente:

{% set customerShippingCode = lookups({\"gelatoShipMethod\": shipment.shipmentMethodUid}, strict=False, default=shipment.shipmentMethodUid) %} \"shipping_method\": ##{{ customerShippingCode|js }},

Lógica condicional

Use condições para incluir ou formatar dados de maneira diferente com base nas circunstâncias:

{% if item.fulfillmentStatus == \"shipped\" %}  \"trackingNumber\": \"##{{ item.trackingCode }}\",  \"trackingUrl\": \"##{{ item.trackingUrl }}\",{% endif %}

Atribuição de variável

Crie variáveis para simplificar expressões complexas:

{% set fullName = customer.firstName + " " + customer.lastName %} "recipientName": "##{{ fullName }}",

Loops com Objetos Complexos

Navegue por estruturas de dados aninhadas:

\"items\": [  {% for item in items %}    {      \"sku\": \"##{{ item.sku }}\",      \"quantity\": ##{{ item.quantity }},      \"options\": [        {% for option in item.options %}          {            "name": "##{{ option.name }}",            "value": "##{{ option.value }}"          }{% if not loop.last %},{% endif %}        {% endfor %}      ]    }{% if not loop.last %},{% endif %}  {% endfor %}]

Melhores práticas para templates

Convenções de nomenclatura baseadas em direção

  • Use nomes claros e descritivos que indiquem tanto o propósito quanto a direção do fluxo de dados

  • Para modelos recebidos: Inclua prefixos como \"IN_\" ou sufixos como \"_Request\"

  • Para modelos de saída: Use prefixos como "OUT_" ou sufixos como "_Response" ou "_Notification"

  • Inclua o nome do cliente para modelos personalizados para cada cliente

  • Use padrões de nomenclatura consistentes para facilitar a localização dos modelos

Gerenciamento de erros

  • Defina valores padrão para evitar referências nulas

  • Use o filtro default para valores ausentes: ##{{ variable|default('N/A') }}

  • Use blocos try/except para trechos de código que possam apresentar problemas

Manutenção

  • Adicione comentários para explicar lógicas complexas: {# Isso trata de um caso especial para pedidos internacionais #}

  • Mantenha os modelos modulares e focados em propósitos específicos

  • Atualize os modelos quando as estruturas de dados ou requisitos mudarem

Testando

  • Teste com diferentes cenários de dados, inclusive situações-limite

  • Sempre que possível, verifique os modelos com dados reais de produção

  • Crie testes completos para os templates mais importantes

Resolvendo problemas com modelos

Problemas comuns e soluções

Problema

Possível Causa

Solução

Erro de sintaxe

Colchetes ou aspas não correspondentes

Verifique atentamente a sintaxe do modelo; certifique-se de que todas as tags de abertura tenham as tags de fechamento correspondentes

Dados ausentes

Referenciando campos que não existem

Verifique os nomes dos campos em relação ao payload de entrada; adicione valores padrão para os campos opcionais

Problemas de formatação

Uso incorreto do filtro

Confirme o uso correto de filtros como js, json ou xml

Modelo não aplicado

Modelo não vinculado ao gatilho

Verificar a configuração do gatilho e a seleção do modelo

Erros ao acessar dados aninhados

Caminho incorreto para propriedades aninhadas

Verifique a estrutura dos dados e ajuste os caminhos das propriedades conforme necessário

Erros de mapeamento de campos

Nomes de campos incorretos para dados de entrada/saída

Para modelos recebidos, verifique os nomes dos campos do cliente; para modelos enviados, confira o formato de resposta esperado

Problemas na transformação de dados

Formatos de dados incompatíveis

Garanta a conversão correta dos tipos de dados entre os sistemas (datas, números, etc.)

Dicas para solucionar problemas

  • Use o botão Renderizar com frequência durante o desenvolvimento para detectar erros precocemente

  • Adicione uma saída de depuração temporária para verificar os valores das variáveis

  • Verifique se há erros de digitação nos nomes dos campos, pois isso costuma causar problemas

  • Lembre-se de que o Jinja2 diferencia maiúsculas de minúsculas ao referenciar variáveis

Artigos relacionados
[Entrada de Pedidos - GCW] Como configurar postbacks?
[Entrada de Pedidos - GCW] Trabalhando com Endpoints da API de Pedidos
[Entrada de Pedidos - GCW] Introdução aos Mapeadores de Modelos
[Entrada de Pedidos - GCW] Criando um Modelo
[Entrada de Pedidos - GCW] Integrando o GelatoConnect com o Cloudprinter
Respondeu à sua pergunta?