Nó VTEX

O nó de workflow VTEX é um cliente REST para VTEX Commerce APIs. Use-o para consultar pedidos (OMS), SKUs de catálogo e master data de clientes em lojas VTEX.

Node ID no editor: vtex_request
URL padrão: GET https://{{vtex_account}}.vtexcommercestable.com.br/api/oms/pvt/orders

O que faz

• Envia requisições HTTP autenticadas para endpoints específicos da conta VTEX
• Suporta GET, POST, PUT, PATCH e DELETE
• Retorna HTTP status, data da resposta e headers da resposta
• Auth padrão: headers X-VTEX-API-AppKey + X-VTEX-API-AppToken

Pré-requisitos

1. Uma loja VTEX (nome da conta obrigatório)
2. App Key e App Token do VTEX License Manager
3. Integration keys em Configurações → API Keys:
   • vtex_account — nome da conta VTEX (subdomínio, ex.: mystore)
   • vtex_app_key
   • vtex_app_token

Como configurar

Passo 1 — Criar credenciais de API

No VTEX Admin → Account settings → Account → API keys, crie par app key/token com permissões para OMS, Catalog e Master Data conforme necessário.

Passo 2 — Definir credenciais

Adicione as três integration keys. URLs seguem o padrão:

https://{account}.vtexcommercestable.com.br/api/...

Passo 3 — Configurar o nó

Templates de operação integrados

Exemplo — criar cliente no Master Data (POST body):

{
  "email": "{{contact.email}}",
  "firstName": "{{contact.first_name}}",
  "lastName": "{{contact.last_name}}"
}

A VTEX usa módulos de API separados — OMS para pedidos, Catalog System para produtos, Master Data (entidade CL) para clientes.

Passo 4 — Usar dados da resposta

Order ID: {{vtex_1.data.orderId}}
Order status: {{vtex_1.data.status}}

Saídas do nó

Dicas e boas práticas

• A VTEX tem múltiplos base paths — OMS, Catalog e Master Data são separados; use o template correto para cada recurso
• Dados de cliente ficam na entidade Master Data CL — endpoints search vs. document se comportam de forma diferente
• Configure VTEX Order Hook ou webhooks para eventos de pedido em tempo real
• Use query params _where e _fields em endpoints de search do Master Data
• .vtexcommercestable.com.br é o hostname stable padrão para contas no Brasil

Exemplos de uso

Pedido faturado → fluxo de etiqueta

1. Webhook — status VTEX invoiced
2. VTEX GET — detalhes do pedido com endereço de entrega
3. Melhor Envio — cotar e gerar etiqueta
4. Send WhatsApp — rastreamento ao cliente

Sincronizar entidade CL com CRM

1. Schedule — a cada hora
2. VTEX GET — /dataentities/CL/search
3. Loop — upsert de contatos no CRM WhatsWave

FAQ

Por que 403 Forbidden?
App key/token sem permissão para o módulo de API solicitado. Ajuste roles no VTEX License Manager.

Por que não encontro produtos no endpoint de pedidos?
Catalog e OMS são APIs separadas. Use endpoints /api/catalog_system/ para produtos/SKUs.

Qual a diferença entre PUT e PATCH em clientes?
O template integrado de update usa PATCH em documentos Master Data — siga a documentação VTEX para seu schema de entidade.

Posso usar .com em vez de .com.br?
O hostname depende da região da conta VTEX. Confirme nas configurações de API do VTEX Admin.

Referência da API

Relacionado

• Visão geral de E-commerce
• Nó Melhor Envio
• Webhook trigger