Integração VTEX com o Datasul: como pedidos, estoque e notas fiscais circulam

27 de outubro de 2026Partners Consultoria

Quem vende numa loja VTEX e fatura no TOTVS Datasul precisa que as duas pontas conversem. O pedido feito na loja tem que chegar ao ERP, e o estoque e a nota fiscal têm que voltar para a loja.

Este artigo descreve esses fluxos, mostra como uma rotina Progress pode consumir as APIs da VTEX e aponta os controles que evitam pedidos perdidos ou duplicados.

Os fluxos de uma integração VTEX com o Datasul

Pedidos (VTEX → Datasul). O pedido aprovado na loja vira pedido de venda no Datasul, com cliente, itens, frete e condição de pagamento.
Estoque (Datasul → VTEX). O saldo do ERP é enviado para a loja, por SKU e por estoque (warehouse) da VTEX.
Preços (Datasul → VTEX), quando o preço de venda nasce no ERP.
Faturamento (Datasul → VTEX). Depois de autorizada a NF-e, a loja recebe os dados da nota e o pedido avança para faturado.
Rastreio (Datasul → VTEX). O código de rastreio e a transportadora, para que a loja informe o comprador.

O cadastro de produtos e de clientes também pode entrar no escopo. A VTEX mantém um guia de integração com ERP que cobre produtos, preços, estoque e clientes: Back office integration guide.

Pedidos VTEX no Datasul: feed ou hook

A VTEX recomenda que a integração de pedidos use o Orders Feed v3, em vez de consultar a lista de pedidos de tempos em tempos. O feed é uma fila de eventos de mudança de status: a rotina lê os eventos, busca os detalhes do pedido e confirma (commit) cada evento tratado. A alternativa é o hook, em que a VTEX envia cada evento para um endereço da empresa. Fonte: Feed v3, na documentação da VTEX.

Numa integração feita a partir do Datasul, o feed costuma ser o caminho mais simples: uma rotina batch (RPW) consulta a fila em intervalos curtos, sem que o ERP precise receber chamadas da internet. O hook exige um endereço que responda HTTP 200 em até 5 segundos, ou seja, um serviço publicado (no PASOE, por exemplo) e preparado para picos de volume.

O ciclo de um pedido, segundo o guia de integração de pedidos da VTEX:

Configurar o filtro do feed (POST /api/orders/feed/config), em geral pelo status ready-for-handling.
Ler os eventos da fila (GET /api/orders/feed).
Para cada evento que exige ação, buscar o pedido completo (GET /api/oms/pvt/orders/{orderId}), com itens, pagamento, entrega e cliente.
Gravar o pedido no Datasul.
Confirmar os eventos tratados (POST /api/orders/feed, com os handles recebidos).
Avisar a VTEX que o pedido entrou em tratamento (POST /api/oms/pvt/orders/{orderId}/start-handling), uma única vez por pedido.

Fonte: Set up order integration, na documentação da VTEX.

USING OpenEdge.Net.HTTP.*.
USING Progress.Json.ObjectModel.*.

DEFINE VARIABLE cConta    AS CHARACTER     NO-UNDO. /* lidos da parametrização */
DEFINE VARIABLE cAppKey   AS CHARACTER     NO-UNDO.
DEFINE VARIABLE cAppToken AS CHARACTER     NO-UNDO.
DEFINE VARIABLE oRequest  AS IHttpRequest  NO-UNDO.
DEFINE VARIABLE oClient   AS IHttpClient   NO-UNDO.
DEFINE VARIABLE oResponse AS IHttpResponse NO-UNDO.
DEFINE VARIABLE oEventos  AS JsonArray     NO-UNDO.

oRequest = RequestBuilder:Get("https://" + cConta + ".vtexcommercestable.com.br/api/orders/feed")
               :AddHeader("X-VTEX-API-AppKey", cAppKey)
               :AddHeader("X-VTEX-API-AppToken", cAppToken)
               :AcceptJson()
               :Request.

oClient   = ClientBuilder:Build():Client.
oResponse = oClient:Execute(oRequest).

IF oResponse:StatusCode = 200 AND TYPE-OF(oResponse:Entity, JsonArray) THEN DO:
    oEventos = CAST(oResponse:Entity, JsonArray).
    /* para cada evento: registra na tabela de controle, ignora o que já foi
       tratado, grava o pedido e depois confirma o evento no feed */
END. /* IF resposta com eventos */

Trecho ilustrativo: leitura do feed de pedidos com o cliente HTTP do OpenEdge. Tratamento de erros, log e o commit dos eventos ficam fora do exemplo.

Os cuidados que o feed exige

Todo evento precisa de commit, mesmo quando não exige ação. Sem isso, o feed deixa de entregar os eventos seguintes.
O mesmo evento pode chegar mais de uma vez. A VTEX garante a entrega, mas não a unicidade. A rotina precisa de uma tabela de controle com o orderId para não criar o mesmo pedido duas vezes no Datasul.
Os eventos expiram em 4 dias, com ou sem commit. Uma rotina parada por um feriado prolongado pode perder pedidos, por isso ela precisa de monitoramento.
A chamada HTTP fica fora da transação de banco. A rotina grava o pedido numa transação curta e só depois confirma o evento na VTEX. Assim, uma lentidão da API não segura bloqueios de registro no ERP.

Estoque e preço do Datasul na VTEX

Na VTEX, o estoque é controlado por SKU e por estoque (warehouse). O guia de importação de estoque indica informar a quantidade total de cada SKU em cada estoque, pelo endpoint PUT /api/logistics/pvt/inventory/skus/{skuId}/warehouses/{warehouseId}. Fonte: Import inventory.

Do lado do Datasul, a decisão é qual saldo enviar: o físico, o disponível descontando reservas e pedidos em carteira, ou apenas o de um estabelecimento ou depósito. Essa regra define se a loja vende o que de fato pode ser entregue.

Para preços, a VTEX tem um guia próprio (Import prices). Se o preço de venda nasce numa tabela de preço do Datasul, a rotina envia as alterações; se nasce na loja, esse fluxo fica de fora.

Nota fiscal e rastreio de volta para a loja

Depois que o Datasul emite e autoriza a NF-e, a VTEX precisa ser avisada para o pedido avançar para faturado. A Orders API tem a notificação de nota fiscal (POST /api/oms/pvt/orders/{orderId}/invoice), que recebe, entre outros dados, número, valor, data de emissão e a chave de acesso da NF-e. O rastreio pode seguir no mesmo envio ou ser atualizado depois. Fonte: Orders API.

O gatilho natural é a autorização da nota no Datasul. Faturamento parcial, devolução e cancelamento precisam de regra combinada antes do desenvolvimento, porque cada um muda o status do pedido na VTEX de um jeito diferente.

O que testar em homologação

Pedido com vários itens, frete e desconto, conferindo os totais com o pedido gravado no Datasul.
O mesmo evento recebido duas vezes: o segundo não pode criar outro pedido.
Pedido cancelado na loja antes do faturamento.
Item sem saldo ou SKU sem correspondência no cadastro de itens do Datasul.
Rotina parada por algumas horas e retomada: os eventos acumulados precisam ser processados.
Nota autorizada, dados enviados e pedido atualizado na loja.

E se a loja não for VTEX

A lógica vale para outras plataformas com API REST, como a JET. O que muda é a forma de receber os pedidos, o formato das mensagens e a autenticação. Os controles de duplicidade, log e reprocessamento são os mesmos.

A Partners desenvolve integrações de e-commerce com o Datasul em Progress. Veja a página de integração e-commerce com o Datasul e o desenvolvimento Progress da Partners, ou fale com a equipe sobre o seu caso.