Vtex
A integração com o Vtex conecta a sua conta ao idworks e sincroniza os fluxos correspondentes ao canal — credenciais, regras de sincronização de produtos, importação de pedidos, conciliação financeira e demais ações específicas dele. A configuração reúne 55 parâmetros distribuídos em 5 grupo(s).
Antes de configurar, ative a integração em Configurações → Integrações (aba Integrações Disponíveis), preencha o nome interno e (quando o tipo exigir) passe pelo fluxo de autenticação. A partir daí, os parâmetros abaixo ficam disponíveis na Configuração (ícone de engrenagem) da integração.
Categoria no catálogo do idworks: Canal de Venda.
Índice
Conceito
Cadastro e autenticação
Parâmetros por grupo
- Credenciais de Acesso
- Integração de Vendas
- Integração de Produtos
- Importação de Anúncios
- Importação de Produtos
Pedidos
Erros mais comuns
- "Sku can not be created because the RefId is registered..."
- "SKU não encontrado para a referência ..."
- "Necessário preencher o código do produto no anúncio para baixar cadastro"
Referência rápida
O que é a integração Vtex?
É a conexão entre o canal Vtex e o idworks. Ela controla como dados fluem entre os dois sistemas — depende do tipo da integração (a categoria neste caso é Canal de Venda), mas em geral cobre uma combinação de credenciais, regras de sincronização, gatilhos automáticos e parâmetros de conciliação.
📍 Onde: menu lateral → Configurações → Integrações → aba Integrações Disponíveis → Vtex.
Como ativar a integração?
- Acesse Configurações → Integrações.
- Na aba Integrações Disponíveis, busque por Vtex e clique no botão +.
- Preencha:
- Conta (apenas multi-conta) — empresa dona da integração.
- Nome da Integração — texto livre. Útil para distinguir várias instâncias do mesmo tipo.
- Clique em Salvar.
A integração aparece imediatamente em Minhas Integrações. Dependendo do tipo, o status inicial é Ativo (quando só requer credencial fixa) ou Não Autenticado (quando depende de autenticação externa).
Pré-requisito: privilégio Criar parametrizações empresa.
Como autenticar e validar as credenciais?
Preencha o grupo Credenciais de Acesso (ver tabela abaixo). Quando a integração pede uma autorização externa (o canal abre a tela de login dele para você liberar o acesso), clique em Autenticar Integração na linha da integração (ícone de cadeado) — uma nova aba abre o login do canal e, ao confirmar, a conexão fica liberada. Para integrações com credencial fixa (usuário/senha/chave), basta preencher os campos e salvar.
Depois de salvar, use a ação Validar credenciais (quando disponível) para confirmar que o canal responde. O status na listagem reflete o resultado: Ativo = OK, Erro = credencial inválida ou revogada, Não Autenticado = falta concluir o fluxo de autorização.
Pré-requisito: privilégio Editar parametrizações empresa.
Credenciais de Acesso
4 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| AccountName (nome da conta) | Texto | Subdomínio para acessar a Vtex |
| AppKey | Senha | (sem descrição cadastrada) |
| AppToken | Senha | (sem descrição cadastrada) |
| Validar credenciais | Botão | Clique para validar as credenciais informadas |
Integração de Vendas
19 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Valor vale compras | Sim/Não | Ative se quiser deixar zerado o valor do vale compras no pedido |
| Mudar Status "em manuseio" | Sim/Não | Ative se quiser mudar o status do pedido para "em manuseio" após a importação |
| Descriptografar email | Sim/Não | Descriptografar o email ao baixar pedido da vtex |
| Empresa Faturadora | Lista | Empresa responsável pelo faturamento dos pedidos, caso seja diferente da principal. |
| Excluir valor frete na NF para PF | Sim/Não | Ative se quiser excluir o valor do frete na Nota Fiscal quando a venda por para pessoa física (PF) |
| Importar pedidos | Sim/Não | Ative se quiser que a idworks integre os pedidos feitos no canal de vendas. |
| Status para importar pedidos | Lista múltipla | Status da Vtex em que o pedido é importado: Pagamento aprovado (payment-approved), Pronto para o manuseio (ready-for-handling) e Preparando entrega (handling). Pedido em outro status só é importado quando passar para um status marcado. Para não importar pedidos em Pagamento aprovado, marque só Pronto para o manuseio e Preparando entrega. Em branco, a notificação (webhook) da Vtex importa o pedido nos três status e a consulta periódica de pedidos busca só os que estão em Pronto para o manuseio. |
| Cancelar pedido automaticamente | Sim/Não | Ative se quiser cancelar pedido automaticamente caso ele seja cancelado no canal de vendas |
| Enviar faturamento parcial | Sim/Não | Ative se quiser enviar faturamento parcial |
| Enviar a URL do PDF no faturamento | Sim/Não | Ative se quiser enviar a URL do arquivo PDF para a Vtex ao invés da URL do arquivo XML |
| Considerar o preço lista como desconto | Sim/Não | Ao ativar, será considerado a diferença entre o preço lista e o preço de venda para calcular o valor do desconto. Caso contrário, será utilizado o preço base e o preço de venda |
| Considerar valor do pedido no valor da fatura (NF) | Sim/Não | Ao ativar, será considerado o valor do pedido, ao invés do valor do pagamento nos campos de valor da fatura e duplicata ao emitir a nota fiscal |
| Empresa Faturadora dentro estado PF | Lista | Empresa responsável pelo faturamento dos pedidos para pessoa física dentro do estado de origem |
| Empresa Faturadora fora estado PF | Lista | Empresa responsável pelo faturamento dos pedidos para pessoa física fora do estado de origem |
| Criar TAG pedido campo observações | Texto | Caso a palavra digitava seja encontrada dentro do campo observações do pedido (tag OpenTextField), será criada uma TAG no pedido dentro da idworks com o mesmo nome |
| Enviar dados NF quando for declaração conteúdo | Sim/Não | Enviar nota fiscal fícticia no caso do pedido ter declaração de conteúdo |
| Fechar pedido automaticamente | Sim/Não | Quando marcado, o idworks fecha o pedido integrado do canal de vendas através do hub. Se desmarcado, o pedido quando integrado permanece com o status de aberto para atualização manual. |
| Campo tag marketing VTEX | Texto | Nome da tag de marketing da VTEX que será lida em "marketingData.marketingTags" para preencher o campo observações do pedido. Exemplo: prescritor |
| Habilitar geração automática de transferência entre CDs | Sim/Não | Ao habilitar, será gerada uma transferência automática entre CDs apenas quando não houver atendimento integral do pedido por um único CD. |
Integração de Produtos
21 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Estoque de segurança | Inteiro | Se a quantidade de um produto estiver abaixo do valor escolhido, seu anúncio será pausado para evitar que sejam feitas vendas sem estoque. O valor de estoque mínimo é aplicado a todos os produtos. |
| Atualizar saldo estoque | Sim/Não | Ative se quiser que a idworks atualize o saldo de estoque na integração. |
| Atualizar marca | Sim/Não | Ative se quiser enviar atualização de marca na integração |
| Atualizar categoria | Sim/Não | Ative se quiser enviar a atualização de categoria na integração |
| Atualizar imagem | Sim/Não | Ative se quiser enviar a atualização de imagem na integração |
| Atualizar kit | Sim/Não | Ative se quiser atualizar kit na integração |
| Atualizar preço | Sim/Não | Ative se quiser enviar a atualização de preço na integração |
| Atualizar produto | Sim/Não | Ative se quiser enviar a atualização de produto na integração |
| Atualizar categoria similar | Sim/Não | Ative se quiser enviar a atualização de categoria similar na integração |
| Atualizar especificações | Sim/Não | Ative se quiser enviar a atualização de especificações na integração |
| Atualizar SKU | Sim/Não | Ative se quiser enviar a atualização de SKU na integração |
| Usar ID ERP | Sim/Não | Utilizar o ID do ERP ao criar novos produtos e SKUs |
| Arredondamento dos centavos do preço | Decimal | Valor em centavos para arredondar o preço de venda. Preencha entre 0,01 e 0,99. |
| Baixar cadastro produto | Sim/Não | Ative se quiser baixar o cadastro do produto na integração |
| Incluir palavras chaves substitutas geradas | Sim/Não | Ative se quiser incluir palavras chaves substitutas geradas automaticamente para erro de digitação |
| Incluir código de barras nas palavras substitutas | Sim/Não | Ative se quiser incluir código de barras nas palavras substitutas |
| Incluir código de referencia palavras substitutas | Sim/Não | Ative se quiser incluir código de referencia nas palavras substitutas |
| Utilizar título como nome SKU | Sim/Não | Utilizar o campo título como nome do SKU ao enviar para o canal |
| Armazéns para somar quantidade | Lista múltipla | Selecionar os armazéns que deve somar a quantidade para enviar aos canais de venda. Caso não seja preenchido, será enviado a quantidade do armazém que esta no de/para |
| Percentual disponibilidade de estoque | % | Valor base para utilizar do estoque em percentual. Ex. se tiver 100 unidades disponíveis e o percentual for 80% será enviado 80 para o canal |
| Política comercial preço base | Lista | Defina qual será a política comercial a ser utilizada para enviar o preço base para a plataforma. Serão utilizados valores da lista de de/para de política comercial. |
Importação de Anúncios
10 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Incluir Preços na ficha do Anúncio | Sim/Não | Traz o preço do anúncio publicado para dentro da ficha do anúncio no sistema. Caso não habilite, será utilizado preço definido pela política comercial do cadastro do produto no momento da sincronização do anúncio. |
| Incluir URL do Video no Cadastro do Produto | Sim/Não | Traz a URL do vídeo do anúncio publicado para dentro da ficha de cadastro do produto, somente nos casos em que for possível realizar o vínculo (match) entre o anúncio, suas variações e os produtos/SKUs cadastrados no sistema. |
| Incluir Título na ficha do Anúncio | Sim/Não | Traz o título do anúncio publicado para dentro da ficha do anúncio no sistema. Caso não habilite, será utilizado o campo Nome do cadastro do produto no momento da sincronização do anúncio. |
| Incluir Descrição na Ficha do Anúncio. | Sim/Não | Traz o descrição do anúncio publicado para dentro da ficha do anúncio no sistema. Caso não habilite, será utilizado o campo Descrição do cadastro do produto no momento da sincronização do anúncio. |
| **Importar somente anúncios inexistente dentro da ** | Sim/Não | Só importa anúncios que ainda não estão cadastrados no sistema. |
| Incluir Imagem dentro do Produto | Sim/Não | Traz as imagens do anúncio publicado para dentro do cadastro do produto no sistema. Caso a opção de trazer imagens para dentro do anúncio esteja habilitada, esta funcionalidade será desconsiderada. |
| Incluir Imagem dentro do Anúncio | Sim/Não | Traz as imagens do anúncio publicado para dentro da ficha do anúncio no sistema. Caso não habilite, serão utilizadas as imagens vinculadas ao cadastro do produto no momento da sincronização do anúncio e das imagens. |
| Não Realizar o vínculo do Anúncio ao Produto/SKU | Sim/Não | Ignora o vínculo automático do anúncio com o produto/SKU, permitindo que o vínculo seja realizado posteriormente. |
| Criar Produto/SKU, com base no Anúncio Importado. | Sim/Não | Cria o Produto/SKU com base no anúncio importado. O sistema utilizará o código SKU presente no canal para criar produtos únicos dentro do sistema. Durante a importação, ele percorrerá todos os anúncios: se, no primeiro anúncio, o código SKU da variação estiver em branco, o sistema criará um SKU automaticamente; no entanto, se os demais anúncios também estiverem com o SKU em branco, existe o risco de o sistema vincular diversos anúncios de forma incorreta a um mesmo SKU. Da mesma forma, se diferentes anúncios estiverem com o mesmo código SKU, mas representarem SKUs fisicamente distintos, também haverá risco de criação e associação equivocadas. O sistema criará os cadastros sempre como Tipo Produto e Tipo SKU. Caso algum dos anúncios importados represente um Kit, será necessário editar manualmente o item após a importação, alterando seu tipo para Kit e definindo sua composição corretamente. Por isso, é fundamental utilizar esta parametrização com bastante atenção, garantindo que os SKU |
| Criar Produto ou SKU Único (Todos Anúncios terá um produto único associado) | Sim/Não | Diferente da opção Criar Produto/SKU com base no Anúncio Importado, esta configuração faz com que o sistema crie um produto único para cada anúncio importado. Nesse caso, o código será utilizado como código do produto, enquanto o código da variação será utilizado para o cadastro do SKU correspondente. O sistema criará os cadastros sempre como Tipo Produto e Tipo SKU. Caso algum dos anúncios importados represente um Kit, será necessário editar manualmente o item após a importação, alterando seu tipo para Kit e definindo sua composição corretamente. |
Importação de Produtos
1 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Incluir Imagens | Sim/Não | Importar imagem para os produtos e SKUs |
Como fica o pedido com entrega no exterior?
Quando o pedido da VTEX tem endereço de entrega em outro país, o idworks guarda o país junto com o endereço. A VTEX informa o país com um código de 3 letras (por exemplo, BRA para Brasil e USA para Estados Unidos). Qualquer código diferente de BRA é tratado como exterior.
No pedido com entrega no exterior:
- O idworks não aplica ao CEP e ao estado a limpeza de padrão brasileiro (manter só números no CEP, tirar o prefixo "BR-" do estado). No endereço do cliente, o estado é gravado em letras maiúsculas.
- Ao criar o endereço do cliente, o idworks não consulta o código IBGE da cidade pelo CEP, como faz com endereço no Brasil.
Se o país que veio da VTEX não estiver cadastrado no idworks, a importação do pedido para com a mensagem "País 'CÓDIGO' do endereço de entrega não cadastrado" (seguida de uma referência técnica entre parênteses), onde CÓDIGO é o código de 3 letras do país. Nesse caso, abra um chamado com o suporte informando o código que aparece na mensagem.
Esse tratamento de país vale para pedidos da VTEX. Pedido com país BRA (ou sem país informado) segue as regras de endereço brasileiro de sempre.
"Sku can not be created because the RefId is registered..."
Mensagem "Sku can not be created because the RefId is registered in Sku id NÚMERO". O idworks tentou criar um SKU novo na VTEX usando um código de referência que já está em uso por outro SKU na conta VTEX. A VTEX exige código de referência único por loja — não permite dois SKUs diferentes com o mesmo código.
A mensagem informa qual SKU da VTEX está ocupando aquele código (o número no final, Sku id), o que ajuda a identificar o conflito.
As causas mais comuns:
- Migração de um sistema antigo para o idworks com códigos repetidos no caminho — o cadastro antigo já mandou aquele código para a VTEX e o idworks tenta de novo achando que é novo.
- Duplicidade no catálogo idworks — dois SKUs locais com o mesmo Código de referência (não tem proteção forte contra duplicidade em todos os fluxos de cadastro).
- SKU criado direto na VTEX com o mesmo código que você está tentando usar.
Como resolver:
- Anote o número de SKU da VTEX que veio na mensagem (a parte "Sku id N").
- Entre no painel da VTEX → Catálogo → SKUs → busque por esse número. Veja qual é o produto e o código de referência ocupado.
- Decida o caminho:
- O SKU local que está tentando subir é o "certo" — apague o SKU duplicado direto na VTEX, ou troque o código de referência dele lá, antes de sincronizar de novo.
- O SKU da VTEX é o correto e o vínculo se perdeu — em Integrações (HUB) → Anúncios, abra o anúncio (Editar), edite a variação e preencha o Código variação com o número do SKU da VTEX que veio na mensagem; salve. Com o código preenchido, o idworks atualiza o SKU que já existe na VTEX em vez de tentar criar um novo.
- Foi duplicidade no idworks — em Produtos → Listar Produtos, busque pelo código de referência repetido e mantenha só um SKU local; descarte ou corrija o outro.
- Refaça a sincronização.
Esse erro só aparece em VTEX porque a VTEX é especialmente rígida com código de referência. Em outros canais, código repetido geralmente atualiza o existente em vez de barrar.
"SKU não encontrado para a referência ..."
Mensagem "SKU não encontrado para a referência CÓDIGO" ou, quando são várias variações, "SKU não encontrado para as referências CÓDIGO1, CÓDIGO2". Aparece ao baixar o anúncio da VTEX para o idworks. Ela significa que o idworks não achou um SKU seu para a variação que veio da VTEX. O CÓDIGO é o código de referência que aquela variação tem na VTEX. Se a variação não tiver código de referência na VTEX, a mensagem sai sem o código; nesse caso, identifique a variação pelo vínculo do anúncio ou pelo código de barras (EAN).
Para cada variação do produto na VTEX, o idworks procura o SKU local nesta ordem:
- Um cadastro do idworks (SKU ou produto) cujo código seja igual ao código de referência da variação na VTEX.
- Se não achar, o SKU que já está vinculado àquela variação no anúncio.
- Se ainda não achar, um SKU com o mesmo código de barras (EAN) que a variação tem na VTEX, seja o código de barras principal ou um código de barras adicional do SKU. Se o EAN na VTEX tiver 12 dígitos, o idworks também tenta completar o dígito verificador final para chegar ao EAN de 13 dígitos.
Só as variações que não passam em nenhuma dessas três buscas entram na mensagem, todas juntas numa frase só. As outras variações encontradas são gravadas mesmo assim, mas a ação termina mostrando erro com essa mensagem. Variação que é kit na VTEX também não é baixada e gera o aviso "produto é kit". Se o download teve outros avisos, eles aparecem na mesma mensagem, separados por ponto e vírgula.
Como resolver (escolha um caminho para cada código da mensagem):
- No painel da VTEX → Catálogo → SKUs, busque o código de referência citado e veja a qual variação ele pertence.
- Deixe o código do SKU no idworks igual ao código de referência da VTEX (ou o contrário, ajustando o código de referência na VTEX); ou
- Em Integrações (HUB) → Anúncios, vincule essa variação do anúncio ao SKU certo do idworks; ou
- Cadastre no SKU do idworks o mesmo código de barras (EAN) que a variação tem na VTEX.
- Baixe o anúncio de novo.
"Necessário preencher o código do produto no anúncio para baixar cadastro"
Mensagem "Necessário preencher o código do produto no anúncio para baixar cadastro". A ação Baixar Anúncio (importar dados da VTEX para a ficha local do anúncio) exige que o vínculo do anúncio tenha o código do produto na VTEX preenchido. Sem o código que identifica o produto-pai na plataforma, o sistema não sabe qual produto baixar.
Aparece em anúncios vinculados manualmente em que só o código do SKU foi preenchido, mas o código do produto-pai ficou em branco — comum em integrações antigas migradas, em que o esquema de vínculo era diferente.
Como resolver:
- Em Integrações (HUB) → Anúncios, abra o anúncio VTEX afetado.
- Preencha o Código do Produto (a parte que identifica o produto-pai na VTEX, encontrável no painel VTEX em Catálogo → Produtos → editar produto → campo ID do Produto).
- Salve e tente baixar o anúncio de novo.
Privilégios da tela
Esta tela tem privilégios próprios que controlam o que cada usuário pode fazer. Configure os perfis de acesso em Configurações → Perfis de Acesso vinculando os privilégios abaixo aos grupos desejados. Quando o usuário não tem o privilégio, a ação correspondente fica desabilitada na tela.
| Privilégio | Libera |
|---|---|
| Visualizar integrações | Acesso à tela de Integrações e a esta página de configuração. |
| Criar parametrizações empresa | Ativar a integração (botão + no catálogo). |
| Editar parametrizações empresa | Abrir a Configuração (engrenagem), editar nome e status e validar credenciais. |
| Deletar parametrizações empresa | Excluir a integração. |