Como Integrar Envia.com no VTEX: Tutorial Enterprise (2026)

VTEX é a plataforma enterprise de e-commerce mais usada na América Latina — Carrefour, Whirlpool, Vivo, Riachuelo rodam VTEX. Para lojas desse porte, configurar logística multi-transportadora é trabalho técnico complexo. A Envia.com oferece uma das integrações mais maduras com VTEX no mercado, mas requer setup cuidadoso por VTEX IO + Master Data + Shipping Strategy.

Este tutorial é para equipes técnicas (DevOps, integradores VTEX, in-house engineers). Se vc é loja média/pequena, considere começar com Shopify + Envia que tem fricção menor.

⚠️ Disclosure: o frete.center é afiliado da Envia.com. Integração VTEX é processo enterprise — recomendamos parceria com integrador VTEX certificado.

Índice

1. Pré-requisitos
2. Arquitetura da integração
3. Passo 1 — Conta Envia + API key
4. Passo 2 — Configurar Shipping Strategy no VTEX Admin
5. Passo 3 — Cadastrar Envia como Carrier
6. Passo 4 — Mapear Master Data e SKUs
7. Passo 5 — Testar em ambiente staging
8. Erros comuns e troubleshooting
9. FAQ

Pré-requisitos

Antes de começar:

• Conta VTEX ativa com permissões de admin no Catálogo, Master Data e Shipping
• Acesso VTEX IO (CLI configurado se vc for fazer customização)
• Conta Envia.com ativa (cadastro grátis)
• API Key da Envia (gerada em Configurações → API no painel Envia)
• Lista de SKUs com peso e dimensões corretos (críticos pra cotação)
• Tabela de coleta — endereço de origem dos pacotes (DC ou loja física)

Arquitetura da integração

O fluxo VTEX + Envia funciona assim:

Cliente no checkout
       ↓
VTEX Shipping Strategy faz cotação
       ↓
VTEX consulta API Envia (REST POST)
       ↓
Envia retorna preço/prazo de cada transportadora
       ↓
VTEX filtra/prioriza e mostra ao cliente
       ↓
Cliente escolhe → pedido confirmado
       ↓
Webhook VTEX → Envia recebe ordem
       ↓
Envia gera etiqueta → status volta pro pedido VTEX

Componentes envolvidos:

• VTEX Master Data: entidade de produto (peso, dimensões)


• VTEX Logistics: Carriers, Docks, Polygons (regiões)


• VTEX Shipping Strategy: regras de qual carrier mostrar


• VTEX OMS: estado do pedido + fulfillment

Passo 1 — Conta Envia + API key

1. Cadastre-se grátis na Envia.com.
2. Configure o endereço de coleta principal.
3. Gere API Key em Configurações → API → Generate new key.
4. Importante: anote a API Key em local seguro. Para VTEX, vamos usar essa key no Shipping Strategy.

Passo 2 — Configurar Shipping Strategy

1. No VTEX Admin: Configurações → Logística → Shipping Strategy.
2. Crie uma nova estratégia chamada "Envia.com".
3. Tipo: External (API).
4. Endpoint: https://api.envia.com/ship/rate/.
5. Authentication: API Key (header Authorization: Bearer {sua-api-key}).
6. Salve.

Para detalhes específicos do payload esperado, consulte a documentação oficial da API Envia.

Passo 3 — Cadastrar Envia como Carrier

No VTEX, cada transportadora ativa via Envia precisa ser cadastrada como Carrier separado:

1. Logística → Carriers → Add new.
2. Para cada transportadora desejada (Correios PAC, Correios SEDEX, Jadlog Package, etc.), crie um Carrier com:

1. Importante: vincule cada Carrier à Shipping Strategy "Envia.com" criada no passo 2.

Veja o detalhe de cada transportadora em Envia.com — transportadoras integradas.

Passo 4 — Mapear Master Data e SKUs

A cotação correta depende de peso e dimensões dos SKUs:

1. Catalog → SKU → cada produto:

1. Sem isso, a cotação Envia falha ou retorna preço/prazo errado.

1. Para volumes altos, considere automatizar via Master Data Schema com integração ao seu ERP.

Passo 5 — Testar em ambiente staging

VTEX permite ambiente "myaccount" + workspace para testar:

1. Crie um workspace feature-envia.
2. Configure a Shipping Strategy nesse workspace.
3. Faça checkout teste em janela anônima (use seu domínio staging VTEX).
4. Confira:

1. Se tudo funcionou, promova o workspace para Master.

Erros comuns e troubleshooting

1. "Shipping rate not available" no checkout.
Causa: SKU sem peso ou dimensões. Solução: revise Master Data.

2. Preço diferente do esperado.
Causa: peso cubado. Pacote leve mas grande paga por volume. Use calculadora para validar.

3. Webhook Envia não recebe pedido.
Causa: VTEX OMS webhook desconfigurado. Solução: Logística → Webhooks → Resync e verificar URL endpoint Envia.

4. Múltiplas SKUs no carrinho geram cotação separada para cada.
Solução: configurar shipping consolidation no VTEX para agrupar SKUs em uma única encomenda.

5. Cliente em zona rural não recebe.
Solução: garantir que Correios está ativo via Envia para esses CEPs — Loggi/Jadlog/J&T têm cobertura limitada fora de RM.

FAQ

A integração Envia + VTEX é gratuita?
Sim, sem mensalidade. Vc paga só as etiquetas que comprar.

Posso ter Envia.com + Mercado Envios + outras transportadoras simultâneas?
Sim. VTEX suporta múltiplas Shipping Strategies em paralelo.

Funciona com VTEX Marketplace?
A cotação Envia funciona para SKUs próprios e SKUs de marketplace, desde que Master Data esteja correto pra todos.

E se eu tiver multi-store ou multi-país no VTEX?
Cada store precisa de sua configuração Envia (origem diferente = coleta diferente). Para multi-país, usar versão Envia do país de origem.

Vale fazer integração custom ou usar o app pronto?
Para até ~10.000 pedidos/mês, app pronto basta. Acima, considere custom via VTEX IO para regras finas (ex: priorizar transportadora por região, frete grátis condicional).

Veja também:

• VTEX + Envia.com — detalhes da integração


• Envia.com no Brasil


• Como escolher transportadora para e-commerce

Cadastrar grátis na Envia.com →