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
✅ As consultas garantem que os dados sejam padronizados para o sistema da Gelato. Evitando incompatibilidades entre valores específicos do cliente e valores compatíveis com a Gelato.
✅ Eles permitem valores alternativos para evitar erros em caso de mapeamentos ausentes.
✅ O envio em massa de arquivos CSV facilita o gerenciamento de mapeamentos em grande escala.
Configurando Consultas: Guia Passo a Passo
1. Acesse a página de Consultas
Entre na sua conta GelatoConnect
Navegue até Fluxo de trabalho > Entrada de pedidos no menu à esquerda
Clique em Consultas para ver os mapeamentos existentes ou criar novos
2. Criar uma nova tabela de consulta
Opção A: Criação Manual
Clique no botão Criar na parte superior da página.
Insira um Nome descritivo para sua consulta (ex.: \"Mapeamento de SKU de Produto\")
Selecione o Cliente ao qual esta pesquisa será aplicada no menu suspenso.
Adicione uma Descrição (opcional, mas recomendado) para ajudar a identificar o propósito da consulta.
Insira um Campo de Modelo - esta é a referência usada no código do mapeador de modelos para acessar esta consulta. O campo de busca do modelo deve estar entre duas chaves duplas (por exemplo, ##{{sku}}).
Adicione mapeamentos clicando no ícone +:
Chave: Insira o valor do seu sistema (por exemplo, seu SKU ou código do produto).
Valor: Insira o valor correspondente da Gelato (por exemplo, o UID do produto da Gelato).
Repita para todos os valores que precisam ser mapeados.
Clique em Salvar alterações para aplicar a configuração.
Opção B: Importação em Massa (Recomendado para Muitos Valores)
Prepare um arquivo Excel ou CSV com duas colunas:
Coluna A: Cabeçalho \"Chave de pesquisa\" seguido pelos valores do seu sistema
Coluna B: Cabeçalho \"UID do Produto\" seguido pelos valores correspondentes da Gelato
Clique em Criar para iniciar uma nova pesquisa
Preencha os campos Nome, Cliente, Descrição e Modelo conforme acima
Clique em Importar em vez de adicionar entradas manualmente
Selecione o seu arquivo Excel/CSV preparado
Revisar os mapeamentos importados
Clique em Salvar alterações para concluir a configuração
Guia em Vídeo
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):
Acesse Workflow > Recebimento de pedidos > Modelos
Edite o modelo onde você deseja usar pesquisas
Na seção Template Mapper, use a função
lookups()para acessar suas tabelas de mapeamentoSintaxe 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:
Acesse seu modelo na seção Modelos
Navegue até a guia Teste de Modelo
Use o formulário de teste para verificar se suas consultas estão traduzindo os valores corretamente
Verifique se as chaves ausentes usam corretamente o seu valor padrão
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) %} "transportadora": ##{{ 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á ausenteSempre 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
Quer saber mais?
Agora que você já configurou os lookups para a integração da sua API, talvez queira:
Saiba mais sobre como criar um modelo para recebimento de pedidos
Configure postbacks para atualizar seus clientes