A VTEX é uma plataforma de e-commerce reconhecida por suas soluções integradas, que facilitam a criação e gestão de lojas virtuais. Ao integrar sua loja VTEX com o Eccosys, você centraliza a gestão de cadastros, estoque, preços, pedidos, rastreio e faturamento em um único sistema, otimizando sua operação e garantindo a sincronização das informações entre as plataformas.

Este manual tem como objetivo guiá-lo pelas configurações necessárias para realizar essa integração de forma eficiente.

Neste manual, você aprenderá:

• Fluxo da integração

• Pré-requisitos para configuração

• Como configurar a integração Eccosys - VTEX

• Como funciona a importação de depósito

• Como funciona a importação e envio de catálogo

• Como funciona a importação de pedidos

• Como é a atualização de pedidos com a VTEX

Fluxo da integração

(*) Enviados apenas em conjunto, quando informados no cadastro do produto.

 "Atributos" e "Marcas" serão enviados nos produtos desde que estas informações tenham sido previamente cadastradas e importadas da plataforma para o Eccosys. 

Entenda quais campos são comunicados entre o Eccosys e a Vtex.

Particularidades da integração com a VTEX

• O envio de imagens em novos produtos é obrigatório.

• Enviamos e importamos apenas um departamento com suas respectivas sub/categorias, por produto.

Pré-requisitos para configuração

• URL da Loja.

• AppKey e Token gerados na VTEX.

⚙️ Como configurar a integração Eccosys - VTEX

Para ativar a comunicação entre o Eccosys e a plataforma VTEX, será necessário preencher no sistema Eccosys corretamente os dados de acesso fornecidos pela própria VTEX.

Acesse o menu:

1. Configurações > Integrações > Plataformas.
   
   

2. Clique no botão Incluir Plataforma.
   
   

3. O sistema exibirá uma lista com todas as plataformas disponíveis para integração.
   
   

4. Localize e clique sobre VTEX para iniciar a 

Preenchendo os dados de acesso

Na tela de configuração da integração com a VTEX, preencha os campos da aba Acesso com as informações abaixo:

• Nome:
   Defina um nome interno para identificar a integração. Exemplo sugerido: Integração VTEX.
  
  

• Status da Integração:
   Deixe como Ativa para que o Eccosys possa iniciar as sincronizações com a plataforma.
  
  

Dados de Acesso

• URL da Loja:
   Informe o endereço da sua loja na VTEX.
  
  

• Api Key:
   Informe a chave de acesso obtido na VTEX.
  
  

• Api Token:
   Informe o token obtido na VTEX.
  

💡 Importante: Certifique-se de preencher todos os campos corretamente antes de continuar. Dados incorretos podem impedir o funcionamento da integração.

Testar conexão

Após preencher os dados:

1. Clique no botão Testar conexão para validar se as credenciais estão corretas e o Eccosys consegue se comunicar com a loja.
   

⚠️ Caso o teste de conexão retorne erro, revise o token e os domínios preenchidos. Se o problema persistir, entre em contato com o suporte da VTEX ou da Eccosys para validação.

Caso sua integração com a VTEX seja na versão VTEX REST, preencha os seguintes campos:

• REST - Key (appkey)

• REST - Token (token)

• REST - URL Base (http://SEUDOMINIO.vtexcommercestable.com.br/api)

• SOAP - Usuário (appkey)

• SOAP - Senha (token)

• SOAP - WSDL URL (http://webservice-SEUDOMINIO.vtexcommerce.com.br/AdminWebService/Service.svc?singleWsdl)

⚙️ Aba Configurações 

Após concluir o preenchimento dos dados de acesso à plataforma de e-commerce, o sistema Eccosys disponibiliza uma estrutura padronizada de abas para gerenciamento da integração.

Entre elas, a aba Configurações é uma das mais importantes, pois centraliza os parâmetros que controlam o comportamento da sincronização entre o ERP e a plataforma VTEX, tanto em relação aos produtos quanto ao estoque e aos pedidos de venda.

Abaixo, explicamos cada campo disponível nessa aba:

Produto

• Importação de Produtos – Apenas Ativos
   Define se o Eccosys deve importar somente os produtos marcados como ativos na plataforma VTEX.
  
  
  

  • Sim: apenas produtos ativos serão sincronizados.
    
    

  • Não: todos os produtos serão importados, independentemente do status.
    
    

• Origem padrão de produtos importados da loja
   Define a origem fiscal padrão (nacional/importado) a ser atribuída aos produtos que vierem da VTEX. Útil para emissão de notas fiscais.
  
  

• Enviar imagens
   Determina se as imagens dos produtos cadastradas no Eccosys devem ser enviadas para a plataforma.
  
  
  

  • Sim: as imagens do ERP serão sincronizadas com a VTEX.
    
    

  • Não: nenhuma imagem será enviada.
    
    

• Utilizar nome da Imagem
   Permite enviar para a plataforma o nome do arquivo de imagem cadastrado no produto, o que pode ser útil para estratégias de SEO. Quando ativado, o nome original da imagem será mantido no envio.
  
  

• Lista de preço da Plataforma
   Permite vincular uma lista de preço específica do Eccosys à integração, para envio de valores personalizados.
  
  
  

  • Nenhuma: utiliza os preços padrão dos produtos.
    
    

Estoque

• Regra de Mapeamento de depósito
   Permite definir como os saldos de estoque serão enviados à VTEX, caso você utilize múltiplos depósitos no Eccosys.

• Tipo de estoque a Enviar o saldo
   Define qual tipo de saldo será enviado à plataforma: estoque físico (total armazenado) ou estoque disponível (físico menos reservas de pedidos).
  
  

• Regra de Envio de Estoque
   Define de que forma o estoque será enviado à plataforma Vtex:
  
  

• Enviar Estoque do Depósito Padrão da Plataforma
   Envia apenas o saldo de estoque do depósito definido como padrão no cadastro da plataforma.
  
  

• Enviar Estoque Consolidado de Todos os Depósitos
   Soma o estoque disponível em todos os depósitos cadastrados no ERP e envia o total para a Vtex.

• ID do Depósito Padrão na Plataforma
   Código do depósito padrão da Vtex.

O Eccosys trabalha com duas formas de identificação de estoque: o estoque físico e o estoque disponível. Por padrão, as atualizações de estoque na plataforma são baseadas no estoque disponível, que é calculado pela diferença entre o estoque físico e as reservas feitas por pedidos.

A reserva de estoque no Eccosys ocorre sempre que um pedido é criado, independentemente de como ele é gerado. Ou seja, toda vez que um pedido é registrado, uma tarefa agendada chamada "Atualização de Estoque" é acionada, ajustando a quantidade do produto disponível para venda de acordo com as reservas.

A VTEX permite que a reserva aconteça na própria plataforma, caso esta configuração seja implementada o nosso time de suporte deve ser acionado para que a reserva não seja duplicada e os seus produtos não fiquem indisponíveis para venda!

Pedidos de Venda

• Enviar imagens do produto pai nas variações
   Define se a imagem do produto principal (pai) será replicada nas variações (filhas).
  
  

• Data de corte mínima para baixa de pedidos
   Permite definir uma data a partir da qual os pedidos passarão a ser sincronizados.
  
  

• Importar pedidos de vendas por situação
   Define qual status os pedidos precisam ter na Vtex para serem importados pelo Eccosys.
  
  
  

  • Exemplo: Pagos — apenas pedidos já pagos serão integrados.
    
    

• Regra de envio de status para a Plataforma
   Define quando o Eccosys deve comunicar à Vtex que o pedido foi processado.
  
  
  

  • Exemplo: Nota Fiscal Autorizada com Pedido Atendido — envia status somente após a emissão da NF-e e que o pedido permaneça com situação atendido.
    
    

• Regra de arredondamento de parcela
   Define se o valor residual do arredondamento será aplicado na primeira ou na última parcela da venda.
  
  

• Enviar XML para Pedidos Faturados
   Define se o Eccosys deve enviar automaticamente o XML da nota fiscal para a plataforma após o faturamento do pedido.
  
  

• Seller Numes
   É possível definir que apenas pedidos de alguns sellers (Vendedores) vão ser importados no Eccosys
  
  

• Incluir Anexos na Observação Interna
  Utilizado para importar anexos da Vtex para personalização de produto.
  
  

Com as configurações ajustadas conforme o fluxo da sua operação, clique em Salvar para aplicar as alterações.

💡 Essas regras impactam diretamente na qualidade e na confiabilidade da integração. Revise com atenção e, se tiver dúvidas, consulte o suporte antes de ativar a sincronização.

Atualmente as informações Código da Política Comercial InStore, Pedidos InStore, Dia de pagamento Walmart, Regra Walmart, Dia de pagamento Extra e Regra Extra não são enviadas/sincronizadas com a plataforma.

Aba Mapeamentos

A aba Mapeamentos permite configurar campos personalizados entre o Eccosys e a plataforma integrada, utilizados quando determinadas informações não são contempladas na comunicação padrão da integração.

Ela serve como um complemento, possibilitando que dados específicos — como NCM, descrições adicionais, canais de venda, entre outros — sejam alinhados corretamente entre os sistemas, conforme a estrutura e nomenclatura utilizadas na plataforma.

Aba Automações

A aba Automações permite ativar ou desativar tarefas automáticas específicas da integração entre o Eccosys e a plataforma Vtex. Essa flexibilidade é essencial para personalizar o comportamento da sincronização, de acordo com as necessidades operacionais de cada loja.

As automações ativadas serão executadas de forma recorrente, em intervalos definidos no menu Configurações > Outros > Tarefas Agendadas do sistema.

A seguir, veja a descrição de cada opção disponível:

Produto

• Criar/Atualizar Produtos
   Permite que o Eccosys crie ou atualize automaticamente os produtos na plataforma Vtex, com base nos dados do ERP.
  
  

• Sincronizar produtos
   Habilita a sincronização periódica do catálogo entre os sistemas.
  
  

• Importar produtos
   Autoriza o Eccosys a buscar os produtos cadastrados na Vtex e importar para a base do ERP.
  
  

• Definir produtos como estoque alterado
   Marca os produtos para que sejam considerados na rotina de envio de estoque.
  
  

• Definir produtos como alterados
   Força os produtos que foram atualizados no Eccosys (ex: alteração de nome, descrição, imagem, marca, etc.) a serem incluídos na fila de sincronização.
  
  

• Instalador Multiplataforma – Apenas catálogo/categorias/marcas
   Importa seletivamente as estruturas da plataforma, ideal para implantações controladas:
  
  
  

  • Catálogo: apenas produtos.
    
    

  • Categorias: apenas as categorias.
    
    

  • Marcas: apenas as marcas.
    
    

• Instalador Multiplataforma
   Executa a importação inicial completa da plataforma (catálogo, categorias, marcas e depósitos).
  
  

• Sincronizar produtos novos
   Inclui na rotina apenas produtos que ainda não foram enviados à plataforma.
  
  

• Sincronizar produtos inativos
   Habilita o envio de produtos inativos, atualizando a situação na plataforma.
  
  

• Atualização de Preços
   Permite que o Eccosys atualize automaticamente os preços dos produtos na Vtex.
  

Estoque

• Instalador Multiplataforma – Apenas depósitos
   Importa apenas os depósitos (centros de distribuição) cadastrados na plataforma.
  
  

• Enviar estoque para a plataforma
   Ativa o envio automático de saldos de estoque conforme as regras configuradas na aba anterior.
  

Vendas

• Enviar informação de entrega para Loja Virtual
   Habilita o envio de dados de rastreamento e status de entrega para a Vtex.

• Importar pedidos de venda
   Habilita a entrada automática de pedidos recebidos na Vtex conforme as regras configuradas na aba anterior.
  
  

• Sincronizar status dos pedidos de venda
   Permite que o Eccosys atualize o status dos pedidos com base no processamento interno (ex: faturado, enviado).
  

Como funciona a importação de depósito

Para que a sincronização de produtos funcione corretamente entre o Eccosys e a Vtex, os depósitos (centro de distribuição) devem ser criados com a mesma nomenclatura entre eccosys e Vtex. Após criados, deve-se programar a tarefa “Instalador apenas depósito” para que ela identifique os depósitos entre os ambientes e permita sua devida identificação nos pedidos de venda.

Recomendações de uso:

• É importante habilitar a automação de importação de depósitos na aba Automações da integração.
  
  

• Após a execução da tarefa e o mapeamento correto do depósito no Eccosys, a automação pode ser desabilitada novamente.

Como funciona a importação e envio de catálogo

A integração entre Eccosys e Vtex permite tanto a importação quanto a exportação do catálogo de produtos, mantendo as informações atualizadas e consistentes entre os dois sistemas.

Essas ações garantem que dados como nome, descrição, preço, imagens, categorias e estoque sejam sincronizados corretamente, seja para enviar do Eccosys para a Vtex ou para importar da Vtex para o ERP.

• Exportação de produtos:
   Permite enviar produtos cadastrados no Eccosys para a Vtex.
   Consulte o manual específico: Exportação de Catálogo nas Integrações de Plataforma
  
  

• Importação de produtos:
   Permite trazer para o Eccosys os produtos já existentes na Vtex.
   Consulte o manual específico: Importação de Catálogo nas Integrações de Plataforma
  
  

Ambas as rotinas podem ser executadas manualmente ou por meio das automações da integração.

Importação de pedidos

Para que os pedidos de venda sejam importados corretamente da plataforma Vtex para o Eccosys, é necessário que as transportadoras estejam previamente mapeadas.

Para instruções completas sobre criação e vínculo de transportadoras, consulte:

Manual de Cadastro e Vínculo de Transportadoras

Após essas configurações, a importação de pedidos no Eccosys varia conforme o tipo de integração com a plataforma VTEX:

Integração com VTEX REST: Para clientes que utilizam a integração com a VTEX REST, ao contratar o complemento de Webhook, a importação de pedidos ocorre em tempo real. Isso significa que, sempre que um pedido é gerado na plataforma VTEX, ele é automaticamente importado para o Eccosys, sem a necessidade de executar tarefas agendadas. Dessa forma, os pedidos são recebidos no Eccosys assim que são criados na VTEX, tornando o processo mais ágil e sem intervenções manuais. Sem o complemento de Webhook, a importação será feita por tarefa agendada, executada em intervalos periódicos. Os pedidos serão importados em lotes, conforme configuração da conta.

Integração com VTEX Padrão (versão anterior à REST): Para quem utiliza a integração com a versão padrão da VTEX, a importação é realizada por meio de uma tarefa agendada. Nesse caso, todos os pedidos disponíveis na plataforma são importados de forma massiva e automática. 

Também é possível realizar a importação manual, caso precise trazer pedidos pontualmente ou em situações específicas de contingência.

Para mais detalhes sobre como funciona o processo de importação de pedidos, acesse:
Importação de Pedidos de Venda nas Integrações de Plataforma

Envio de rastreamento para a plataforma

O envio das informações de rastreamento para a plataforma Vtex acontece de forma automática durante a sincronização do status dos pedidos, conforme configurado na aba Automações da integração.

Quando a automação “Sincronizar status dos pedidos de venda” está ativa, o Eccosys atualiza o status do pedido na plataforma com base no progresso da operação dentro do ERP.

Se houver um código de rastreamento retornado pela logística integrada e uma URL de rastreio configurada no vínculo da transportadora, essas informações também serão enviadas para a plataforma no momento da atualização de status.

Dessa forma, o consumidor final poderá acompanhar o andamento do pedido diretamente pela loja, com base nos dados transmitidos automaticamente pelo Eccosys.

Conclusão

A integração entre o Eccosys e a VTEX foi desenvolvida para garantir agilidade, controle e confiabilidade em todos os processos da sua operação — desde o cadastro de produtos até o envio do pedido ao cliente final.

Com a configuração correta e o uso das automações, é possível reduzir falhas manuais, manter os dados sempre sincronizados entre os sistemas e proporcionar uma experiência de compra fluida para o consumidor.

Em caso de dúvidas, nosso time de suporte está à disposição para auxiliar.