Tray — Integração com E-commerce¶
Aplicativo externo
IntegracaoTray.exe| Sincronização automática em intervalo configurável
O que é¶
A Integração Tray é um aplicativo standalone (separado do Master Key) que roda minimizado na bandeja do Windows e sincroniza dados entre o Master Key e uma loja na plataforma de e-commerce Tray. A sincronização ocorre automaticamente em intervalos configuráveis.
O fluxo é bidirecional: - Master Key → Tray: produtos, variações, grades, categorias, especificações, imagens e notas fiscais - Tray → Master Key: pedidos e clientes
Pré-requisitos¶
- Chave de liberação válida cadastrada no Master Key para a filial utilizada
- URL e Código de autorização fornecidos pela Tray (obtidos no painel da loja)
- Banco de dados do Master Key acessível pelo computador onde o aplicativo roda
Configuração¶
Acesse o menu Opções → Configurações dentro do aplicativo. As configurações são salvas no arquivo IntegracaoTray.ini na mesma pasta do executável.
Aba API¶
| Campo | O que é |
|---|---|
| URL | URL da loja na Tray (ex.: https://sualoja.commercesuite.com.br) |
| Código | Código de autorização gerado no painel da Tray |
Sem URL e Código configurados o sistema registra atenção no log e encerra o ciclo sem sincronizar.
Aba Integração¶
| Campo | O que é |
|---|---|
| Filial | Filial do Master Key utilizada como base da integração |
| Filiais de Estoque | Filiais cujo saldo soma para calcular o estoque enviado à Tray |
| Tabela de Preço | Tabela de preços utilizada para price. Marque Usar Preço de Venda 2 para usar o preço 2 independente de tabela |
| Intervalo (seg) | Tempo entre cada ciclo de sincronização |
| Vendedor | Código do vendedor padrão para pedidos importados da Tray |
| Tipo de Frete | Tipo de frete padrão para os pedidos (ex.: Destinatário) |
| Similares como Variações | Envia produtos similares do Master Key como variações na Tray |
| Grades como Variações | Envia grades de produto como variações na Tray (não pode ser usado junto com Similares) |
| Referência na Descrição | Adiciona o código de referência do produto ao nome enviado à Tray |
| Pedidos a partir de | Data mínima de criação dos pedidos Tray que serão importados |
Campos de Inserção / Atualização / Exclusão¶
A tela apresenta três árvores de campos configuráveis:
- Inserção: campos enviados quando o produto ainda não existe na Tray
- Atualização: campos enviados quando o produto já existe (campos de imagem são tratados separadamente via FTP/AWS)
- Exclusão: define se produtos, variações e grades podem ser excluídos da Tray quando inativados no Master Key
Cada árvore exibe os grupos: Produtos, Variações, Categorias e Especificações. Campos marcados em cinza são obrigatórios e não podem ser desmarcados.
Aba Clientes¶
Configurações para clientes importados automaticamente a partir dos pedidos Tray:
| Campo | O que é |
|---|---|
| Vendedor | Vendedor padrão atribuído ao cliente |
| Praça | Praça padrão atribuída ao cliente |
| Atividade | Atividade padrão atribuída ao cliente |
Aba FTP¶
Configurações para envio de imagens dos produtos via FTP:
| Campo | O que é |
|---|---|
| Host | Endereço do servidor FTP |
| Usuário | Login FTP |
| Senha | Senha FTP |
| Pasta | Pasta de destino no servidor FTP |
| URL de Imagens | URL pública base das imagens (enviada à Tray como picture_source) |
Imagens também podem ser enviadas via AWS S3 quando configurado.
Fluxo de Sincronização¶
A cada ciclo, o aplicativo executa as etapas abaixo na ordem:
1. Pedidos (Tray → Master Key)¶
Consulta na Tray os pedidos modificados desde a última verificação. Para cada pedido: - Busca os detalhes completos do pedido via API - Cria ou atualiza o pedido no Master Key - Cria o cliente automaticamente se não existir
Controle salvo em Integracao → UltimaVerificacaoPedidos no INI.
2. Notas (Master Key → Tray)¶
Envia para a Tray as notas fiscais emitidas/modificadas no Master Key desde o último envio. A nota é vinculada ao pedido correspondente na Tray.
Controle salvo em Integracao → UltimaAtualizacaoNotas.
3. Exclusões (Master Key → Tray)¶
Remove da Tray produtos, variações e grades que foram inativados/excluídos no Master Key — somente se os respectivos grupos estiverem marcados na aba de Exclusão.
Se uma exclusão falhar, as exclusões subsequentes do mesmo ciclo são canceladas para evitar inconsistências.
4. Categorias (Master Key → Tray)¶
Sincroniza as categorias de produtos. O ID da categoria na Tray é gravado na tabela CAMPOS do Master Key para referência futura.
A Tray limita a profundidade de categorias e subcategorias. O sistema avisa no log se esse limite for excedido.
5. Produtos (Master Key → Tray)¶
Envia produtos modificados desde a última sincronização.
| Campo Master Key | Campo Tray | Descrição |
|---|---|---|
PR_CODIGO |
reference |
Código interno (obrigatório) |
EC_NOMEPROD / PR_NOME |
name |
Nome do produto |
PR_OBS |
description |
Observação / descrição |
PR_CODBARRA |
ean |
Código de barras |
MA_NOME |
brand |
Marca |
PR_NCM |
ncm |
NCM |
DT_PERCIPI |
ipi_value |
% IPI |
PR_PBRUTO |
weight |
Peso bruto (em gramas) |
EC_ALTURA |
height |
Altura (cm) |
EC_PROFUNDIDADE |
length |
Comprimento (cm) |
EC_LARGURA |
width |
Largura (cm) |
EC_DISP |
available |
Disponível para venda (S=1, N=0) |
SALDO - EC_MARGEMEST |
stock |
Estoque (saldo menos margem de segurança) |
PRECOVENDA |
price |
Preço de venda |
PRECOPROMO |
promotional_price |
Preço promocional |
EC_DATADISP |
release_date |
Data de disponibilidade |
EC_CODIGOML |
id |
Código do produto na Tray (preenchido após inserção) |
6. Especificações / Características (Master Key → Tray)¶
Sincroniza as especificações dos produtos (ex.: cor, material). Se uma especificação for inativada no Master Key e já existir na Tray, é excluída da plataforma.
7. Variações (Master Key → Tray)¶
Sincroniza variações de produtos (ex.: tamanho P/M/G). Imagens de variações são enviadas separadamente via FTP/AWS.
8. Grades como Variações (Master Key → Tray)¶
Quando Grades como Variações está ativo, envia as combinações de grade (cor + tamanho) como variações na Tray.
9. Imagens (Master Key → Tray)¶
Envia imagens dos produtos via FTP ou AWS S3. As URLs públicas das imagens são então enviadas à Tray nos campos picture_source_1 até picture_source_15.
Logs¶
O aplicativo mantém logs em Log\Log_ddMMyyyy.xml (um arquivo por dia) e exibe um grid na tela principal com o histórico. Cada entrada pode ter três situações:
| Ícone | Situação | Quando ocorre |
|---|---|---|
| Verde | Sucesso | Registros sincronizados com sucesso |
| Amarelo | Atenção | Configuração incompleta ou chave inválida |
| Vermelho | Erro | Falha em inserção, atualização ou exclusão |
Clique duas vezes em uma linha de log para abrir o arquivo XML de detalhe da requisição (disponível apenas para erros que geraram arquivo).
Tabelas e campos relevantes¶
| Tabela | Campo | Função |
|---|---|---|
PRODUTOS / ECOMMERCE |
EC_CODIGOML |
Código do produto/variação na Tray. P + ID para produtos, ID puro para variações |
ECOMMERCE |
EC_DISP |
Disponibilidade para venda online |
ECOMMERCE |
EC_MARGEMEST |
Margem de segurança do estoque (descontada do saldo enviado) |
ECOMMERCE |
EC_NOMEPROD |
Nome alternativo para e-commerce (se vazio, usa PR_NOME) |
CAMPOS |
CAMPO / VALOR |
Tabela genérica — armazena o ID da Tray para categorias e especificações |
FILIAIS |
FL_CODIGO |
Filiais disponíveis para seleção de filial e estoque |
Perguntas frequentes do suporte¶
"O aplicativo para de sincronizar sem mostrar erro" → Verifique se a chave de liberação da integração está válida e não vencida (Utilitários → Chave de Liberação no Master Key).
"Produto não está sendo enviado para a Tray"
→ Verifique se o produto tem os campos de e-commerce preenchidos (EC_DISP, EC_CODIGOML vazio para novo produto) e se o grupo Produtos está marcado na aba de Inserção das configurações.
"Estoque está errado na Tray"
→ Confirme quais filiais estão marcadas em Filiais de Estoque. O saldo enviado é SALDO total das filiais - EC_MARGEMEST. Estoque negativo é enviado como zero.
"Pedido da Tray não entrou no Master Key" → Verifique se a data do pedido é posterior à data configurada em Pedidos a partir de. Confira também o log do dia para erros de importação.
"Imagem não aparece na Tray" → Verifique as configurações de FTP (host, usuário, senha, pasta e URL de imagens). A URL de imagens deve ser a URL pública acessível pela Tray, não o caminho local.
"Categoria não está sendo sincronizada" → Verifique se o grupo Categorias está marcado nas abas de Inserção/Atualização. Confira também se os níveis de categorias na Tray não foram excedidos (aviso no log).