Guia de Integração — Checkouts × Metrito

Versão: 1.0 · Abril 2026
Contato técnico: contato@metrito.com

O que é a Metrito?

A Metrito é uma plataforma de tracking e atribuição para anunciantes digitais. Rastreamos a jornada do usuário desde o clique no anúncio até a compra, conectando dados de mídia paga (Meta Ads) com dados de vendas do checkout. Problema que resolvemos: Meta perde dados de conversão por bloqueio de cookies, ad blockers e limitações de navegador. A Metrito captura esses dados server-side e devolve as conversões para Meta com muito mais precisão.

Modelos de Integração

Existem dois modelos. O modelo ideal é o Híbrido (Pixel + Webhook), mas o modelo Webhook-only já funciona e é o mais simples de implementar.

Modelo 1: Webhook-only (mais simples)

O que rastreia: apenas pedidos (evento Purchase). Como funciona:

A cada mudança de status de um pedido, o checkout dispara um webhook para a Metrito.
A Metrito processa o pedido, faz a atribuição via UTMs e envia a conversão para Meta via CAPI (Conversions API).

Requisitos do checkout:

Disparar POST JSON para a URL da Metrito a cada mudança de status de pedido
Adequar o payload ao formato da Metrito (descrito na seção de Especificação Técnica)

Cobertura de eventos:

Evento	Suportado?
Purchase (Compra)	✅
InitiateCheckout	❌
AddPaymentInfo	❌
PageView	❌

UTMs são essenciais. Para a atribuição funcionar, o checkout precisa preservar os parâmetros UTM da URL original do visitante (utm_source, utm_medium, utm_campaign, etc.) e incluí-los no payload do webhook. Se o checkout já salva UTMs em campos do pedido, basta enviá-los.

Modelo 2: Híbrido — Pixel + Webhook (recomendado)

O que rastreia: toda a jornada do usuário no checkout. Como funciona:

O Pixel Metrito (script JS) é carregado nas páginas do checkout e dispara eventos de navegação em tempo real.
O Webhook continua sendo disparado para confirmar o status final do pedido (pagamento aprovado, reembolso, etc).

Requisitos do checkout (uma das opções):

Opção	Descrição	Esforço
A) Campo de ID de tracking	O checkout oferece um campo onde o lojista cola o ID do container Metrito. O checkout injeta o script internamente.	Médio (precisa de desenvolvimento)
B) Injeção de script na `<head>`	O checkout permite que o lojista cole qualquer script na `<head>` das páginas.	Baixo (se já existe o recurso)

Cobertura de eventos:

Evento	Suportado?
PageView	✅ (pixel)
InitiateCheckout	✅ (pixel)
AddPaymentInfo	✅ (pixel)
Purchase (Compra)	✅ (webhook — mais confiável que pixel)
Reembolso / Chargeback	✅ (webhook)

Opção A é a ideal. O checkout controla a injeção do script e pode reutilizar dados internos (ex: email do cliente já disponível no contexto do checkout) para enriquecer o tracking sem expor dados no HTML. Qualidade de atribuição: Quanto mais eventos o checkout enviar (PageView, InitiateCheckout, AddPaymentInfo), melhor a qualidade de atribuição no Meta CAPI (event match quality).

Comparativo

Critério	Webhook-only	Híbrido (Pixel + Webhook)
Esforço de integração	Baixo	Médio
Eventos rastreados	Apenas Purchase	PageView, InitiateCheckout, AddPaymentInfo, Purchase
Qualidade da atribuição	Boa (depende de UTMs)	Excelente (event match quality com Meta CAPI)
Satisfação do cliente final	✅	✅✅✅

Recomendação da Metrito: sempre que possível, implementar o modelo Híbrido. Checkouts com integração híbrida terão prioridade nas indicações da Metrito para nossos clientes.

Especificação Técnica: Webhook

Como funciona

O checkout deve se adequar ao formato de payload da Metrito descrito abaixo. Cada lojista terá uma URL única de webhook gerada pela Metrito. O checkout precisa disparar um POST para essa URL a cada mudança de status de pedido.

Endpoint

POST https://webhook.metrito.com/v1/ingress?k={CONNECTION_KEY}
Content-Type: application/json

O CONNECTION_KEY é único por lojista — gerado automaticamente pela Metrito quando o lojista conecta o checkout na plataforma. Exemplo de URL real:

https://webhook.metrito.com/v1/ingress?k=cmnz1crux00em0fn26pnw163n

Payload

O checkout deve enviar o JSON exatamente neste formato. A Metrito valida o payload e rejeita requests fora do schema.

{
  "transaction": {
    "id": "12345",
    "status": "approved",
    "commission_currency": "BRL",
    "commission_value": 9990,
    "currency": "BRL",
    "value": 9990,
    "created_at": "2026-04-14T15:30:00-03:00",
    "updated_at": "2026-04-14T15:30:00-03:00",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "phone": "+5511999999999"
    },
    "products": [
      {
        "id": "prod_001",
        "product_name": "Curso de Marketing",
        "quantity": 1,
        "value": 9990
      }
    ],
    "payment": {
      "method": "credit_card",
      "installments": 3
    }
  },
  "utm": {
    "source": "facebook",
    "medium": "cpc",
    "campaign": "black-friday-2026",
    "term": null,
    "content": null
  }
}

Campos obrigatórios

Campo	Tipo	Descrição
`transaction.id`	string	ID único do pedido/transação
`transaction.status`	enum	Status padronizado (ver tabela abaixo)
`transaction.commission_currency`	string	Moeda ISO 3 letras (ex: `"BRL"`)
`transaction.commission_value`	integer	Valor da comissão em centavos (ex: 9990 = R$99,90)
`transaction.created_at`	string	ISO 8601 com timezone
`transaction.updated_at`	string	ISO 8601 com timezone

Campos opcionais (mas recomendados)

Campo	Tipo	Descrição
`transaction.currency`	string	Moeda do valor total
`transaction.value`	integer	Valor total em centavos
`transaction.customer`	object	Nome, email e telefone do comprador
`transaction.products`	array	Lista de produtos (id, nome, qtd, valor unitário em centavos)
`transaction.payment`	object	Método e parcelas
`utm`	object	Parâmetros UTM capturados na sessão do comprador

Status do Pedido (enum)

O checkout deve mapear seus status internos para um destes valores:

Status Metrito	Significado
`pending`	Aguardando pagamento / processando
`approved`	Pagamento confirmado ✅
`authorized`	Autorizado, aguardando captura
`failed`	Pagamento falhou / recusado / expirado
`refunded`	Reembolsado (total ou parcial)
`chargeback`	Contestação / disputa
`under_analysis`	Em análise de fraude
`cancelled`	Cancelado

Múltiplos status do checkout podem mapear para o mesmo status Metrito. Isso é esperado e correto. Por exemplo: “Venda Aprovada” e “Em Trânsito” (atualização de entrega) ambos representam um pedido já pago — os dois devem ser enviados como approved. A Metrito faz deduplicação automaticamente e não dispara o evento de Purchase para o Meta Ads mais de uma vez para o mesmo pedido.

Enviar webhook a cada mudança de status. Não enviar apenas no approved — precisamos de refunded, chargeback, etc. para manter a atribuição precisa.

Métodos de Pagamento (enum)

Método Metrito	Cobre
`credit_card`	Cartão de crédito e débito
`bank_slip`	Boleto bancário
`pix`	Pix
`paypal`	PayPal
`free`	Grátis / trial
`unknown`	Qualquer outro (fallback)

Valores Monetários

Todos os valores devem ser enviados em centavos (inteiros).

Valor real	Enviar como
R$ 99,90	`9990`
R$ 1.500,00	`150000`
R$ 0,50	`50`

Especificação Técnica: Pixel (modelo híbrido)

Script de tracking

O script Metrito é carregado via URL:

https://{SST_DOMAIN}/mtrtprxy/tag?id={TAG_ID}

Onde:

SST_DOMAIN = domínio server-side do lojista (configurado na Metrito)
TAG_ID = ID do container de tracking do lojista

Injeção do script (Opção A — recomendada)

O checkout expõe um campo de configuração onde o lojista informa o TAG_ID. Internamente, o checkout injeta na <head>:

<script src="https://{SST_DOMAIN}/mtrtprxy/tag?id={TAG_ID}" async></script>

Disparo de eventos (opcional, mas ideal)

Se o checkout quiser disparar eventos diretamente (em vez de depender do auto-tracking do pixel), pode usar:

window.metrito.track("InitiateCheckout", {
  event: {
    facebook: { name: "InitiateCheckout", data: { currency: "BRL", value: 99.90 } },
    label: "InitiateCheckout"
  }
});

window.metrito.track("AddPaymentInfo", {
  event: {
    facebook: { name: "AddPaymentInfo", data: { currency: "BRL", value: 99.90 } },
    label: "AddPaymentInfo"
  }
});

Nota: o evento Purchase NÃO deve ser disparado pelo pixel. Compras sempre devem ser confirmadas via webhook para garantir que o status de pagamento é real.

Fluxo Resumido

┌─────────────────────────────────────────────────────────┐
│                    JORNADA DO USUÁRIO                   │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Clique no anúncio (Meta Ads)                           │
│       │                                                 │
│       ▼                                                 │
│  Landing page (pixel captura UTMs + cookie)             │
│       │                                                 │
│       ▼                                                 │
│  Checkout ──── Pixel dispara InitiateCheckout           │
│       │                                                 │
│       ▼                                                 │
│  Pagamento ── Pixel dispara AddPaymentInfo              │
│       │                                                 │
│       ▼                                                 │
│  Pedido criado ── Webhook dispara Purchase              │
│       │              (status: approved)                 │
│       ▼                                                 │
│  Metrito atribui a conversão ao anúncio correto         │
│  e envia para Meta CAPI                                 │
│                                                         │
└─────────────────────────────────────────────────────────┘

Próximos Passos

Para iniciar a integração, o checkout precisa:

Implementar o disparo de webhooks no formato de payload descrito acima — a cada mudança de status de pedido, disparar um POST para a URL da Metrito.
Mapear os status internos do checkout para os status da Metrito (tabela acima). Precisamos saber quais são todos os possíveis status de pedido do checkout e qual status Metrito cada um representa.
Mapear os métodos de pagamento para os valores aceitos pela Metrito (tabela acima).
Informar sobre suporte a scripts — o checkout permite injetar scripts na <head> ou tem campo de ID de tracking? (necessário para o modelo híbrido)

O que a equipe do checkout precisa nos enviar: a lista completa de status de pedido e métodos de pagamento com o que cada um significa. Com isso, ajudamos a definir o mapeamento correto.

Dúvidas? support@metrito.com

Primeiros Passos

Conceitos Fundamentais

Dashboard

Análise de Dados

Integrações

Rastreamento

Checkout integration guide

Guia de Integração — Checkouts × Metrito

O que é a Metrito?

Modelos de Integração

Modelo 1: Webhook-only (mais simples)

Modelo 2: Híbrido — Pixel + Webhook (recomendado)

Comparativo

Especificação Técnica: Webhook

Como funciona

Endpoint

Payload

Campos obrigatórios

Campos opcionais (mas recomendados)

Status do Pedido (enum)

Métodos de Pagamento (enum)

Valores Monetários

Especificação Técnica: Pixel (modelo híbrido)

Script de tracking

Injeção do script (Opção A — recomendada)

Disparo de eventos (opcional, mas ideal)

Fluxo Resumido

Próximos Passos

​Guia de Integração — Checkouts × Metrito

​O que é a Metrito?

​Modelos de Integração

​Modelo 1: Webhook-only (mais simples)

​Modelo 2: Híbrido — Pixel + Webhook (recomendado)

​Comparativo

​Especificação Técnica: Webhook

​Como funciona

​Endpoint

​Payload

​Campos obrigatórios

​Campos opcionais (mas recomendados)

​Status do Pedido (enum)

​Métodos de Pagamento (enum)

​Valores Monetários

​Especificação Técnica: Pixel (modelo híbrido)

​Script de tracking

​Injeção do script (Opção A — recomendada)

​Disparo de eventos (opcional, mas ideal)

​Fluxo Resumido

​Próximos Passos

Guia de Integração — Checkouts × Metrito

O que é a Metrito?

Modelos de Integração

Modelo 1: Webhook-only (mais simples)

Modelo 2: Híbrido — Pixel + Webhook (recomendado)

Comparativo

Especificação Técnica: Webhook

Como funciona

Endpoint

Payload

Campos obrigatórios

Campos opcionais (mas recomendados)

Status do Pedido (enum)

Métodos de Pagamento (enum)

Valores Monetários

Especificação Técnica: Pixel (modelo híbrido)

Script de tracking

Injeção do script (Opção A — recomendada)

Disparo de eventos (opcional, mas ideal)

Fluxo Resumido

Próximos Passos