[Loja Virtual] Integração do SOMA Gestão com a Plataforma Tray Commerce

Tags: tray integração implantação loja-virtual

Objetivo

Este documento é um guia interno de implantação, no formato de passo a passo, para configurar a integração entre o ecossistema SOMA Gestão (não apenas o ERP) e a Tray.

A integração permite, principalmente:

  • Enviar do SOMA para a Tray: categorias, marcas, variações, produtos, preços, estoque, imagens e (em cenários aplicáveis) informações pós-venda.

  • Trazer da Tray para o SOMA: pedidos, clientes e informações de logística/etiquetas conforme o fluxo do cliente.

Conceito-chave: o sincronismo é um conjunto de três aplicações “intermediárias” que executa a troca de dados. Ele fica rodando e, em intervalos definidos, sincroniza o SOMA com a Tray.

Visão geral da arquitetura e do fluxo

Componentes envolvidos

  1. SOMA Gestão

    • ERP onde estão os cadastros (produtos, clientes, estoque, cotações, etc), as regras, os parâmetros e rotinas operacionais.

  2. Loja Virtual (Plataforma Tray)

    • Onde o lojista vende, recebe pedidos, publica produtos e realiza operações do e-commerce.

  3. Sincronismo

    • Aplicações instaladas no ambiente do cliente (ou servidor designado) que fazem a sincronização de informações entre o SOMA e a Tray.

Sincronismo: são três (e por que isso importa)

Na implantação, considere três sincronismos distintos, porque cada um atende um conjunto de responsabilidades:

  1. Sincronismo de Produtos

    • Envia para a Tray: categorias, marcas/fabricantes, características/variações e produtos (incluindo variações).

    • Finalidade: garantir que o catálogo da loja reflita o cadastro do SOMA.

  2. Sincronismo de Pedidos

    • Traz da Tray: pedidos (que entram no SOMA como cotações, conforme o fluxo definido) e clientes vinculados a esses pedidos.

    • Finalidade: fazer o pedido “cair” no SOMA para processamento (estoque, faturamento, expedição, etc.).

  3. Sincronismo de Nota Fiscal / Etiquetas

    • Envia para a Tray dados de documentos fiscais (nota fiscal) e gera as etiquetas do Mercado Livre.

    • Finalidade: integrar pós-venda/logística conforme o modelo do cliente.

Passo a passo de implantação

Etapa 1) Entender as credenciais e a autorização “dos dois lados”

A integração só funciona quando existem dois níveis de autorização:

  • Autorização do lado da SOMA (integrador): comprova que o cliente possui contrato vigente com a SOMA e que foi devidamente autorizado a utilizar o serviço de sincronismo.

  • Autorização do lado do lojista (cliente): prova que aquela loja específica permitiu que o SOMA acesse os dados dela.

Isso explica por que existem dois grupos de chaves: as do integrador (fixas) e as do lojista (por cliente).

 

Etapa 2) Configurar as Chaves do Integrador (fixas da SOMA)

O que são

  • São as chaves que a SOMA recebeu quando:

    • preencheu o formulário/processo de homologação na Tray,

    • cadastrou o aplicativo no catálogo,

    • e teve o aplicativo aprovado como integrador.

Por que são fixas

  • Porque representam a identidade do integrador: SOMA Soluções (o aplicativo da SOMA).

  • Elas não variam por cliente, pois não representam a loja do cliente; representam o “quem está integrando”.

O que acontece se não configurar

  • O sincronismo nem consegue iniciar autenticação correta do lado “aplicativo”, mesmo que o lojista tenha instalado.

Parâmetros (solicitar para o desenvolvimento)

  • CONSUMER_KEY_TRAY

  • CONSUMER_SECRET_TRAY

 

Etapa 3) Configurar os Dados de Integração do Lojista (por cliente)

O que são

  • Quando o lojista entra na loja Tray dele e instala o aplicativo da SOMA, a Tray entrega para ele os dados de integração.

  • Esses dados identificam “qual loja” será acessada.

Quais são

  • CODE_TRAY: token/código do lojista (daquela loja)

  • API_ADDRESS_TRAY: endereço da API daquela loja

Por que isso existe

  • Como a SOMA pode atuar como integradora de várias lojas, esse par (code + api address) identifica de forma única qual loja deve ser conectada no sincronismo e comprova que o logista autorizou a SOMA a consultar e manipular os dados dessa loja.

Parâmetros

  • CODE_TRAY

  • API_ADDRESS_TRAY

 

Etapa 4) Infraestrutura do sincronismo: usuário, instalação, padrão e operação contínua

O sincronismo não é “uma execução pontual”. Ele precisa ficar rodando.

Recomendação interna

  • Criar um usuário dedicado no sistema operacional para o sincronismo, com padrão de nome e senha (conforme política interna).

  • Evitar logoff desse usuário, se a aplicação estiver no modo que depende de sessão (especialmente quando “aplicativo gráfico precisa ficar aberto”).

Motivo

  • Se a sessão cair/logoff ocorrer, o sincronismo pode parar e:

    • pedidos deixam de entrar,

    • atualizações de preço/estoque deixam de subir,

    • fila de integração fica defasada.

Preparar o local de instalação

  1. Identifique a pasta onde o SOMA Gestão (ERP) está sendo executado no servidor/estação (onde ficam os executáveis do ERP - Oficina.exe).

  2. É nesse mesmo local que as pastas Integrações e Serviços devem ficar.

Objetivo: manter o padrão de execução do ambiente e garantir que tudo que depende do runtime do ERP (ou da mesma estrutura operacional) rode no mesmo contexto.

Extrair o pacote base (Integrações e Serviços)

  1. Extraia o pacote SOMA Gestão - Implantação - Integrações e Serviços.zip.

  2. Copie (ou mova) as pastas Integrações e Serviços para dentro da pasta onde o SOMA Gestão executa.

Inserir os executáveis da Integração Tray

  1. Extraia o pacote IntegracaoTrayPack.zip.

  2. Copie os executáveis para as pastas correspondentes:

  • IntegracaoTrayProduct.exe - Integrações\Tray\Produtos\

  • IntegracaoTrayOrder.exe - Integrações\Tray\Pedidos\

  • IntegracaoTrayNFe.exe - Integrações\Tray\Notas Fiscais\

Observação: este pacote contém somente os executáveis. As dependências (DLLs/config) já vêm no pacote base.

Execução contínua (serviços)

A operação completa normalmente envolve dois blocos independentes:

A) Integrações (Tray)

  • Os executáveis da Tray ficam em Integrações\Tray\...

  • Responsáveis pelo sincronismo de:

    • Produtos

    • Pedidos

    • Nota Fiscal / Etiquetas

B) Serviços do SOMA Gestão

  • A pasta Serviços\SOMA Gestão\... é destinada a tudo que o ERP precisa rodar em segunda instância (rotinas internas e serviços complementares).

  • Esse serviço é gerado sob medida por cliente, então:

    • não é um executável “genérico”

    • deve ser solicitado ao Desenvolvimento para compilação/entrega do binário específico

A pasta já deve ficar preparada no local correto, para quando o Desenvolvimento disponibilizar o executável do serviço do cliente.

Sincronismo de imagens (FileS)

  • O sincronismo de imagens para nuvem é feito pelo componente FileS (interno ao serviço do SOMA Gestão).

  • Ele roda dentro do bloco Serviços do SOMA Gestão e não dentro dos executáveis da Tray.

Detalhes internos do FileSync não precisam estar descritos aqui — o importante na implantação é entender onde ele roda e em qual pasta ele deve ficar.

Validação inicial (antes de “subir em produção”)

  1. Validar se as pastas estão no local correto (junto do executável do SOMA Gestão, o Oficina.exe).

  2. Validar configurações.

 

Etapa 5) Configuração de Nuvem (AWS) para imagens e por quê

Além de cadastro de produto, a loja precisa de imagens. Em muitos cenários, o sincronismo faz a ponte para disponibilizar essas imagens na nuvem.

Objetivo

  • Garantir que as imagens dos produtos estejam acessíveis/estáveis para consumo pela plataforma.

Passo a passo

  1. Entrar no console AWS e criar um usuário no IAM (usuário dedicado para esse cliente/serviço).

  2. Criar chaves de acesso (Access Key / Secret Key).

  3. Salvar as chaves no LastPass.

  4. Instalar o serviço do SOMA Gestão responsável por sincronizar imagens para a nuvem.

Diretriz operacional: usar usuário dedicado e guardar credenciais de forma rastreável reduz risco operacional e facilita manutenção.

 

Etapa 6) Criar o Tipo de Cliente LOJA VIRTUAL e por quê

Pedidos importados trazem dados de comprador. No SOMA, isso precisa cair com um “carimbo” de origem.

Por que existe

  • Para diferenciar clientes originados do e-commerce de outros clientes (balcão, televendas, cadastro manual).

  • Para aplicar regras específicas (ex.: validações, políticas comerciais, relatórios, filtros operacionais).

Como fazer

  1. Cadastrar um tipo de cliente “LOJA VIRTUAL”.

  2. Informar no parâmetro:

  • COD_TIPO_CLIENTE_WEB

 

Etapa 7) Preparar o Operador LOJA VIRTUAL (ou operador humano) e o porquê

Durante a importação, principalmente de pedidos/cotações, o sistema precisa saber qual operador “assina” aquele registro.

Por que criar

  • Para evitar que registros importados fiquem com operador vazio.

  • Para identificar que a origem daquele lançamento foi a loja virtual/sincronismo.

Como fazer

  1. Criar o operador “LOJA VIRTUAL” no cadastro de operadores (ou definir um operador humano responsável).

  2. Configurar:

    • empresas que esse operador pode operar,

    • acessos aos estoques que ele deve enxergar/operar.

Parâmetros relacionados

  • CD_OPERADOR_WEB: operador “dono” do processo de importação (ex.: para vincular a cotação importada).

  • CD_OPERADOR_WEB_AVISO: operador(es) que devem receber avisos/notificações no fluxo (quando aplicável internamente).

Regra prática: CD_OPERADOR_WEB resolve consistência de cadastro (não deixar vazio) e rastreabilidade (“foi a loja”). O parâmetro de “aviso” é para direcionar atenção humana quando necessário.

 

Etapa 8) Definir Forma de Pagamento Padrão e o motivo real

No mundo real, nem sempre o pagamento da Tray “casa” 1:1 com o cadastro de formas de pagamento do SOMA.

Problema que esse parâmetro resolve

  • Pedido importado vem com uma forma que não foi mapeada, sem fallback, a importação pode falhar ou ficar inconsistente.

O que fazer

  • Definir uma forma padrão (ex.: “PAGAMENTO LOJA VIRTUAL”) e configurar:

  • FORMA_PAGTO_PADRAO_WEB

Isso não impede mapeamentos corretos; apenas garante que sempre exista uma forma válida quando o vínculo não existir.

 

Etapa 9) Configurar Unidades (peso e dimensões) entendendo conversões

Aqui não é só “texto”: a unidade informada influencia conversões no sincronismo.

Por quê

  • A Tray pode exigir medidas em um padrão (ex.: peso em gramas), enquanto o cliente pode cadastrar no SOMA em quilogramas.

  • O sincronismo, ao saber a unidade usada no SOMA, consegue converter para o formato que a Tray espera.

Como funciona na prática

  • Se o cliente informar kg (ou equivalente mapeado) e a Tray exigir g, o sincronismo converte (ex.: 1,2 kg para 1200 g).

  • O mesmo vale para dimensões: cm, m, mm etc.

Risco se configurar errado

  • Se for informada uma unidade que não existe ou não está mapeada no sincronismo, não haverá conversão.

  • Resultado: medidas podem subir erradas ou a plataforma pode interpretar incorretamente.

Parâmetros

  • Dimensões: SIGLA_UNIDADE_MEDIDA_DIMENSOES

  • Peso: SIGLA_UNIDADE_MED_PESO

Unidades comuns (esperadas)

  • Peso: g, kg

  • Dimensões: mm, cm, m

 

Etapa 10) Configurar Tabela de Preço Padrão e por quê

O que é “tabela de venda”

É uma forma de precificação onde o preço final não é “um valor fixo único”, mas um preço calculado a partir de uma tabela com percentuais/regras (muito usado para negociação e políticas de comissão).

Exemplo de uso real:

  • Tabela 1: preço mais alto (melhor comissão).

  • Tabela 2: preço mais competitivo (mais desconto).

  • A escolha influencia a margem e a dinâmica de venda.

Por que esse parâmetro é crítico na loja

Se o cliente trabalha com tabela de venda, o sincronismo não pode depender apenas do “valor de venda do cadastro”, porque o preço correto para o e-commerce precisa ser calculado com a tabela definida.

O que configurar

  • TABELA_VENDA_WEB_PADRAO

Efeito

  • Define qual tabela será usada como base para calcular o preço de venda enviado para a Tray.

Observação: neste contexto, a tabela de venda impacta o preço de venda (não o custo).

 

Etapa 11) Parâmetros funcionais adicionais e como interpretar cada um

Abaixo, os parâmetros que normalmente “dão problema” quando não se entende o porquê.

COD_TIPO_ENDERECO_INATIVO

Define qual código de Tipo de Endereço será usado pelo sincronismo para marcar/inativar endereços antigos que não devem mais ser considerados válidos.

Por que importa: durante o sincronismo (principalmente de clientes/pedidos), é comum o sistema precisar “trocar” ou atualizar endereços. Ao invés de apagar registros (o que pode gerar perda de histórico e problemas de rastreabilidade), o processo inativa os endereços antigos usando um Tipo de Endereço específico, definido por este parâmetro.

TIPO_ETIQUETA_TRAY

Define o formato de etiqueta no fluxo (pdf ou zpl2).

  • pdf: etiqueta no formato de um arquivo .pdf.

  • zpl2: etiqueta na forma de comandos que serão enviados para impressoras matriciais compatíveis.

Por que importa: se escolher formato incompatível com o ambiente, a operação de impressão/logística trava.

ESTRU_WEB_PADRAO

Define a estrutura/canal padrão para identificar origem de venda (ex.: Loja própria, Mercado Livre, Shopee, etc.) quando não houver correspondência direta.

Por que existe: o SOMA precisa “classificar” a venda para relatórios, regras e integrações.

ENVIA_PRODUTO_WEB_SEM_IMAGEM

Controla se o produto pode ser enviado para a loja mesmo sem imagem.

Por que existe: alguns clientes preferem catálogo completo (mesmo sem foto), outros preferem bloquear para não “queimar vitrine”.

SOB_CONSULTA_AO_ZERAR_ESTOQUE_WEB

Quando o estoque zerar, em vez de tirar o produto do ar, pode manter como “sob consulta”.

Por que existe: estratégia comercial. Produto continua indexado/visível, mas não permite compra direta.

STATUS_PEDIDO_WEB_CANCELADO

Nome/identificador do status da Tray que equivale a “cancelado” para o SOMA alinhar corretamente.

Por que existe: sem isso, cancelamentos podem ficar inconsistentes entre loja e retaguarda.

UNIDADE_MAPEADA_SERVIDOR e CAMINHO_UNIDADE_MAPEADA_SERVIDOR

Usados quando o ambiente utiliza unidade mapeada (ex.: S:) e o serviço precisa acessar o caminho real.

Por que existe: serviços/rotinas executadas “como serviço” nem sempre enxergam mapeamentos de drive como um usuário logado.

Checklist final de parâmetros

Configurar e validar:

  • CONSUMER_KEY_TRAY

  • CONSUMER_SECRET_TRAY

  • CODE_TRAY

  • API_ADDRESS_TRAY

  • TIPO_ETIQUETA_TRAY

  • TABELA_VENDA_WEB_PADRAO

  • CD_OPERADOR_WEB

  • CD_OPERADOR_WEB_AVISO

  • COD_TIPO_CLIENTE_WEB

  • ENVIA_PRODUTO_WEB_SEM_IMAGEM

  • ESTRU_WEB_PADRAO

  • FORMA_PAGTO_PADRAO_WEB

  • SOB_CONSULTA_AO_ZERAR_ESTOQUE_WEB

  • STATUS_PEDIDO_WEB_CANCELADO

  • UNIDADE_MAPEADA_SERVIDOR

  • CAMINHO_UNIDADE_MAPEADA_SERVIDOR

  • (Unidades)

    • SIGLA_UNIDADE_MEDIDA_DIMENSOES

    • SIGLA_UNIDADE_MED_PESO

Resultado esperado após implantação

Ao final, o cenário “mínimo saudável” é:

  • A SOMA está autorizada como integrador (consumer key/secret corretos).

  • A loja Tray está autorizada (code + api address corretos).

  • Os sincronismos estão instalados, rodando continuamente e com usuário/infra adequados.

  • Produtos, variações, preços, estoque e imagens sobem corretamente.

  • Pedidos entram no SOMA como cotações sem a necessidade de completar informações.

VOLTAR

Outros Artigos

Nenhum artigo relacionado.