Metatags de Automação

Catálogo de metatags {{categoria.campo}}, disponibilidade por gatilho e processamento no backend.

Esta documentação descreve as metatags disponíveis no sistema de automações e como elas devem ser normalizadas e processadas pelo backend.

📋 Índice

1. Formato das Metatags
2. Categorias de Metatags
3. Mapeamento para Tabelas do Banco de Dados
4. Processamento no Backend
5. Exemplos de Uso

---

🔤 Formato das Metatags

As metatags são representadas no formato {{chave}} e devem ser substituídas pelos valores reais durante a execução das automações.

Formato:

{{categoria.campo}}

Exemplos:

• {{lead.name}} → Nome do lead
• {{order.total}} → Valor total do pedido
• {{customer.email}} → Email do cliente

---

📂 Categorias de Metatags

1. Lead - Informações Básicas

Metatags relacionadas aos dados básicos do lead.

Chave	Label	Descrição	Tipo
lead.id	ID do Lead	ID único do lead	string
lead.name	Nome do Lead	Nome completo do lead	string
lead.email	Email do Lead	Email do lead	string
lead.phone	Telefone do Lead	Telefone do lead	string
lead.cpf	CPF do Lead	CPF do lead	string
lead.cnpj	CNPJ do Lead	CNPJ do lead	string
lead.birthDate	Data de Nascimento	Data de nascimento formatada	string (DD/MM/YYYY HH:mm)
lead.gender	Gênero	Gênero do lead	string
lead.fingerprint	Fingerprint	Fingerprint do dispositivo	string
lead.checkoutId	ID do Checkout	ID do checkout relacionado	string

Tabela de Origem: leads

---

2. Lead - Endereço

Metatags relacionadas ao endereço do lead.

Chave	Label	Descrição	Tipo
lead.zipCode	CEP	CEP do lead	string
lead.street	Rua	Rua do endereço	string
lead.number	Número	Número do endereço	string
lead.complement	Complemento	Complemento do endereço	string
lead.neighborhood	Bairro	Bairro do endereço	string
lead.city	Cidade	Cidade do lead	string
lead.state	Estado	Estado do lead	string
lead.country	País	País do lead	string
lead.latitude	Latitude	Coordenada de latitude	number
lead.longitude	Longitude	Coordenada de longitude	number

Tabela de Origem: leads

---

3. Lead - Tracking

Metatags relacionadas ao tracking e origem do lead.

Chave	Label	Descrição	Tipo
lead.source	Origem	Origem do lead	string
lead.campaign	Campanha	Campanha do lead	string
lead.utmSource	UTM Source	UTM Source	string
lead.utmMedium	UTM Medium	UTM Medium	string
lead.utmCampaign	UTM Campaign	UTM Campaign	string
lead.utmTerm	UTM Term	UTM Term	string
lead.utmContent	UTM Content	UTM Content	string

3.1. Lead - Device/Browser

Metatags relacionadas ao dispositivo e navegador do lead.

Chave	Label	Descrição	Tipo
lead.ipAddress	IP do Lead	Endereço IP	string
lead.userAgent	User Agent	User Agent do navegador	string
lead.deviceType	Tipo de Dispositivo	Tipo de dispositivo (mobile/desktop)	string
lead.browserName	Nome do Navegador	Nome do navegador	string
lead.browserVersion	Versão do Navegador	Versão do navegador	string
lead.osName	Sistema Operacional	Nome do SO	string
lead.osVersion	Versão do SO	Versão do sistema operacional	string
lead.screenResolution	Resolução da Tela	Resolução da tela	string
lead.language	Idioma	Idioma do navegador	string
lead.timezone	Fuso Horário	Fuso horário	string

3.2. Lead - Status e Datas

Metatags relacionadas ao status e datas do lead.

Chave	Label	Descrição	Tipo
lead.currentStep	Etapa Atual	Etapa atual no checkout	string
lead.isCompleted	Está Completo	Se o checkout foi completado	boolean
lead.isConverted	Está Convertido	Se foi convertido em pedido	boolean
lead.checkAddress	Verificou Endereço	Se verificou o endereço	boolean
lead.checkInfo	Verificou Informações	Se verificou as informações	boolean
lead.checkPayment	Verificou Pagamento	Se verificou o pagamento	boolean
lead.checkoutDuration	Duração do Checkout	Duração em segundos	integer
lead.firstSeenAt	Primeira Visita	Data da primeira visita	string (DD/MM/YYYY HH:mm)
lead.lastSeenAt	Última Visita	Data da última visita	string (DD/MM/YYYY HH:mm)
lead.completedAt	Data de Conclusão	Data de conclusão do checkout	string (DD/MM/YYYY HH:mm)
lead.convertedAt	Data de Conversão	Data de conversão em pedido	string (DD/MM/YYYY HH:mm)
lead.createdAt	Data de Criação	Data de criação do lead	string (DD/MM/YYYY HH:mm)
lead.updatedAt	Data de Atualização	Data de última atualização	string (DD/MM/YYYY HH:mm)

Tabela de Origem: leads

---

4. Cliente (Order Customer)

Metatags relacionadas aos dados do cliente do pedido.

Chave	Label	Descrição	Tipo
customer.name	Nome do Cliente	Nome do cliente do pedido	string
customer.email	Email do Cliente	Email do cliente	string
customer.phone	Telefone do Cliente	Telefone do cliente	string
customer.documentType	Tipo de Documento	Tipo de documento (CPF/CNPJ)	string
customer.documentNumber	CPF/CNPJ	Documento do cliente	string
customer.address	Endereço Completo	Endereço completo formatado	string
customer.addressNumber	Número do Endereço	Número do endereço	string
customer.neighborhood	Bairro	Bairro do cliente	string
customer.complement	Complemento	Complemento do endereço	string
customer.city	Cidade do Cliente	Cidade do cliente	string
customer.state	Estado do Cliente	Estado do cliente	string
customer.zipcode	CEP do Cliente	CEP do cliente	string

Tabela de Origem: order_customers

Relacionamento: order_customers.order_id → orders.id

---

5. Pedido (Order)

Metatags relacionadas aos dados do pedido.

Chave	Label	Descrição	Tipo
order.id	ID do Pedido	ID único do pedido	string (UUID)
order.total	Total do Pedido	Valor total do pedido formatado	string (R$ X,XX)
order.subtotal	Subtotal	Subtotal do pedido formatado	string (R$ X,XX)
order.status	Status do Pedido	Status atual do pedido	enum
order.payment_method	Método de Pagamento	Método de pagamento	string
order.pix_code	Código PIX copia e cola	Código PIX (se aplicável)	string
order.pix_qr_code	QR Code PIX (imagem HTML)	<img> com URL HTTPS em apiv3/public/pix-qr.png	html (email)
order.boleto_barcode	Código de Barras	Código de barras do boleto	string
order.boleto_digitable_line	Linha Digitável	Linha digitável do boleto	string
order.boleto_url	URL do Boleto	URL para visualizar/pagar boleto	string
order.createdAt	Data de Criação	Data de criação formatada	string (DD/MM/YYYY HH:mm)
order.updatedAt	Data de Atualização	Data de atualização formatada	string (DD/MM/YYYY HH:mm)
order.domain	URL do Checkout	URL/domínio do checkout	string
order.customerId	ID do Cliente	ID do cliente (User)	string
order.session	Sessão	ID da sessão do checkout	string
order.shopifyOrderId	ID Shopify	ID do pedido no Shopify	string
order.external_id	ID Externo	ID externo do pedido	string
order.fingerprint	Fingerprint	Fingerprint do dispositivo	string
order.acquirer	Adquirente	Nome da adquirente	string
order.installments	Parcelas	Número de parcelas	integer
order.currency	Moeda	Código da moeda	string
order.woocommerceOrderId	ID WooCommerce	ID do pedido no WooCommerce	integer
order.notes	Observações	Observações do pedido	string
order.couponId	ID do Cupom	ID do cupom aplicado	string
order.discount.type	Tipo de Desconto	Tipo de desconto aplicado	string
order.discount.value	Valor do Desconto	Valor do desconto	number
order.discount.amount	Valor do Desconto Formatado	Valor formatado do desconto	string (R$ X,XX)

Tabela de Origem: orders

Valores Possíveis para order.status:

• PENDING - Pendente
• PAID - Pago
• FAILED - Falhou
• CANCELLED - Cancelado
• REFUNDED - Reembolsado

QR Code PIX no email (order.pix_qr_code)

Metatag HTML (somente canal email, trigger pix.generated). Substitui {{order.pix_qr_code}} por <img src="https://apiv3.usecorvex.com.br/public/pix-qr.png?d=...&s=180"> — não usa data:image/png;base64 (bloqueado por Gmail/Outlook).

Regra	Detalhe
Fonte	order.pix_code (EMV) ou imagem da adquirente quando disponível
MJML	<mj-raw>{{order.pix_qr_code}}</mj-raw>
Valor	{{order.total}} já inclui R$ — não duplique no template
Combo	QR + {{order.pix_code}} + {{order.url_pix_gerado}}

---

6. Itens do Pedido (Order Items)

Metatags relacionadas aos itens do pedido.

Chave	Label	Descrição	Tipo
order.items	Itens do Pedido	Lista completa de itens formatada	string
order.items.first.name	Nome do Primeiro Produto	Nome do primeiro produto	string
order.items.first.price	Preço do Primeiro Produto	Preço formatado do primeiro produto	string (R$ X,XX)
order.items.first.quantity	Quantidade do Primeiro Produto	Quantidade do primeiro produto	integer
order.items.first.productId	ID do Produto	ID do produto	string
order.items.first.variantId	ID da Variante	ID da variante do produto	string
order.items.first.shopifyVariantId	ID Variante Shopify	ID da variante no Shopify	string
order.items.first.isOrderBump	É Order Bump	Se é um order bump	boolean
order.items.first.isUpsell	É Upsell	Se é um upsell	boolean
order.items.first.orderBumpId	ID do Order Bump	ID do order bump (se aplicável)	string
order.items.first.createdAt	Data de Criação	Data de criação do item	string (DD/MM/YYYY HH:mm)

Tabela de Origem: order_items

Relacionamento: order_items.order_id → orders.id

Estrutura de order.items (formato string):

2x Produto A - R$ 99,90
1x Produto B - R$ 149,90

---

7. Frete (Shipping)

Metatags relacionadas ao frete do pedido.

Chave	Label	Descrição	Tipo
shipping.id	ID do Frete	ID único do frete	string
shipping.shippingId	ID do Método	ID do método de frete	string
shipping.name	Nome do Frete	Nome do método de frete	string
shipping.price	Valor do Frete	Valor do frete formatado	string (R$ X,XX)
shipping.turnaround	Prazo de Entrega	Prazo de entrega	string
shipping.carrier	Transportadora	Nome da transportadora	string

Tabela de Origem: order_shippings

Relacionamento: order_shippings.order_id → orders.id

---

8. Navegador/Dispositivo (Browser)

Metatags relacionadas aos dados do navegador/dispositivo.

Chave	Label	Descrição	Tipo
browser.ip	IP do Cliente	Endereço IP	string
browser.userAgent	User Agent	User Agent do navegador	string
browser.screenSize	Tamanho da Tela	Resolução da tela	string
browser.location	Localização	Localização geográfica formatada	string
browser.fingerprint	Fingerprint	Fingerprint do dispositivo	string
browser.utms.source	UTM Source	Origem da campanha (UTM)	string
browser.utms.medium	UTM Medium	Meio da campanha (UTM)	string
browser.utms.campaign	UTM Campaign	Nome da campanha (UTM)	string
browser.utms.term	UTM Term	Termo da campanha (UTM)	string
browser.utms.content	UTM Content	Conteúdo da campanha (UTM)	string

Tabela de Origem: order_browsers

Relacionamento: order_browsers.order_id → orders.id

Formato de browser.location:

São Paulo, SP, BR

---

🗄️ Mapeamento para Tabelas do Banco de Dados

Estrutura de Relacionamentos

orders (tabela principal)
├── order_customers (1:1)
├── order_browsers (1:1)
├── order_items (1:N)
├── order_shippings (1:1)
└── leads (1:1) via leads.order_id

Schema das Tabelas

leads

SQL

- id (TEXT PRIMARY KEY)
- name (TEXT)
- email (TEXT)
- phone (TEXT)
- cpf (TEXT)
- cnpj (TEXT)
- birth_date (TIMESTAMP)
- gender (TEXT)
- zip_code (TEXT)
- street (TEXT)
- number (TEXT)
- complement (TEXT)
- neighborhood (TEXT)
- city (TEXT)
- state (TEXT)
- country (TEXT)
- source (TEXT)
- campaign (TEXT)
- utm_source (TEXT)
- utm_medium (TEXT)
- utm_campaign (TEXT)
- order_id (TEXT FK → orders.id)

order_customers

SQL

- id (TEXT PRIMARY KEY)
- order_id (TEXT FK → orders.id)
- name (TEXT)
- email (TEXT)
- phone (TEXT)
- document_number (TEXT)
- address (TEXT)
- city (TEXT)
- state (TEXT)
- zipcode (TEXT)

orders

SQL

- id (TEXT PRIMARY KEY)
- total (NUMERIC)
- subtotal (NUMERIC)
- status (OrderStatus ENUM)
- payment_method (TEXT)
- pix_code (TEXT)
- boleto_barcode (TEXT)
- created_at (TIMESTAMP)
- domain (TEXT)

order_items

SQL

- id (TEXT PRIMARY KEY)
- order_id (TEXT FK → orders.id)
- product_id (TEXT)
- name (TEXT)
- quantity (INTEGER)
- price (NUMERIC)
- is_order_bump (BOOLEAN)
- is_upsell (BOOLEAN)

order_shippings

SQL

- id (TEXT PRIMARY KEY)
- order_id (TEXT FK → orders.id)
- name (TEXT)
- price (NUMERIC)
- turnaround (TEXT)
- carrier (TEXT)

order_browsers

SQL

- id (TEXT PRIMARY KEY)
- order_id (TEXT FK → orders.id)
- ip (TEXT)
- user_agent (TEXT)
- screen_size (TEXT)
- location (JSONB)

---

⚙️ Processamento no Backend

Fluxo de Substituição de Metatags

1. Receber mensagem com metatags:

   "Olá {{customer.name}}, seu pedido {{order.id}} no valor de {{order.total}} está sendo processado!"

2. Identificar todas as metatags:

   • Extrair padrões {{categoria.campo}}
   • Listar todas as metatags encontradas

3. Buscar dados do contexto:

   • Identificar o orderId do contexto da automação
   • Buscar dados relacionados:
     • orders (pedido principal)
     • order_customers (dados do cliente)
     • order_items (itens do pedido)
     • order_shippings (frete)
     • order_browsers (navegador)
     • leads (lead relacionado)

4. Normalizar valores:

   • Formatar valores monetários (decimal → string com 2 casas, formato R$)
   • Formatar datas (timestamp → string formatada DD/MM/YYYY HH:mm)
   • Tratar valores nulos (retornar string vazia ou valor padrão)
   • Processar arrays (converter para string formatada)

5. Substituir metatags:

   • Substituir cada {{chave}} pelo valor correspondente
   • Metatags não encontradas são substituídas por string vazia ""
   • order.pix_qr_code é resolvida de forma assíncrona a partir de order.pix_code (ou imagem da adquirente), gerando <img> com URL HTTPS em GET /public/pix-qr.png — somente canal email

Implementação

As metatags são substituídas automaticamente pelo motor de automação imediatamente antes do envio de cada mensagem (WhatsApp, SMS, email).

Funções principais:

• replaceMetatags(text, context) - Substitui metatags em uma string
• processMetatagsInObject(data, context) - Processa metatags recursivamente em objetos
• fetchContextData(context) - Busca todos os dados do contexto do banco

---

💡 Exemplos de Uso

Exemplo 1: Mensagem WhatsApp de Confirmação

Mensagem com metatags:

Olá {{customer.name}}! 

Seu pedido #{{order.id}} foi confirmado!

📦 Itens:

{{order.items}}

💰 Total: {{order.total}}

🚚 Frete: {{shipping.name}} - {{shipping.turnaround}}

Você pode acompanhar seu pedido em: {{order.domain}}

Mensagem processada:

Olá João Silva! 

Seu pedido #a08672a1-63cc-43e6-bacf-1f7190643d11 foi confirmado!

📦 Itens:

2x Produto A - R$ 99,90
1x Produto B - R$ 149,90

💰 Total: R$ 249,80

🚚 Frete: PAC - 10 dias úteis

Você pode acompanhar seu pedido em: https://checkout.minhaloja.com

---

Exemplo 2: Email de Lembrete de Pagamento

Mensagem com metatags:

Prezado(a) {{customer.name}},

Seu pedido {{order.id}} no valor de {{order.total}} está aguardando pagamento.

Código PIX: {{order.pix_code}}

Ou pague com boleto: {{order.boleto_barcode}}

Atenciosamente,

Equipe {{order.domain}}

Mensagem processada:

Prezado(a) Maria Santos,

Seu pedido a08672a1-63cc-43e6-bacf-1f7190643d11 no valor de R$ 249,80 está aguardando pagamento.

Código PIX: 00020126360014BR.GOV.BCB.PIX0114+5511999999999...

Ou pague com boleto: 34191.09008 12345.678901 23456.789012 3 12345678901234

Atenciosamente,

Equipe https://checkout.minhaloja.com

---

Exemplo 2b: Email PIX com QR Code (pix.generated)

Canal: email · Gatilho: pix.generated · Metatags: {{order.pix_qr_code}}, {{order.pix_code}}, {{order.url_pix_gerado}}

MJML (trecho):

HTML

<mj-raw>
  <div style="text-align:center;padding:16px 0;">
    {{order.pix_qr_code}}
    <p style="font-size:12px;color:#666;margin-top:8px;">Escaneie com o app do seu banco</p>
  </div>
</mj-raw>
<mj-text font-size="12px"><pre style="word-break:break-all;">{{order.pix_code}}</pre></mj-text>
<mj-button href="{{order.url_pix_gerado}}">Abrir PIX e pagar</mj-button>

Após processamento (trecho do HTML renderizado):

HTML

<img src="https://apiv3.usecorvex.com.br/public/pix-qr.png?d=MDAwMjAxMjYzNjAwMTRCUi4uLg&s=180"
     alt="QR Code PIX" width="180" height="180" style="display:block;margin:0 auto;" />

Importante: {{order.pix_qr_code}} gera URL HTTPS — não use data:image/png;base64 manualmente. Use {{order.total}} sem prefixar R$.

---

Exemplo 3: SMS de Acompanhamento

Mensagem com metatags:

{{customer.name}}, seu pedido {{order.id}} foi enviado!

Transportadora: {{shipping.carrier}}

Prazo: {{shipping.turnaround}}

Acompanhe: {{order.domain}}

Mensagem processada:

João Silva, seu pedido a08672a1-63cc-43e6-bacf-1f7190643d11 foi enviado!

Transportadora: Correios

Prazo: 10 dias úteis

Acompanhe: https://checkout.minhaloja.com

---

Exemplo 4: Email com HTML e Metatags

Mensagem com metatags:

JSON

{
  "type": "action",
  "name": "send_email",
  "data": {
    "subject": "Pedido {{order.id}} - {{order.status}}",
    "html": "<h1>Olá {{customer.name}}!</h1><p>Seu pedido no valor de <strong>{{order.total}}</strong> está <strong>{{order.status}}</strong>.</p><h2>Itens do Pedido:</h2><pre>{{order.items}}</pre><p>Endereço de entrega: {{customer.address}}, {{customer.city}} - {{customer.state}}</p>"
  }
}

Mensagem processada:

HTML

<h1>Olá João Silva!</h1>
<p>Seu pedido no valor de <strong>R$ 249,80</strong> está <strong>PAID</strong>.</p>
<h2>Itens do Pedido:</h2>
<pre>2x Produto A - R$ 99,90
1x Produto B - R$ 149,90</pre>
<p>Endereço de entrega: Rua Exemplo, 123, São Paulo - SP</p>

---

🔍 Validação e Tratamento de Erros

Regras de Validação

1. Metatags Inválidas:

   • Se uma metatag não for encontrada no mapa de valores, substituir por string vazia ""
   • Metatags não processadas são removidas silenciosamente

2. Valores Nulos:

   • Strings: retornar ""
   • Números: retornar "0" ou "R$ 0,00" (para moeda)
   • Datas: retornar ""

3. Arrays Vazios:

   • order.items: retornar "Nenhum item"
   • Arrays de objetos: retornar string vazia

4. Campos Relacionados Não Encontrados:

   • Se order_customers não existir, usar dados do lead
   • Se lead não existir, usar dados do order_customers
   • Se nenhum existir, usar valores padrão ou vazios

---

📌 Notas Importantes

1. Performance:

   • Dados do pedido são buscados uma única vez por execução
   • Cache implícito dentro do contexto da automação
   • Queries otimizadas com índices

2. Segurança:

   • Valores são sanitizados antes de inserir em mensagens
   • HTML é escapado em emails quando necessário
   • Validação de formatos de email e telefone

3. Formatação:

   • Valores monetários: sempre formatados em Real brasileiro (R$)
   • Datas: sempre formatadas no padrão brasileiro (DD/MM/YYYY HH:mm)
   • Números decimais: sempre com 2 casas decimais

4. Extensibilidade:

   • Novas metatags podem ser adicionadas facilmente
   • Suporte a formatação customizada por tipo de campo
   • Processamento recursivo em objetos aninhados

---

🔗 Referências

• Manifesto LLM — Automações — regras para copilot/LLM (inclui QR PIX §8)
• Lista resumida de metatags
• Documentação da API de Automações
• Endpoint GET /automation/metatags

---

Última atualização: Julho 2026 — order.pix_qr_code via URL HTTPS