A VTEX é a plataforma mais usada por médias e grandes operações de varejo no Brasil. A integração com o ShopIA é feita via API oficial, sem necessidade de instalação de aplicativo na sua conta.
A conexão com VTEX opera no nível api_only. O ShopIA consome os endpoints REST oficiais e recebe webhooks nativos para os eventos principais. Caso utilize VTEX IO, recursos adicionais podem ser habilitados em fase posterior.
Pré-requisitos
- Conta VTEX com perfil de administrador
- Permissão para criar App Key e App Token em Configurações da conta > Chaves de aplicação
- Account name da loja (ex:
minhalojaemminhaloja.vtexcommercestable.com.br)
Como gerar as credenciais
1. Criar a chave de aplicação na VTEX
No admin VTEX:
- Acesse Configurações da conta > Chaves de aplicação.
- Clique em Gerenciar minhas chaves.
- Crie uma nova chave com nome ShopIA (sugerimos esse nome para facilitar identificação futura).
- Copie o App Key e o App Token exibidos. O App Token só aparece uma vez — guarde com segurança.
2. Atribuir os papéis necessários
A chave precisa ter permissão para os seguintes recursos:
- Leitura de pedidos (Orders)
- Leitura de clientes (Master Data)
- Leitura de produtos (Catalog)
- Gestão de webhooks
Acesse Configurações da conta > Gerenciamento de acessos > Papéis, edite o papel associado à sua chave e marque os recursos acima.
3. Conectar no ShopIA
No painel do ShopIA, acesse Configurações > Plataforma:
- Selecione VTEX.
- Informe o account name da sua loja.
- Cole o App Key e o App Token.
- Clique em Validar e conectar.
O sistema executa um teste imediato. Caso as credenciais estejam corretas, a sincronização inicial começa em segundo plano.
Tempo de sincronização
A VTEX costuma operar com volume superior às demais plataformas. Considere os seguintes prazos:
- Lojas com até 5.000 pedidos: 15 a 30 minutos
- Lojas com 5.000 a 50.000 pedidos: 1 a 3 horas
- Lojas com mais de 50.000 pedidos: até 6 horas (sincronização paginada noturna)
Acompanhe o progresso em Painel > Estado da sincronização.
Particularidades da VTEX
Master Data v2
O ShopIA consulta os dados de cliente no Master Data v2 (CL entity). Caso sua loja utilize entidades customizadas para clientes, entre em contato com o suporte para mapeamento adicional.
Múltiplas contas (multi-account)
Cada conta VTEX representa uma loja no ShopIA. Se você opera duas marcas em contas separadas, conecte cada uma como loja distinta no painel.
Webhooks nativos
A VTEX envia webhooks via Hook System. O ShopIA registra os hooks automaticamente após a primeira conexão bem-sucedida. Não é necessário configurá-los manualmente.
Validação pós-conexão
Após o término da sincronização, recomenda-se verificar:
- Total de pedidos importados em Pedidos vs total na VTEX (mesmo recorte de data)
- Total de clientes em Clientes
- Catálogo de produtos em Produtos
Pequenas divergências podem ocorrer em pedidos cancelados ou em status não importáveis. Diferenças superiores a 5% indicam problema de configuração — abra um chamado no suporte.
Limitações conhecidas
- Recuperação de carrinho exige integração adicional. A VTEX nativamente não expõe carrinhos abandonados via webhook. Recursos de cart capture estarão no roadmap Tier 2.
- Cupons gerados pelo ShopIA precisam ser configurados no admin da VTEX para ativação automática.
- Atualizações de produto em massa (importação CSV) podem demorar mais para aparecer no ShopIA do que pedidos transacionais.