> ## 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 ``** | O checkout permite que o lojista cole qualquer script na `` 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 ``: ```html theme={null} ``` ### 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 `` 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)