Passar para o conteúdo principal

[Entrada de Pedidos - GCW] Como Configurar Consultas

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

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

  1. Entre na 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 na parte superior da página.

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

  3. Selecione o Cliente ao qual esta pesquisa será aplicada no menu suspenso.

  4. Adicione uma Descrição (opcional, mas recomendado) para ajudar a identificar o propósito da consulta.

  5. 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}}).

  6. 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).

  7. Repita para todos os valores que precisam ser mapeados.

  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 \"Chave de pesquisa\" 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

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):

  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) %} "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á 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

Quer saber mais?

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

  1. Saiba mais sobre como criar um modelo para recebimento de pedidos

  2. Configure postbacks para atualizar seus clientes

Artigos relacionados
[Entrada de Pedidos - GCW] Como configurar postbacks?
[Entrada de Pedidos - GCW] Exemplos de Mapeador de Modelos
[Entrada de Pedidos - GCW] Criando Modelos para Entrada de Pedidos
[Entrada de Pedidos - GCW] Introdução aos Mapeadores de Modelos
[Entrada de Pedidos - GCW] Integrando o GelatoConnect com o Cloudprinter
Respondeu à sua pergunta?