> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrito.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout integration guide

# Guia de Integração — Checkouts × Metrito

**Versão:** 1.0 · Abril 2026\
**Contato técnico:** [contato@metrito.com](mailto: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:**

1. A cada mudança de status de um pedido, o checkout dispara um webhook para a Metrito.
2. 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:**

1. O **Pixel Metrito** (script JS) é carregado nas páginas do checkout e dispara eventos de navegação em tempo real.
2. 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.

```json theme={null}
{
  "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>`:

```html theme={null}
<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:

```javascript theme={null}
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:

1. **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.
2. **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.
3. **Mapear os métodos de pagamento** para os valores aceitos pela Metrito (tabela acima).
4. **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](mailto:support@metrito.com)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.