Passar para o conteúdo principal

[Order Intake - GCW] Configurando Lookups para integração de API

Escrito por Kyle Sawyer

O que são Consultas e por que são importantes?

As tabelas de consulta no GelatoConnect funcionam como tradutores, convertendo dados do seu sistema para formatos que a Gelato entende. Elas são essenciais para uma integração de API sem complicações, especialmente para mapear:

  • IDs/SKUs de produtos: Converta seus identificadores de produtos personalizados para os UIDs padronizados da Gelato

  • Métodos de envio: Relacione os nomes dos seus métodos de envio com os códigos das transportadoras da Gelato

  • Identificadores de Transportadora: Traduzir nomes de transportadoras entre sistemas

  • Outros Mapeamentos Personalizados: Qualquer valor que precise de tradução consistente entre sistemas

Sem consultas, os pedidos podem falhar quando os identificadores do seu sistema não correspondem aos valores esperados pela Gelato. As consultas fornecem uma maneira confiável de preencher essa lacuna, garantindo um processamento consistente dos pedidos.

Principais benefícios de usar pesquisas

✅ Padronização: Garante a consistência dos dados entre o seu sistema e a Gelato
✅ Prevenção de erros: Reduz falhas devido a identificadores incompatíveis
✅ Proteção de fallback: Fornece valores padrão se correspondências exatas não forem encontradas
✅ Escalabilidade: Facilita o gerenciamento ao adicionar novos produtos ou métodos de envio
✅ Manutenção: Gerenciamento centralizado de mapeamentos para atualizações mais fáceis

Configurando Consultas: Guia Passo a Passo

1. Acesse a página de Consultas

  1. Acesse sua conta GelatoConnect

  2. Navegue até Fluxo de trabalho > Entrada de pedidos no menu à esquerda

  3. Clique em Consultas para ver os mapeamentos existentes ou criar novos

2. Criar uma nova tabela de consulta

Opção A: Criação Manual

  1. Clique no botão Criar no topo da página

  2. Insira um Nome descritivo para sua consulta (ex.: \"Mapeamento de SKU de Produto\")

  3. Selecione o Cliente ao qual este lookup será aplicado no menu suspenso

  4. Adicione uma Descrição (opcional, mas recomendado) para ajudar a identificar a finalidade do lookup

  5. Insira um Campo de modelo - esta é a referência usada no código do mapeador de modelo para acessar este lookup

  6. Adicione mapeamentos clicando no ícone +:

    • Chave: Insira o valor do seu sistema (por exemplo, o SKU ou código do seu produto)

    • Valor: Insira o valor correspondente do Gelato (por exemplo, o UID do produto do Gelato)

  7. Repita para todos os valores que precisam de mapeamento

  8. Clique em Salvar alterações para aplicar a configuração

Opção B: Importação em Massa (Recomendado para Muitos Valores)

  1. Prepare um arquivo Excel ou CSV com duas colunas:

    • Coluna A: Cabeçalho "lookup key" seguido pelos valores do seu sistema

    • Coluna B: Cabeçalho "UID do produto" seguido pelos valores correspondentes da Gelato

  2. Clique em Criar para iniciar uma nova pesquisa

  3. Preencha os campos Nome, Cliente, Descrição e Modelo conforme acima

  4. Clique em Importar em vez de adicionar entradas manualmente

  5. Selecione o seu arquivo Excel/CSV preparado

  6. Revisar os mapeamentos importados

  7. Clique em Salvar alterações para concluir a configuração

3. Implemente pesquisas no seu mapeador de modelos

Depois de configurar suas tabelas de lookups, é preciso referenciá-las no código do seu template mapper (usando Jinja2):

  1. Acesse Workflow > Recebimento de pedidos > Modelos

  2. Edite o modelo onde você deseja usar pesquisas

  3. Na seção Template Mapper, use a função lookups() para acessar suas tabelas de mapeamento

  4. Sintaxe básica: ##{{ lookups({"alias": value_to_lookup}, strict=False, default="fallback_value")|js }}

Exemplo 1: Mapeamento de UID do Produto

{% set productUid = lookups({"sku": item.sku}, strict=False, default=item.sku) %}
"productUid": ##{{ productUid|js }},

Exemplo 2: mapeamento de método de envio

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

O parâmetro strict=False garante que o código não apresentará erro caso não encontre uma correspondência, e o parâmetro default oferece um valor alternativo.

Testando suas pesquisas

Sempre teste suas pesquisas antes de usá-las em produção:

  1. Acesse seu modelo na seção Modelos

  2. Navegue até a guia Teste de Modelo

  3. Use o formulário de teste para verificar se suas consultas estão traduzindo os valores corretamente

  4. Verifique se as chaves ausentes usam corretamente o seu valor padrão

  5. Envie um pedido de teste e verifique se ele foi processado conforme o esperado

Casos de uso comuns

Mapeamento de SKU do Produto para UID da Gelato

Mapeie seus códigos internos de produtos para os UIDs de produtos da Gelato:

{% set productUid = lookups({"sku": item.sku}, strict=False, default=item.sku) %}
"productUid": ##{{ productUid|js }},

Tradução do método de envio

Converta os nomes dos seus métodos de envio para os UIDs de método de envio da Gelato:

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

Mapeamento de Transportadoras

Mapeie identificadores de transportadoras entre sistemas:

{% set carrier = lookups({"carrier_code": shipment.carrier}, strict=False, default=shipment.carrier) %} "carrier": ##{{ carrier|js }},

Mapeamento de Códigos de Estado Específicos por País

Lidar com casos especiais para códigos de estado em países específicos:

{% set stateCode = shipTo.state %}
{% if shipTo.country|upper == "US" %}
    {% set stateCode = lookups({"us_state": shipTo.state}, strict=False, default=shipTo.state) %}
{% endif %}
"state": ##{{ stateCode|js }},

Solução de problemas de consultas

Se suas consultas não estiverem funcionando como esperado:

  • Verifique correspondências exatas: As chaves são sensíveis a maiúsculas e minúsculas e devem corresponder exatamente ao que está nos seus dados de API

  • Verifique os nomes dos campos do modelo: Certifique-se de que o campo do modelo em sua pesquisa corresponde ao que está referenciado em seu modelo

  • Use strict=False: Isso evita erros quando uma chave de pesquisa está ausente

  • Sempre defina valores padrão: Defina valores padrão adequados para lidar com mapeamentos ausentes

  • Verifique a carga útil completa da solicitação: Use a página de Solicitações para examinar a carga útil que está sendo processada

Melhores práticas

  • Use nomes descritivos: Nomeie as pesquisas de forma clara para indicar sua finalidade

  • Adicionar descrições: Inclua detalhes sobre quando e onde cada consulta é utilizada

  • Mantenha os mapeamentos atualizados: Revise e atualize as consultas regularmente conforme os produtos ou serviços mudam

  • Use a importação em massa para grandes conjuntos de dados: Economize tempo importando pesquisas em massa

  • Teste cuidadosamente: Sempre faça testes com valores que correspondem e que não correspondem

  • Documente suas consultas: Mantenha um registro de quais consultas são usadas em quais modelos

Próximos Passos

Agora que você já configurou os lookups para a integração da sua API, talvez queira:

  1. Aprenda sobre como criar um modelo para Order Intake

  2. Explore técnicas avançadas do Template Mapper

  3. Configure Postbacks automáticos para atualizar clientes

Precisa de mais ajuda? Entre em contato com nossa equipe de suporte em [email protected]

Artigos relacionados
Respondeu à sua pergunta?