Como usar o validador
- No Excel ou no Google Sheets, selecione as células da sua tabela de frete, incluindo a linha de cabeçalho, e copie.
- Cole na caixa acima. Também dá para abrir um arquivo CSV ou TXT, com ponto e vírgula ou vírgula.
- Leia a lista: cada erro mostra a linha, a coluna, o que está errado e, quando dá, a sugestão.
- Use "Corrigir" para aplicar o que não muda o sentido da tabela e copie o resultado de volta para o modelo da VTEX.
O cabeçalho precisa ter os nomes do modelo oficial (ZipCodeStart, ZipCodeEnd, WeightStart e os demais). Se a sua tabela vem de uma transportadora com outros nomes de coluna, renomeie a primeira linha antes de colar.
O que o validador confere, e de onde vem cada regra
As regras vêm do modelo de frete descrito pela própria VTEX (shipping rate template, na central de ajuda). O validador separa o que a VTEX documenta, que aparece como erro, do que ela não documenta, que aparece como aviso:
- CEP: até 8 caracteres, só letras e números. Hífen, ponto e espaço são erro. Faixas numéricas vão de 0000000 a 99999999.
- Polígono: quando há PolygonName, o CEP inicial e o final precisam ser 0. CEP e polígono na mesma linha é erro.
- Prazo (TimeCost): formato DD.HH:MM:SS. Quatro dias e meio são 04.12:00:00.
- País (Country): código ISO de 3 letras em maiúsculas, como BRA.
- Peso e custos: números decimais; peso inicial maior que o final é erro.
- Tamanho: até 65.536 linhas por aba e 10 MB por arquivo.
- Avisos (não documentados pela VTEX): faixas que se sobrepõem, linhas repetidas, vírgula como separador decimal e zero à esquerda perdido no CEP.
As 12 colunas do modelo de frete
ZipCodeStarteZipCodeEnd: início e fim da faixa de CEP.PolygonName: nome do polígono de geolocalização, no lugar da faixa de CEP.WeightStarteWeightEnd: peso mínimo e máximo da faixa, na mesma unidade dos SKUs.AbsoluteMoneyCost: custo fixo do frete.PricePercent: adicional em percentual sobre o preço (10 = 10%), somado ao custo fixo.PriceByExtraWeight: adicional por peso total do pedido, somado ao custo fixo.MaxVolume: volume máximo, na unidade de volume dos SKUs.TimeCost: prazo de entrega em DD.HH:MM:SS.Country: país, com código ISO de 3 letras.MinimumValueInsurance: seguro adicional, somado ao frete só quando o adicional por preço é menor que esse valor.
Prazo em DD.HH:MM:SS
O prazo é dias, horas, minutos e segundos separados por ponto e dois-pontos: 04.12:00:00 é quatro dias e doze horas. Quando o prazo da transportadora vem em dias, a seção "Prazo em dias para o formato da VTEX" converte nos dois sentidos, e o botão "Corrigir" converte as células que trazem só o número de dias.
Os erros que mais travam o envio
- CEP copiado com hífen (01310-100). O modelo aceita só letras e números.
- Zero à esquerda apagado pelo Excel (01000000 vira 1000000), o que muda a faixa sem aviso.
- Prazo escrito como "4 dias" ou "4,5" em vez de 04.12:00:00.
- País em minúsculas ou por extenso ("Brasil") em vez de BRA.
- Linha de polígono com CEP preenchido.
A VTEX só avisa depois do envio: se a planilha tem erro, a descrição chega por e-mail. Validar antes poupa essa volta.
O que o validador não faz
- Não gera o arquivo .xls: a VTEX recebe o modelo oficial salvo como .xls ou .zip, e o resultado daqui é colado nele.
- Não sabe quais colunas a VTEX exige: a página oficial não diz. Ele avisa quando uma coluna do modelo não aparece.
- Não confere os valores contra o contrato com a transportadora.
- Não decide se uma sobreposição de faixas é intencional: só mostra onde ela está.
Sua loja também precisa captar contatos? Conheça a roleta de desconto para VTEX, com app oficial na VTEX App Store.
Perguntas frequentes sobre a planilha de frete da VTEX
O que é a planilha de frete da VTEX?
É o modelo em que você descreve o custo e o prazo de entrega por faixa de CEP e de peso: faixas de CEP ou polígono, peso, custo fixo e adicionais, volume, prazo e país. Você baixa o modelo na criação da política de frete, preenche e envia de volta.
Onde baixo o modelo oficial da VTEX?
No Admin, em Shipping > Shipping strategy > Shipping policies. Ao criar uma política (Create shipping policy) ou editar uma existente, a seção Upload shipping rates tem o botão para baixar o modelo da planilha.
Em que formato salvo a planilha?
Como .xls ou .zip, e o envio é feito na seção Upload shipping rates da política de frete.
Qual é o limite de linhas e de tamanho do arquivo?
Cada aba aceita até 65.536 linhas e o arquivo pode ter até 10 MB. Dá para usar várias abas, desde que cada uma fique dentro do limite. Se o arquivo ainda ficar grande, compacte em .zip; se mesmo assim passar, divida em dois arquivos e crie outra política de frete para o segundo.
Quantos caracteres o CEP aceita?
Até 8, só letras e números, sem caractere especial. Faixas numéricas vão de 0000000 a 99999999 e faixas só com letras, de AAAAAAAA a ZZZZZZZZ. A própria página da VTEX escreve o máximo alfabético com nove Z para um limite de 8 caracteres; confira com a sua transportadora.
Posso deixar o hífen no CEP?
Não. O CEP aceita só letras e números, então 01310-100 deve virar 01310100. O botão "Corrigir" faz isso.
Por que o Excel apaga o zero à esquerda do CEP?
Porque ele trata a célula como número, e número não tem zero à esquerda: 01000000 vira 1000000. A faixa muda sem aviso. Formate a coluna como texto antes de colar, ou use a opção de completar o CEP com zeros à esquerda depois da validação.
Como preencher o prazo de entrega (TimeCost)?
No formato DD.HH:MM:SS: dias, horas, minutos e segundos. Quatro dias e meio são 04.12:00:00. O validador marca como erro qualquer outro formato e sugere a conversão quando a célula traz só o número de dias.
Como converto dias em DD.HH:MM:SS?
A parte inteira são os dias e a fração vira horas: 0,5 dia são 12 horas. Por isso 4,5 dias são 04.12:00:00 e 1,25 dia é 01.06:00:00. A seção de prazo da ferramenta converte nos dois sentidos.
O que é o PolygonName e quando usar?
É o identificador de um polígono da função de geolocalização da VTEX, usado no lugar da faixa de CEP. Preencha o PolygonName apenas quando não usar CEP.
O que coloco no CEP quando a linha usa polígono?
CEP inicial e CEP final iguais a 0. O validador marca como erro a linha com polígono e CEP diferente de 0 e sugere o 0.
Qual é a unidade do peso e do volume?
A mesma usada no cadastro dos SKUs. O peso (WeightStart e WeightEnd) e o adicional por peso (PriceByExtraWeight) usam a unidade do peso do SKU, como grama ou quilo; o volume (MaxVolume) usa a unidade de volume do SKU, como cm³ quando as dimensões estão em centímetros.
Como funcionam o custo fixo e os adicionais?
O AbsoluteMoneyCost é o custo fixo. O PricePercent (percentual sobre o preço) e o PriceByExtraWeight (adicional por peso total do pedido) são somados a ele.
Para que serve o MinimumValueInsurance?
É um valor de seguro adicional, somado ao custo do frete, e só vale quando o adicional por preço é menor que esse valor mínimo.
Como informar o país?
Com o código ISO de 3 letras em maiúsculas, como BRA para Brasil. "Brasil" ou "br" não valem. O botão "Corrigir" passa para maiúsculas quando são 3 letras.
O que acontece se a planilha tiver erro?
A VTEX envia um e-mail descrevendo o erro depois do envio, e a confirmação pode demorar conforme o volume de dados. Validar antes evita a volta.
A VTEX aceita faixas de CEP que se sobrepõem?
A página oficial não diz. O validador mostra como aviso as linhas do mesmo país cujas faixas de CEP e de peso se cruzam, para você confirmar se é intencional. Faixas que só se tocam no peso (de 0 a 1 e de 1 a 2) não são marcadas.
A VTEX aceita vírgula ou ponto como separador decimal?
A página oficial pede números decimais e não especifica o separador. O validador avisa quando encontra vírgula decimal; confira como o modelo baixado grava os decimais. O botão "Corrigir" troca vírgula por ponto, então revise o resultado.
Quais colunas são obrigatórias?
A página da VTEX não marca colunas como obrigatórias ou opcionais. O validador avisa quando uma coluna do modelo não aparece e só trata como erro o que a documentação descreve.
Posso colar uma tabela da Jadlog, dos Correios ou de outra transportadora?
Pode, desde que o cabeçalho use os nomes do modelo da VTEX (ZipCodeStart, ZipCodeEnd, WeightStart e os demais). Se a tabela da transportadora tem outros nomes de coluna, renomeie a primeira linha. A ferramenta confere o formato, não o conteúdo do contrato.
A ferramenta gera o arquivo .xls para enviar à VTEX?
Não. Ela entrega o texto corrigido, que você cola no modelo oficial baixado da VTEX e salva como .xls ou .zip. Também dá para baixar um CSV com ponto e vírgula.
Posso usar a ferramenta com planilhas de outros países?
Sim. O modelo da VTEX aceita CEP de até 8 caracteres com letras e números e a coluna Country com o código de 3 letras, então as regras valem para qualquer país. Para México, Colômbia, Argentina, Chile ou Peru, use MEX, COL, ARG, CHL ou PER.
Os dados da minha planilha são enviados a algum servidor?
Não. A leitura e a validação acontecem no seu navegador. Nada é enviado nem guardado pela ferramenta.
Outras ferramentas para lojas virtuais
No navegador, sem enviar nada, você também pode:
- gerar uma etiqueta dos Correios com código de barras
- redimensionar as fotos de produto para o tamanho da sua loja
- gerar códigos de barras EAN-13 e UPC-A
Outras ferramentas gratuitas
Todas rodam no navegador, sem cadastro e sem enviar os seus arquivos:
- Gerador de Link do WhatsApp: Crie links wa.me com mensagem pré-preenchida e use no site, no Instagram ou em anúncios.
- Gerador de QR Code: Crie QR Codes para links, WhatsApp, Instagram, Google Reviews, contatos e outros destinos.
- Calculadora de prêmios para roleta: Descubra quais prêmios colocar na sua roleta de desconto, a partir do segmento, do ticket médio e do objetivo.
- Redimensionar imagem: Redimensione imagens por pixels ou porcentagem, corte, ajuste a qualidade e baixe várias de uma vez em ZIP.
- Converter imagem: Converta imagens entre JPG, PNG e WebP sem mudar o tamanho em pixels, com qualidade ajustável e download em ZIP.
- Imagem para PDF: Junte uma ou várias imagens em um único PDF, uma por página, na ordem que você escolher.
- Etiqueta dos Correios: Gere etiquetas de endereçamento em PDF, várias de uma vez, com o CEP em código de barras. Só no navegador.