Integracao VTEX com ERP: SAP, TOTVS, Bling e APIs customizadas

A integracao entre VTEX e ERP e uma das etapas mais criticas de uma implantacao de e-commerce. Quando bem feita, a operacao flui automaticamente: pedidos caem no ERP, notas fiscais sao emitidas, estoque e atualizado em tempo real e o catalogo se mantem sincronizado. Quando mal feita, gera retrabalho manual, vendas de produtos sem estoque, divergencia de precos e atrasos no faturamento. Este guia cobre a arquitetura de integracao, os principais ERPs do mercado e as boas praticas para uma integracao robusta.

Arquitetura de integracao

A VTEX expoe APIs REST documentadas para todas as entidades do sistema: catalogo (produtos, SKUs, categorias, marcas), precos (tabelas de preco, precos fixos, promocoes), estoque (warehouses, inventory), pedidos (orders, feed, hook) e logistica (SLAs, docks, carriers). A integracao com ERP pode ser feita de tres formas. Direta: o ERP chama as APIs da VTEX e vice-versa. Via middleware: um servico intermediario (Node.js, Python, ou plataforma iPaaS) orquestra a comunicacao entre os dois sistemas. Via conector pronto: solucoes como Eccosys, HUB de Integracoes e conectores especificos que abstraem a complexidade. Para operacoes de grande porte, o middleware dedicado e a abordagem recomendada pois oferece controle total sobre transformacao de dados, retry em falhas e logs detalhados.

Integracao com SAP

SAP e o ERP mais comum em operacoes enterprise que rodam VTEX. A integracao tipica cobre: catalogo (SAP envia materiais, VTEX recebe como produtos/SKUs), precos (SAP envia tabelas de preco por condicao comercial), estoque (SAP atualiza disponibilidade via API de inventory), pedidos (VTEX envia pedidos faturados para SAP gerar nota fiscal) e devoluções (SAP notifica VTEX sobre status de reversa). O conector mais utilizado e via SAP Commerce Cloud Integration ou um middleware Node.js dedicado que traduz IDocs/BAPIs para chamadas REST na VTEX. Pontos de atencao: mapeamento de campos entre SAP e VTEX (codigos de material vs SKU IDs), tratamento de divergencia de estoque em alta concorrencia e fila de retry para chamadas que falham por timeout.

Integracao com TOTVS

TOTVS Protheus e amplamente usado por operacoes de medio porte no Brasil. A integracao com VTEX segue padroes similares ao SAP mas com APIs diferentes. O TOTVS disponibiliza web services SOAP e APIs REST (dependendo da versao) para catalogo, estoque, precos e pedidos. O fluxo tipico: TOTVS publica produtos via API de catalogo da VTEX, sincroniza estoque via API de inventory, recebe pedidos via feed ou webhook da VTEX e retorna NF-e com chave de acesso. Ferramentas como Eccosys e Bridge Hub oferecem conectores prontos TOTVS-VTEX que reduzem o tempo de implantacao de meses para semanas. Para operacoes que precisam de customizacao alem do conector padrao, um middleware Node.js com Fastify e a abordagem mais flexivel.

Integracao com Bling e Tiny

Bling e Tiny sao ERPs focados em e-commerce, populares entre operacoes de pequeno e medio porte. Ambos oferecem APIs REST bem documentadas e integracoes nativas com a VTEX via marketplace de apps. O Bling sincroniza catalogo, precos, estoque e pedidos com a VTEX atraves do app oficial ou via API direta. O Tiny funciona de forma similar com foco em automacao de NF-e e etiquetas de envio. Para essas integracoes, o setup e mais simples: instale o app no admin VTEX, configure as credenciais do ERP e mapeie os campos. Em poucos dias a integracao esta operacional. O ponto de atencao e volume: para operacoes com mais de 500 pedidos por dia, valide se o plano do ERP suporta o throughput necessario sem throttling.

Middleware: quando e como construir

Um middleware de integracao e recomendado quando: os sistemas nao se comunicam diretamente (formatos incompativeis), a operacao precisa de transformacao de dados complexa, existem regras de negocio que nao pertencem nem ao ERP nem a VTEX, ou o volume exige filas e retry automatico. A stack recomendada para middleware VTEX e: Node.js com Fastify para alta performance, filas com Redis ou SQS para processamento assincrono, logs estruturados com Pino para debugging, health checks e alertas para detectar falhas rapidamente. O middleware deve ser idempotente: processar a mesma mensagem duas vezes nao pode gerar duplicidade. Use IDs de correlacao para rastrear um pedido do inicio ao fim. Monitore latencia e taxa de erro. Um middleware saudavel processa mensagens em menos de 2 segundos e tem taxa de erro abaixo de 0.1%.

Sincronizacao de catalogo e precos

A sincronizacao de catalogo e a base de toda integracao. O ERP e o master de dados do produto: nome, descricao, atributos, peso, dimensoes. A VTEX e o sistema de apresentacao: imagens, SEO, categorias visuais. O fluxo tipico: ERP envia produto via API de Catalog da VTEX (POST /api/catalog/pvt/product), depois envia SKUs (POST /api/catalog/pvt/stockkeepingunit), depois precos (PUT /api/pricing/prices/sku-id), depois estoque (PUT /api/logistics/pvt/inventory/skus/sku-id/warehouses/warehouse-id). A sincronizacao pode ser por polling (periodica) ou por evento (webhook do ERP). Para catalogo, polling a cada 15-30 minutos e aceitavel. Para estoque em operacoes de alto volume, sincronizacao por evento ou polling a cada 1-2 minutos e necessaria para evitar overselling.

Fluxo de pedidos e NF-e

O fluxo de pedidos integrados segue: cliente compra na VTEX, pedido entra no OMS com status payment-approved, VTEX notifica o ERP via feed ou webhook, ERP processa o pedido (reserva estoque, gera NF-e), ERP retorna a NF-e para a VTEX via API de invoice (POST /api/oms/pvt/orders/order-id/invoice), VTEX atualiza o status para invoiced e envia email de confirmacao ao cliente. Para capturar pedidos, use o Order Feed ou o Order Hook da VTEX. O Feed e pull-based (voce consulta periodicamente), o Hook e push-based (VTEX envia para seu endpoint). O Hook e mais eficiente mas exige um endpoint sempre disponivel. Em ambos os casos, processe pedidos de forma assincrona com fila para nao perder eventos em picos de trafego.

Boas praticas e erros comuns

Sempre use autenticacao via appKey e appToken da VTEX. Nunca exponha credenciais no frontend. Implemente retry com backoff exponencial para chamadas que falham por timeout ou rate limit. A VTEX tem rate limits por endpoint; respeite os headers X-RateLimit. Valide dados antes de enviar: produtos sem imagem, SKUs sem preco ou estoque negativo causam erros silenciosos. Monitore a fila de integracao: pedidos parados ha mais de 30 minutos indicam problema. Crie alertas para divergencia de estoque entre ERP e VTEX. Documente o mapeamento de campos entre sistemas. Teste a integracao em ambiente de homologacao antes de producao. E o mais importante: planeje para falha. Sistemas caem, APIs ficam lentas, dados chegam incompletos. Uma integracao robusta trata todos esses cenarios sem intervencao manual.