# Tela de Campanhas
Source: https://docs.metrito.com/analise/campanhas

Acompanhe o desempenho das suas campanhas de anúncios com colunas, filtros e exportação.

## O que é a tela de Campanhas?

A tela de **Campanhas** mostra o desempenho dos seus anúncios cruzado com os resultados de negócio. É onde você vê, lado a lado, **gasto** e **retorno** de cada campanha, conjunto e anúncio.

> [!WARNING]
>
> Esta tela trabalha **exclusivamente com dados de anúncios (hoje, Meta Ads) e com dados atribuídos via UTM**. Métricas de negócio como cadastros, conversas, compras e receita só aparecem aqui quando foram **atribuídas por UTM** ao anúncio correspondente.

## Por que um evento não aparece na coluna que adicionei?

Esta é a dúvida mais comum desta tela. A resposta quase sempre é a mesma:

> **Se o evento não tem UTMs, não há como vinculá-lo a uma campanha — então ele não aparece aqui.**

A tela de Campanhas precisa saber **de qual anúncio** veio cada cadastro, conversa ou compra. Esse vínculo é feito pelos parâmetros **UTM** capturados no rastreamento. Sem UTM, o Metrito não consegue dizer a qual campanha aquele evento pertence, e a coluna fica zerada.

> [!TIP]
>
> Garanta que suas campanhas estejam com os **UTMs configurados** corretamente. Veja o guia de [Configuração de UTMs](/tracking/utm-configuration). É isso que alimenta as colunas de cadastros, vendas e receita por campanha.

## Configurar colunas

Você escolhe quais métricas aparecem na tabela. Adicione colunas de anúncios (gasto, impressões, CPM, CTR…) e colunas de negócio atribuídas via UTM (cadastros, vendas aprovadas, faturamento, ROAS…).

> [!NOTE]
>
> Lembre-se: colunas de negócio (cadastros, vendas, receita) dependem de **atribuição por UTM**. Colunas nativas do anúncio (gasto, impressões) vêm direto da conta conectada e aparecem mesmo sem UTM.

## Filtros de status

No topo da tela há um filtro de status que define **quais campanhas entram na visão**:

| Filtro | O que mostra |
| - | - |
| **Todas** | Todas as campanhas disponíveis nas contas de anúncio conectadas ao Metrito, independentemente de status ou veiculação. |
| **Tiveram veiculação** | Apenas campanhas que tiveram **impressão ou gasto** no período selecionado — **não importa o status atual** da campanha. |
| **Apenas ativas** | Apenas as campanhas que estão **de fato com o status ativo** no momento. |

> [!TIP]
>
> Para analisar resultados de um período, prefira **Tiveram veiculação** — ele ignora o status atual e mostra tudo o que realmente rodou no intervalo. Use **Apenas ativas** para olhar o que está no ar agora.

## Filtrar e buscar

* **Filtrar por texto** — busque rapidamente por nome de campanha, conjunto ou anúncio.
* **Filtros de dados** — recorte a visão por conta de anúncio e outros critérios.
* **Período** — todos os números respeitam o intervalo de datas selecionado.

## Exportar dados

Você pode **exportar os dados** da tela para análise externa ou para montar relatórios e planejamentos fora da plataforma.

## Próximos passos

> **[Configuração de UTMs](/tracking/utm-configuration)**
>
> Configure os UTMs para que cadastros e vendas apareçam por campanha.

> **[Contas de anúncio](/integracoes/contas-de-anuncio)**
>
> Conecte e gerencie as contas que alimentam esta tela.


# Tela de Leads
Source: https://docs.metrito.com/analise/leads

Veja todos os contatos identificados, filtre por origem, fonte e WhatsApp, e exporte os dados.

## O que é a tela de Leads?

A tela de **Leads** lista todos os **contatos identificados** do seu projeto. Um lead é alguém que o Metrito conseguiu identificar — por **e-mail**, **telefone**, **nome** ou outro identificador capturado ao longo da jornada.

> [!NOTE]
>
> Visitas anônimas (sem nenhum identificador) ainda não são leads. Elas viram leads no momento em que um identificador é capturado — por exemplo, ao preencher um formulário ou iniciar uma conversa no WhatsApp.

A tela funciona de forma parecida com a de [Vendas](/analise/vendas): uma lista filtrável e exportável, mas voltada aos contatos em vez das transações.

## Filtros disponíveis

| Filtro | O que faz |
| - | - |
| **Origem / Fonte** | De onde o lead veio (a origem da jornada). |
| **Realizou compra** | Separa leads que já compraram dos que ainda não compraram. |
| **Domínio** | O container de rastreamento associado ao lead (hoje, um por campanha). |
| **Número de WhatsApp** | Filtra pelo número de WhatsApp de origem do contato. |
| **Período** | Recorta os leads pelo intervalo de datas. |

> [!TIP]
>
> Combine **Realizou compra = não** com um filtro de **origem** para encontrar rapidamente leads quentes que ainda não converteram — uma boa lista para remarketing ou follow-up.

## Exportar leads

Você pode **exportar os leads como planilha** para usar em planejamentos, campanhas ou análises externas. A exportação inclui os dados do contato — inclusive **qual foi o número de origem** pelo qual o lead chegou.

## Próximos passos

> **[Rastreamento via WhatsApp](/tracking/whatsapp)**
>
> Entenda como as conversas viram leads identificados.

> **[Visão geral do rastreamento](/tracking/overview)**
>
> Como o Metrito identifica e unifica os contatos.


# Tela de Vendas
Source: https://docs.metrito.com/analise/vendas

Veja todas as suas transações e pedidos, com filtros por status, tipo, plataforma e produto.

## O que é a tela de Vendas?

A tela de **Vendas** reúne **todas as transações** registradas no projeto — cada pedido que chegou pelos seus checkouts e integrações conectados.

### Pedido x item

Cada **pedido** representa uma venda e pode conter **um ou mais itens** (produtos). Ou seja, um único pedido pode somar vários produtos comprados de uma vez.

## De onde vêm as vendas?

As vendas chegam das suas [integrações de checkout/gateway](/integracoes/checkouts-e-comissoes) (Hotmart, Shopify, Stripe, etc.) e também de [integrações personalizadas](/integracoes/integracao-personalizada). Cada venda aprovada vira um pedido nesta tela.

### Vendas e rastreamento

Quando um checkout está com a coluna **tracking** ativada em [Integrações](/integracoes/overview), cada **compra aprovada** dispara um **evento de compra (`Purchase`)** para os pixels cadastrados na sua seção de rastreamento.

```mermaid theme={null}
flowchart LR
    venda["Compra aprovada<br/>no checkout"] --> metrito["Metrito<br/>registra o pedido"]
    metrito -->|tracking ativado| pixel["Dispara evento Purchase<br/>para os pixels configurados"]
    metrito --> dash["Atualiza dashboard<br/>e tela de campanhas"]
```

> [!NOTE]
>
> É esse evento de compra que alimenta a atribuição e pode ser enviado para o Meta (e outras plataformas). Se a coluna **tracking** estiver desativada para aquela conexão, o pedido ainda aparece nas Vendas, mas **não** dispara evento de rastreamento.

## Filtros disponíveis

A tela de Vendas permite recortar as transações por:

| Filtro | O que faz |
| - | - |
| **Status** | Filtra por situação da transação (aprovada, pendente, reembolsada, etc.). |
| **Tipo (traqueado / não traqueado)** | Separa vendas que tiveram rastreamento das que não tiveram. |
| **Plataforma** | Filtra pelas integrações conectadas (a origem da venda). |
| **Produto** | Filtra pelos produtos identificados a partir dessas conexões. |

> [!TIP]
>
> O filtro **traqueado / não traqueado** é ótimo para auditar a cobertura do seu rastreamento: se muitas vendas aparecem como "não traqueadas", vale revisar a coluna **tracking** das integrações e a instalação do pixel.

## Período e exportação

* **Período** — as vendas respeitam o intervalo de datas selecionado.
* **Exportação** — você pode exportar as transações para conferência, contabilidade ou análise externa.

## Próximos passos

> **[Checkouts e comissões](/integracoes/checkouts-e-comissoes)**
>
> Entenda como a comissão define o valor líquido das vendas.

> **[Integração personalizada](/integracoes/integracao-personalizada)**
>
> Envie pedidos de qualquer sistema próprio para o Metrito.


# Atualizar Gatilho
Source: https://docs.metrito.com/api-reference/atualizar-gatilho

/openapi/tracking.yaml put /v3/tracking/containers/{container_id}/triggers/{trigger_id}
Atualiza um gatilho existente. Apenas gatilhos com `trigger.type = "api"` podem ser atualizados via API pública.




# Atualizar Objetos de Anúncios
Source: https://docs.metrito.com/api-reference/atualizar-objetos-de-anúncios

/openapi/platform.yaml put /v3/connections/{connection_id}/objects
Pausar, ativar ou alterar o orçamento de campanhas, conjuntos de anúncios ou anúncios em lote.

Cada item no array `updates` recebe **exatamente um** dos campos `status` ou `budget` — nunca ambos.

O orçamento deve ser enviado em **centavos da moeda da conta** (ex: `5000` = R$ 50,00 ou US$ 50,00).
O Metrito detecta automaticamente se a campanha usa orçamento diário ou vitalício.


## Identificando a conexão

O parâmetro `connectionId` aceita dois formatos:

| Formato | Exemplo | Quando usar |
| - | - | - |
| ID Metrito | `64a1b2c3d4e5f6a7b8c9d0e1` | Padrão — obtido via `GET /v3/projects/:id/connections` |
| ID da conta Meta | `act_123456789` ou `123456789` | Quando você já tem o ID da conta de anúncios |

## Tipos de objeto suportados

| `type` | O que representa |
| - | - |
| `campaign` | Campanha |
| `adset` | Conjunto de anúncios |
| `ad` | Anúncio individual |

## Operações por objeto

| Operação | Campo | Valores aceitos | Suporta |
| - | - | - | - |
| Pausar / Ativar | `status` | `"ACTIVE"`, `"PAUSED"` | campaign, adset, ad |
| Alterar orçamento | `budget` | Inteiro positivo em centavos | campaign, adset |

> **Nota:** Anúncios não possuem orçamento próprio. Use `campaign` ou `adset` para alterar orçamento.

## Misturar operações em uma chamada

Você pode misturar operações de `status` e `budget` no mesmo array `updates`. O Metrito agrupa e processa cada tipo separadamente.

## Exemplos de uso

**Pausar uma campanha:**

```json
{
  "type": "campaign",
  "updates": [
    { "id": "120215678901234567", "status": "PAUSED" }
  ]
}
```

**Ativar múltiplos anúncios:**

```json
{
  "type": "ad",
  "updates": [
    { "id": "120215678901234567", "status": "ACTIVE" },
    { "id": "120215678901234568", "status": "ACTIVE" }
  ]
}
```

**Alterar orçamento de múltiplas campanhas:**

```json
{
  "type": "campaign",
  "updates": [
    { "id": "120215678901234567", "budget": 10000 },
    { "id": "120215678901234568", "budget": 5000 }
  ]
}
```

**Pausar e alterar orçamento na mesma chamada:**

```json
{
  "type": "campaign",
  "updates": [
    { "id": "120215678901234567", "status": "PAUSED" },
    { "id": "120215678901234568", "budget": 10000 }
  ]
}
```


# Login
Source: https://docs.metrito.com/api-reference/autenticar-na-plataforma

/openapi/platform.yaml post /v3/auth/login
Autentica o usuário com e-mail e senha e retorna um token JWT para uso nas demais rotas autenticadas.

O token retornado deve ser enviado no header `Authorization: Bearer {token}` em todas as requisições autenticadas.


## Uso do Token

O token JWT retornado tem validade de **7 dias**. Após expirar, faça login novamente.

Envie o token em todas as requisições autenticadas:

```bash
curl -X GET https://api.metrito.com/v3/projects \
  -H "Authorization: Bearer {token}"
```

> [!WARNING]
>
> Este endpoint é destinado a integrações server-to-server. Para a maioria dos casos de uso, recomendamos usar **API Keys** (chaves de serviço) que não expiram e têm escopos granulares. Veja a [página de autenticação](/api-reference/authentication) para mais detalhes.


# Autenticação
Source: https://docs.metrito.com/api-reference/authentication

Como autenticar nas APIs do Metrito — JWT, API Keys e endpoints públicos

O Metrito oferece diferentes métodos de autenticação dependendo da API e do caso de uso.

## Métodos de Autenticação

> **API Key (Recomendado)**
>
> Chave de serviço com escopos granulares. Ideal para integrações, automações e acesso programático.

> **JWT Token**
>
> Token obtido via login com e-mail e senha. Usado para integrações que precisam de contexto de usuário.

> **[OAuth 2.0](/api-reference/oauth)**
>
> Para plataformas de terceiros que precisam conectar workspaces de usuários sem intervenção manual. Gera uma API Key automaticamente com consentimento do usuário.

***

## API Key (Chave de Serviço)

API Keys são a forma recomendada de autenticação para integrações. Têm escopos granulares, não expiram (a menos que configurado) e não dependem de sessão de usuário.

### Formato

Todas as API Keys seguem o formato `mtk_live_...` e podem ser enviadas de duas formas:

```bash theme={null}
# Via header Authorization
curl -X POST https://api.metrito.com/v3/query \
  -H "Authorization: Bearer mtk_live_abc123..."

# Via header x-api-key
curl -X POST https://api.metrito.com/v3/query \
  -H "x-api-key: mtk_live_abc123..."
```

> [!NOTE]
>
> Ao usar API Key, **não é necessário** enviar o header `X-Workspace-Id` — o workspace é resolvido automaticamente pela chave.

### Como criar uma API Key

**1. Acesse as Configurações**

Na plataforma Metrito, clique no menu lateral e acesse **Configurações** (ícone de engrenagem).

**2. Vá até Chaves de API**

Na página de configurações, selecione a aba **Chaves de API**.

**3. Crie uma nova chave**

Clique em **Criar chave de API** e preencha:

* **Nome**: identificador para referência (ex: "n8n Produção", "Meu Dashboard")
* **Escopos**: permissões que a chave terá
* **Expiração**: nunca, 30 dias, 90 dias ou 1 ano

**4. Copie o token**

Após a criação, copie o token imediatamente. **Ele não será exibido novamente** por segurança.

### Escopos Disponíveis

| Escopo | Descrição |
| - | - |
| `tracking:read` | Leitura de containers, eventos, decode messages (`GET /v3/tracking/*`) |
| `tracking:write` | Enviar eventos de rastreamento, criar/editar conversões (`POST /v3/tracking/*`) |
| `data:read` | Consultar métricas via Data API (`POST /v3/query`, `GET /v3/fields`, `GET /v3/connections/*`) |
| `data:write` | Escrita de dados na Data API (reservado para uso futuro) |

> [!WARNING]
>
> Selecione apenas os escopos necessários para sua integração. Chaves com menos permissões são mais seguras.

***

## JWT Token (Login)

Para obter um JWT, use o endpoint de [login](/api-reference/autenticar-na-plataforma):

```bash theme={null}
curl -X POST https://api.metrito.com/v3/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "seu@email.com", "password": "suaSenha" }'
```

A resposta contém o `token` JWT:

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "60f1b2c3d4e5f6a7b8c9d0e1",
    "name": "João Silva",
    "email": "seu@email.com",
    "role": "owner"
  }
}
```

Use o token nas requisições autenticadas:

```bash theme={null}
curl -X GET https://api.metrito.com/v3/projects \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
```

> [!NOTE]
>
> O JWT expira em **7 dias**. Para integrações de longa duração, use API Keys.

***

## Resumo por API

| API | Endpoint | Autenticação |
| - | - | - |
| **Plataforma** | `POST /v3/auth/login` | Nenhuma (retorna JWT) |
| **Plataforma** | `GET /v3/projects` | JWT **ou** API Key (`data:read`) |
| **Plataforma** | `GET /v3/projects/{id}/connections` | JWT **ou** API Key (`data:read`) |
| **Plataforma** | `GET /v3/connections/{id}/sync` | JWT **ou** API Key (`data:read`) |
| **Plataforma** | `PUT /v3/connections/{id}/objects` | JWT **ou** API Key (`data:write`) |
| **Rastreamento** | `GET /v3/tracking/containers/{id}` | API Key (`tracking:read`) |
| **Rastreamento** | `GET /v3/tracking/containers/{id}/triggers` | API Key (`tracking:read`) |
| **Rastreamento** | `POST /v3/tracking/containers/{id}/triggers` | API Key (`tracking:write`) |
| **Rastreamento** | `PUT/DELETE /v3/tracking/containers/{id}/triggers/{triggerId}` | API Key (`tracking:write`) |
| **Rastreamento** | `POST /v3/tracking/events` | API Key **ou** Nenhuma (dual-mode) |
| **Rastreamento** | `POST /v3/tracking/messages/decode` | API Key (`tracking:read`) |
| **Rastreamento** | `POST /v2/tracking/generic?k={chave}` | Query param `k` |
| **Dados** | `GET /v3/fields` | JWT + `X-Workspace-Id` **ou** API Key (`data:read`) |
| **Dados** | `POST /v3/query` | JWT + `X-Workspace-Id` **ou** API Key |


# Consultar Métricas
Source: https://docs.metrito.com/api-reference/consultar-métricas-de-anúncios

/openapi/data.yaml post /v3/query
Endpoint unificado para consulta de métricas de anúncios. Retorna dados sincronizados do PostgreSQL via CubeJS,
com enriquecimento de nomes de entidades e conversão de moeda automática.

Os dados são sincronizados em background a cada 5-30 minutos (conforme o tier do plano).
A resposta é instantânea (~50ms) pois consulta dados já armazenados localmente.


## Autenticação

Este endpoint aceita dois formatos de autenticação:

1. **JWT da plataforma**
   * Header: `Authorization: Bearer {jwt}`
   * Header adicional obrigatório: `X-Workspace-Id`

2. **API Key do Metrito**
   * Header: `Authorization: Bearer mtk_live_...` **ou** `x-api-key: mtk_live_...`
   * **Não** precisa enviar `X-Workspace-Id` (o workspace é resolvido pela própria chave)

## Métricas Disponíveis

### Métricas Base (sincronizadas das APIs)

| Métrica | Descrição |
| - | - |
| `spend` | Valor gasto em anúncios |
| `impressions` | Vezes que o anúncio foi exibido |
| `clicks` | Cliques no anúncio |
| `reach` | Pessoas únicas alcançadas (apenas Meta) |
| `video_plays` | Vezes que o vídeo começou a rodar |
| `video_views_p75` | Visualizações até 75% do vídeo |

### Métricas Calculadas — Eficiência de Tráfego

| Métrica | Fórmula | Descrição |
| - | - | - |
| `ctr` | clicks / impressions | Taxa de clique |
| `cpc` | spend / clicks | Custo por clique |
| `cpm` | (spend / impressions) \* 1000 | Custo por mil impressões |
| `frequency` | impressions / reach | Frequência média |

### Métricas Calculadas — Análise de Vídeo

| Métrica | Fórmula | Descrição |
| - | - | - |
| `hook_rate` | video\_views\_3s / impressions | Qualidade do hook (3s) |
| `hold_rate` | video\_views\_p75 / impressions | Qualidade do conteúdo (75%) |
| `play_rate` | video\_plays / impressions | Taxa de play |
| `cta_rate` | clicks / video\_views\_p75 | Eficácia do CTA |

### Métricas Calculadas — Atribuição de Vendas

| Métrica | Descrição |
| - | - |
| `tx_revenue` | Faturamento atribuído |
| `tx_count` | Vendas aprovadas |
| `tx_count_total` | Vendas totais (inclui pendentes) |
| `tx_count_pending` | Vendas pendentes |
| `tx_count_refunded` | Reembolsos |
| `page_views` | Visualizações de página |
| `leads` | Cadastros/leads |
| `initiate_checkout` | Inícios de checkout |

### Métricas Calculadas — Financeiro

| Métrica | Fórmula | Descrição |
| - | - | - |
| `roas` | tx\_revenue / spend | Retorno sobre investimento em ads |
| `roi` | (tx\_revenue - spend) / spend | ROI percentual |
| `profit` | tx\_revenue - spend - tx\_product\_costs | Lucro líquido |
| `aov` | tx\_revenue / tx\_count | Ticket médio |
| `cpa` | spend / tx\_count | Custo por aquisição |
| `cpl` | spend / leads | Custo por lead |

## Granularidades

| Valor | Descrição |
| - | - |
| `5min`, `10min`, `15min`, `30min` | Sub-horária (planos Growth/Enterprise) |
| `hour` | Horária |
| `day` | Diária |
| `week` | Semanal |
| `month` | Mensal |
| `quarter` | Trimestral |
| `year` | Anual |

Se a granularidade solicitada não tiver dados disponíveis, o sistema faz fallback automático para granularidades mais grossas (`raw → hourly → daily`).

## Conversão de Moeda

A API converte automaticamente valores monetários para a moeda padrão do projeto. Para forçar uma moeda específica, use `metadata.convert_to_currency`.

Apenas campos monetários são convertidos (`spend`, `cpc`, `cpm`, `cpa`, `roas`, `profit`, `aov`, etc.). Campos como `clicks`, `impressions`, `ctr` não são afetados.


# Criar Gatilho
Source: https://docs.metrito.com/api-reference/criar-gatilho

/openapi/tracking.yaml post /v3/tracking/containers/{container_id}/triggers
Cria um novo gatilho no container. Via API pública, apenas gatilhos com `trigger.type = "api"` podem ser criados — o disparo é feito programaticamente via `POST /v3/tracking/events`.

Suporta header `Idempotency-Key` para evitar criações duplicadas em caso de retry.


## Tipo de Disparo

Via API pública, apenas `trigger.type = "api"` é suportado. Gatilhos de outros tipos (pageview, click, scroll) são criados via interface da plataforma Metrito.

## Mapeamento Meta

O campo `config.facebook.name` define qual evento padrão da Meta será disparado quando este gatilho for ativado. Valores suportados: `Purchase`, `Lead`, `PageView`, `AddToCart`, `InitiateCheckout`, etc.


# Decodificar Mensagens
Source: https://docs.metrito.com/api-reference/decodificar-mensagens-whatsapp

/openapi/tracking.yaml post /v3/tracking/messages/decode
Decodifica mensagens rastreadas do WhatsApp, retornando os parâmetros UTM e dados de rastreamento originais associados a cada mensagem.




# Deletar Gatilho
Source: https://docs.metrito.com/api-reference/deletar-gatilho

/openapi/tracking.yaml delete /v3/tracking/containers/{container_id}/triggers/{trigger_id}
Remove um gatilho. Apenas gatilhos com `trigger.type = "api"` podem ser deletados via API pública.



# Enviar Evento
Source: https://docs.metrito.com/api-reference/enviar-evento

/openapi/tracking.yaml post /v3/tracking/events
Envia um evento de rastreamento ao Metrito.

## Dois modos de uso

| Modo | Como usar | Resolução do container |
|------|-----------|------------------------|
| **Autenticado** (API key) | `Authorization: Bearer mtk_live_...` ou `x-api-key` | Container resolvido automaticamente pela chave |
| **Público** (sem auth) | Sem header de autenticação | Campo `domain` obrigatório no body |

O modo público é equivalente ao endpoint legado `POST /v2/public/tracking/events` — use este endpoint como ponto de entrada único.

## Idempotência

Envie `Idempotency-Key` com um valor único por evento. Dentro de 24h, chamadas repetidas com o mesmo key retornam a resposta original com `X-Idempotent-Replayed: true`.


## Modo Autenticado vs Público

**Com API key** — o container é resolvido automaticamente pela chave. O campo `domain` no body é ignorado (mas pode ser enviado).

**Público (sem auth)** — o campo `domain` é obrigatório e identifica o container de destino.

## config.name vs config.facebook.name

| Campo | Onde é usado | Descrição |
| - | - | - |
| `config.name` | **Metrito** | Nome interno para relatórios e dashboards |
| `config.facebook.name` | **Meta (Facebook/Instagram)** | Nome enviado à Meta Conversion API (`PageView`, `Purchase`, `Lead`, etc.) |

Se `config.facebook` for omitido, o evento é registrado no Metrito mas **não** é enviado para a Meta.


# Visão Geral
Source: https://docs.metrito.com/api-reference/introduction

Referência completa das APIs públicas do Metrito

O Metrito expõe três APIs com finalidades distintas:

| API | URL Base | Finalidade |
| - | - | - |
| **Plataforma** | `https://api.metrito.com` | Autenticação, projetos e conexões |
| **Rastreamento** | `https://api.metrito.com` | Eventos de rastreamento e webhooks de transação |
| **Dados** | `https://api.metrito.com` | Consulta de métricas de anúncios sincronizadas |

Plataforma, rastreamento e consulta de métricas compartilham o host **`https://api.metrito.com`** (gateway unificado). Não é necessário usar um subdomínio específico para dados.

## Autenticação

A maioria dos endpoints exige autenticação. Veja a [página de autenticação](/api-reference/authentication) para detalhes completos.

**Resumo rápido:**

* **API Key** `mtk_live_...` — recomendado para integrações. Criada em **Configurações → Chaves de API** na plataforma.
* **JWT** — obtido via `POST /v3/auth/login` com e-mail e senha.
* **Públicos** — apenas `POST /v2/public/tracking/events` (modo sem API key) não exige autenticação. `GET /v3/fields` e as demais rotas da API de dados exigem JWT ou API Key.

## Infraestrutura

Toda requisição à API v3 retorna:

* **`X-Request-Id`** — ID único para rastreamento e suporte
* **`X-RateLimit-*`** — Headers de rate limiting ([ver detalhes](/api-reference/rate-limits))
* **Formato de erro padronizado** — Códigos máquina-legíveis em todas as respostas de erro

## APIs

> **[Plataforma](/api-reference/autenticar-na-plataforma)**
>
> Login, listagem de projetos e conexões. Ponto de partida para descobrir IDs.

> **[Rastreamento](/api-reference/enviar-evento)**
>
> Envie eventos de rastreamento e webhooks de transação de qualquer plataforma.

> **[Dados](/api-reference/listar-campos-disponíveis)**
>
> Consulte métricas de anúncios com filtros, granularidade temporal e conversão de moeda.

## Fluxo Típico de Integração

**1. Autentique-se**

Crie uma [API Key](/api-reference/authentication) na plataforma ou faça [login](/api-reference/autenticar-na-plataforma) para obter um JWT.

**2. Descubra seus projetos**

Use `GET /v3/projects` para listar os projetos disponíveis e obter o `project_id`.

**3. Liste as conexões**

Use `GET /v3/projects/{project_id}/connections` para ver as fontes de dados conectadas.

**4. Consulte campos disponíveis**

Use `GET /v3/fields` para descobrir quais métricas e dimensões estão disponíveis.

**5. Consulte métricas**

Use `POST /v3/query` com o `project_id`, campos desejados e período para obter os dados.


# Listar Campos Disponíveis
Source: https://docs.metrito.com/api-reference/listar-campos-disponíveis

/openapi/data.yaml get /v3/fields
Retorna a lista de todas as métricas e dimensões disponíveis para consulta,
com metadados como nome, descrição, tipo de dado e fontes suportadas.

**Autenticação obrigatória** em `api.metrito.com`:

- **JWT** — `Authorization: Bearer {jwt}` e header `X-Workspace-Id`
- **API Key** — `Authorization: Bearer mtk_live_...` ou header `x-api-key` (workspace resolvido pela chave; `X-Workspace-Id` não é necessário)

Requer escopo `data:read` quando usar API Key.




# Listar Conexões
Source: https://docs.metrito.com/api-reference/listar-conexões-de-um-projeto

/openapi/platform.yaml get /v3/projects/{project_id}/connections
Retorna todas as conexões (fontes de dados) vinculadas a um projeto específico.

Cada conexão representa uma conta de anúncios ou fonte de dados integrada (Meta Ads, Google Ads, TikTok Ads, etc.).


## Autenticação

Este endpoint aceita dois formatos de autenticação:

1. **JWT da plataforma**
   * Header: `Authorization: Bearer {jwt}`

2. **API Key do Metrito**
   * Header: `Authorization: Bearer mtk_live_...` **ou** `x-api-key: mtk_live_...`
   * Requer escopo `data:read`
   * O projeto deve pertencer ao workspace vinculado à chave


# Listar Gatilhos
Source: https://docs.metrito.com/api-reference/listar-gatilhos

/openapi/tracking.yaml get /v3/tracking/containers/{container_id}/triggers
Retorna os gatilhos configurados em um container com paginação.

Um **gatilho** é uma configuração que define quando e como uma conversão deve ser disparada — tipo de disparo (`api`, `page_view`, `element_click`, etc.), nome do evento no Metrito, mapeamento para a Meta Conversion API e condições de página.




# Listar Projetos
Source: https://docs.metrito.com/api-reference/listar-projetos-do-usuário

/openapi/platform.yaml get /v3/projects
Retorna todos os projetos (brands) que o usuário autenticado tem acesso.

Cada projeto contém um `id` que é usado como `project_id` nas demais APIs (Data API, conexões, etc.).


## Autenticação

Este endpoint aceita dois formatos de autenticação:

1. **JWT da plataforma**
   * Header: `Authorization: Bearer {jwt}`

2. **API Key do Metrito**
   * Header: `Authorization: Bearer mtk_live_...` **ou** `x-api-key: mtk_live_...`
   * Requer escopo `data:read`
   * Retorna todos os projetos do workspace vinculado à chave


# OAuth 2.0
Source: https://docs.metrito.com/api-reference/oauth

Permita que plataformas de terceiros se conectem a workspaces do Metrito com consentimento do usuário

O Metrito suporta um fluxo de autorização baseado em **OAuth 2.0 Authorization Code** para plataformas de terceiros — como ferramentas de automação, CRMs e plataformas de marketing — que precisam acessar workspaces do Metrito em nome de seus usuários.

Com esse fluxo, o usuário nunca precisa criar ou copiar uma API Key manualmente. A plataforma parceira redireciona o usuário para o Metrito, onde ele visualiza uma tela de consentimento, seleciona a workspace e aprova o acesso. O resultado é uma API Key criada automaticamente, pronta para uso.

> [!WARNING]
>
> **O `client_id` e o `client_secret` não são gerados automaticamente.** Para integrar sua plataforma com o Metrito via OAuth, você precisa solicitá-los diretamente com a equipe do Metrito.
>
> [→ Entrar em contato com o time do Metrito](mailto:contato@metrito.com)
>
> Ao entrar em contato, informe o nome da sua plataforma, a URL de redirecionamento (`redirect_uri`) que você usará e uma breve descrição do caso de uso.

***

## Como funciona o fluxo

**1. Redirecionar o usuário para a tela de consentimento**

Sua plataforma redireciona o usuário para a URL de autorização do Metrito. O usuário precisa estar logado no Metrito — caso não esteja, será redirecionado automaticamente para o login antes de ver a tela de consentimento.

```
https://app.metrito.com/authorize
  ?client_id=metrito_app_suaplataforma
  &redirect_uri=https://suaplataforma.com/metrito/callback
  &state=TOKEN_CSRF_GERADO_POR_VOCE
```

O parâmetro `state` deve ser um valor aleatório gerado pela sua plataforma para prevenir ataques CSRF. Você receberá ele de volta no redirecionamento.

**2. Usuário aprova o acesso**

O Metrito exibe uma tela mostrando o nome da sua plataforma, as permissões que serão concedidas e um seletor de workspace. O usuário seleciona a workspace que deseja conectar e clica em **Autorizar acesso**.

Se o usuário clicar em **Cancelar**, será redirecionado para a `redirect_uri` com `error=access_denied`.

**3. Metrito redireciona de volta com um código**

Após a aprovação, o Metrito redireciona para a `redirect_uri` registrada com um código de autorização de uso único:

```
https://suaplataforma.com/metrito/callback
  ?code=CODIGO_DE_AUTORIZACAO
  &state=TOKEN_CSRF_GERADO_POR_VOCE
```

Valide que o `state` recebido corresponde ao que você enviou. O `code` expira em **5 minutos** e só pode ser usado uma vez.

**4. Trocar o código por uma API Key (servidor para servidor)**

No backend da sua plataforma, troque o código por uma API Key do Metrito. Essa chamada usa o `client_secret` e nunca deve ser feita pelo frontend.

```bash theme={null}
curl -X POST https://api.metrito.com/v3/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "metrito_app_suaplataforma",
    "client_secret": "sk_live_...",
    "code": "CODIGO_DE_AUTORIZACAO",
    "redirect_uri": "https://suaplataforma.com/metrito/callback",
    "key_name": "Sua Plataforma"
  }'
```

A API Key retornada (`access_token`) pode ser usada imediatamente para autenticar chamadas à API do Metrito.

***

## URL de Autorização

```
https://app.metrito.com/authorize
```

### Parâmetros

| Parâmetro | Obrigatório | Descrição |
| - | - | - |
| `client_id` | Sim | Identificador da sua plataforma, fornecido pelo time do Metrito (ex: `metrito_app_suaplataforma`) |
| `redirect_uri` | Sim | URL para onde o usuário será redirecionado após a autorização. Deve corresponder exatamente à URI registrada pelo time do Metrito |
| `state` | Sim | String aleatória gerada pela sua plataforma para prevenção de CSRF. Será retornada no redirecionamento |

***

## Troca de Código por API Key

### Endpoint

```
POST https://api.metrito.com/v3/oauth/token
```

### Body da requisição

```json theme={null}
{
  "grant_type": "authorization_code",
  "client_id": "metrito_app_suaplataforma",
  "client_secret": "sk_live_...",
  "code": "CODIGO_DE_AUTORIZACAO",
  "redirect_uri": "https://suaplataforma.com/metrito/callback",
  "key_name": "Sua Plataforma - Conta do João"
}
```

| Campo | Obrigatório | Descrição |
| - | - | - |
| `grant_type` | Sim | Deve ser `"authorization_code"` |
| `client_id` | Sim | Seu identificador de aplicativo OAuth |
| `client_secret` | Sim | Seu segredo de aplicativo OAuth. **Nunca exponha isso no frontend** |
| `code` | Sim | O código recebido no redirecionamento |
| `redirect_uri` | Sim | Exatamente a mesma URI usada na etapa de autorização |
| `key_name` | Não | Nome da chave que aparecerá na workspace do usuário. Se omitido, usa o nome da sua plataforma (ex: `"Zapflow"`) |

### Resposta

```json theme={null}
{
  "access_token": "mtk_live_AbCdEfGh...",
  "token_type": "bearer",
  "scope": "tracking:read tracking:write data:read data:write",
  "workspace_id": "60f1b2c3d4e5f6a7b8c9d0e1",
  "key_name": "Sua Plataforma - Conta do João",
  "expires_at": null
}
```

| Campo | Descrição |
| - | - |
| `access_token` | A API Key do Metrito no formato `mtk_live_...`. Use como `Bearer` token em todas as chamadas da API |
| `token_type` | Sempre `"bearer"` |
| `scope` | Escopos concedidos (sempre todos os quatro escopos disponíveis) |
| `workspace_id` | ID da workspace que o usuário autorizou |
| `key_name` | Nome da chave criada na workspace |
| `expires_at` | Data de expiração da chave, ou `null` se não expira |

### Usando a API Key

Após receber o `access_token`, use-o como Bearer token em todas as chamadas:

```bash theme={null}
curl -X GET https://api.metrito.com/v3/projects \
  -H "Authorization: Bearer mtk_live_AbCdEfGh..."
```

> [!NOTE]
>
> A API Key criada via OAuth fica visível na seção **Configurações → Chaves de API** da workspace do usuário, identificada com o nome da sua plataforma. O usuário pode revogá-la a qualquer momento.

***

## Escopos

Toda API Key gerada via OAuth recebe automaticamente todos os escopos disponíveis. Não há seleção de escopos por parte da plataforma parceira ou do usuário.

| Escopo | Permissão |
| - | - |
| `tracking:read` | Leitura de containers, eventos e decode messages |
| `tracking:write` | Envio de eventos de rastreamento e criação de conversões |
| `data:read` | Consulta de métricas de anúncios via Data API |
| `data:write` | Escrita de dados na Data API |

***

## Segurança

> **Códigos de uso único**
>
> O código de autorização (`code`) expira em 5 minutos e é invalidado imediatamente após o primeiro uso. Não pode ser reutilizado.

> **Proteção contra CSRF**
>
> O parâmetro `state` é retornado intacto no redirecionamento. Sempre valide que o valor recebido corresponde ao que você enviou antes de trocar o código.

> **redirect\_uri obrigatória**
>
> A `redirect_uri` usada na troca de código deve ser idêntica à registrada e à utilizada na autorização. URIs não registradas são rejeitadas.

> **client\_secret no servidor**
>
> O `client_secret` só deve existir no backend da sua plataforma. Nunca inclua-o em código de frontend, aplicativos móveis ou em URLs.

***

## Erros comuns

| Código HTTP | Mensagem | Causa |
| - | - | - |
| `400` | `redirect_uri is not registered` | A URI não foi registrada para este `client_id` |
| `400` | `Invalid authorization code` | Código inválido, expirado ou já utilizado |
| `400` | `client_id mismatch` | O `client_id` na troca não corresponde ao usado na autorização |
| `400` | `redirect_uri mismatch` | A `redirect_uri` na troca difere da usada na autorização |
| `401` | `Invalid client credentials` | `client_id` ou `client_secret` incorretos |
| `404` | `OAuth application not found` | `client_id` não existe ou foi revogado |

***

## Solicitar credenciais

Para integrar sua plataforma ao Metrito via OAuth, entre em contato com nosso time:

> **[Solicitar client\_id e client\_secret](mailto:contato@metrito.com)**
>
> Envie um e-mail para **[contato@metrito.com](mailto:contato@metrito.com)** com o nome da sua plataforma, a `redirect_uri` que você usará e uma breve descrição do caso de uso. O time do Metrito retornará suas credenciais em até 2 dias úteis.


# Obter Container
Source: https://docs.metrito.com/api-reference/obter-container

/openapi/tracking.yaml get /v3/tracking/containers/{container_id}
Retorna informações completas de um container de rastreamento, incluindo domínio, gatilhos configurados e pixels vinculados.

O parâmetro `container_id` aceita **três formatos** de identificação:

| Formato | Exemplo | Onde encontrar |
|---------|---------|----------------|
| **ObjectId** do Metrito | `64a1b2c3d4e5f6a7b8c9d0e1` | Na URL da plataforma após `/containers/` |
| **Domínio** (containers v2) | `minhaloja.com.br` | O domínio real configurado no container |
| **Metrito Tracking Code** (containers v3) | `MTC-AB12` | Na sidebar da plataforma, página de Tracking |


## Identificando o container

O parâmetro `container_id` é flexível e aceita qualquer um dos três formatos abaixo:

| Formato | Exemplo | Quando usar |
| - | - | - |
| ObjectId Metrito | `64a1b2c3d4e5f6a7b8c9d0e1` | Obtido via URL da plataforma (`/containers/{id}`) ou via API |
| Domínio (v2) | `minhaloja.com.br`, `advera.com.br` | Containers legados v2 — use o domínio real |
| Metrito Tracking Code (v3) | `MTC-AB12` | Containers v3 — visível na sidebar da plataforma, na página de Tracking |

> [!TIP]
>
> O **Metrito Tracking Code** (MTC) é a forma mais fácil de identificar containers v3. Ele aparece diretamente na sidebar da plataforma e é curto e fácil de copiar.

### Exemplos de chamada

**Por ObjectId:**

```bash
curl https://api.metrito.com/v3/tracking/containers/64a1b2c3d4e5f6a7b8c9d0e1 \
  -H "Authorization: Bearer mtk_live_..."
```

**Por domínio (v2):**

```bash
curl https://api.metrito.com/v3/tracking/containers/minhaloja.com.br \
  -H "Authorization: Bearer mtk_live_..."
```

**Por Metrito Tracking Code (v3):**

```bash
curl https://api.metrito.com/v3/tracking/containers/MTC-AB12 \
  -H "Authorization: Bearer mtk_live_..."
```


# Rate Limits
Source: https://docs.metrito.com/api-reference/rate-limits

Limites de requisição, headers e como lidar com throttling

Todas as rotas do Metrito possuem rate limiting para garantir estabilidade e uso justo da plataforma.

## Limites por Tier

| Tier | Limite | Janela |
| - | - | - |
| API Key padrão | 120 req | 1 minuto |
| Growth | 300 req | 1 minuto |
| Enterprise | 1.000 req | 1 minuto |

## Headers de Resposta

Toda resposta das rotas `/v3/` inclui headers de rate limit:

| Header | Descrição |
| - | - |
| `X-RateLimit-Limit` | Limite máximo de requisições na janela |
| `X-RateLimit-Remaining` | Requisições restantes na janela atual |
| `X-RateLimit-Reset` | Timestamp Unix de quando a janela reseta |
| `Retry-After` | Segundos até poder tentar novamente (apenas em 429) |

## Lidando com Rate Limiting

Quando o limite é excedido, a API retorna `429 Too Many Requests`:

```json theme={null}
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Maximum 120 requests per 60s.",
    "request_id": "req_abc123"
  }
}
```

**Recomendações:**

1. Respeite o header `Retry-After` antes de tentar novamente
2. Implemente backoff exponencial para retries
3. Agrupe múltiplas consultas em uma única chamada quando possível (ex: multiple fields em `POST /v3/query`)
4. Cache respostas que não mudam frequentemente (`GET /v3/fields`)

***

## Request ID

Toda resposta inclui o header `X-Request-Id`. Use este ID ao entrar em contato com o suporte.

```
X-Request-Id: req_k8mN2pQ4rT6wX1
```

***

## Idempotência

Endpoints de escrita (`POST /v3/tracking/events`, `POST /v3/tracking/containers/:id/events`) suportam o header `Idempotency-Key`.

```bash theme={null}
curl -X POST https://api.metrito.com/v3/tracking/events \
  -H "Authorization: Bearer mtk_live_abc123..." \
  -H "Idempotency-Key: meu-evento-unico-123" \
  -H "Content-Type: application/json" \
  -d '{ "config": { "name": "Purchase" } }'
```

| Comportamento | Descrição |
| - | - |
| Primeira chamada | Processa normalmente e armazena resultado |
| Chamada repetida (mesmo key, 24h) | Retorna resultado armazenado com header `X-Idempotent-Replayed: true` |
| Após 24h | Key expira, chamada é processada novamente |

> [!WARNING]
>
> O `Idempotency-Key` é vinculado à API key. Chaves diferentes podem usar o mesmo valor sem conflito.

***

## Formato de Erro Padronizado

Todas as rotas `/v3/` retornam erros no formato:

```json theme={null}
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "request_id": "req_abc123"
  }
}
```

### Tipos de Erro

| Tipo | HTTP Status | Descrição |
| - | - | - |
| `authentication_error` | 401 | Credencial ausente, inválida ou expirada |
| `authorization_error` | 403 | Permissão insuficiente (escopo) |
| `validation_error` | 400 | Parâmetro ausente ou inválido |
| `not_found_error` | 404 | Recurso não encontrado |
| `rate_limit_error` | 429 | Limite de requisições excedido |
| `api_error` | 500 | Erro interno do servidor |

### Códigos de Erro

| Código | Descrição |
| - | - |
| `invalid_api_key` | API key inválida ou revogada |
| `expired_api_key` | API key expirada |
| `insufficient_scope` | API key não possui o escopo necessário |
| `rate_limit_exceeded` | Limite de requisições excedido |
| `invalid_parameter` | Parâmetro de request inválido |
| `missing_parameter` | Parâmetro obrigatório ausente |
| `resource_not_found` | Recurso não encontrado |
| `idempotency_conflict` | Conflito de idempotência |
| `internal_error` | Erro interno |


# Webhook de Pedido
Source: https://docs.metrito.com/api-reference/webhook-de-pedidotransação

/openapi/tracking.yaml post /v2/tracking/generic
Webhook genérico para receber eventos de pedido/transação de qualquer plataforma de checkout, ERP ou sistema customizado.

O parâmetro `k` na query string identifica e autentica a requisição. Nenhum header `Authorization` é necessário.

O Metrito irá:
- Fazer **upsert** do registro da transação usando `transaction.id` como chave única
- **Detectar o tipo de evento** automaticamente pelo campo `status`
- **Disparar conversão de Compra** para a Meta Conversion API quando `status = "approved"`
- **Associar a transação a um lead rastreado** via UTM, e-mail ou telefone


## Autenticação

O parâmetro `k` na query string identifica e autentica a requisição.

**Onde encontrar sua chave:** No painel do Metrito, acesse **Conexões → Adicionar Conexão → Personalizado**. A URL completa do webhook (incluindo seu `k`) é exibida após a criação.

## Valores Monetários

Todos os valores monetários devem ser enviados como **inteiros em centavos**.

| Campo | Exemplo (BRL) | Valor Correto |
| - | - | - |
| `transaction.value` | R\$ 199,80 | `19980` |
| `transaction.commission_value` | R\$ 29,97 | `2997` |

## Status de Transação

| Valor | Dispara Compra Meta? |
| - | - |
| `pending` | Não |
| `approved` | **Sim** |
| `failed` | Não |
| `refunded` | Não |
| `chargeback` | Não |


# Configurações do projeto
Source: https://docs.metrito.com/conceitos/configuracoes-do-projeto

Defina nome, logo, moeda padrão e fuso horário do seu projeto no Metrito.

## Por que configurar o projeto?

As configurações do projeto definem como os seus dados são **exibidos e interpretados**. Moeda e fuso horário, em especial, afetam todos os relatórios — então vale a pena acertá-los logo no início.

Acesse as configurações pelo ícone de **engrenagem** na barra lateral, na seção de configurações do projeto.

## Identidade do projeto

**1. Nome do projeto**

É como o projeto aparece no seletor de projetos e nos relatórios compartilhados. Use um nome claro — o nome da marca, do cliente ou do produto.

**2. Logo do projeto**

A imagem que identifica o projeto na plataforma e nos dashboards compartilhados. Use uma imagem quadrada e de boa resolução para um visual mais profissional, principalmente ao [compartilhar dashboards](/dashboard/compartilhamento) com clientes.

## Moeda padrão

A **moeda padrão** é a moeda em que os valores do projeto são exibidos — faturamento, gasto em anúncios, ticket médio e afins.

> [!NOTE]
>
> A moeda padrão do projeto é diferente da moeda de cada integração. Cada checkout/conta de anúncio tem a sua própria moeda de origem; o Metrito converte os valores para a moeda padrão do projeto na hora de mostrar os relatórios. Você também pode trocar a moeda de exibição pontualmente no topo do dashboard.

Escolha a moeda que representa a operação do projeto (ex.: `BRL` para operações no Brasil, `USD` para operações internacionais).

## Fuso horário padrão

O **fuso horário** define como os dados são agrupados por dia, semana e mês. Ele afeta diretamente os filtros de data e a leitura de qualquer relatório.

> [!WARNING]
>
> Configurar o fuso errado é uma das causas mais comuns de "os números não batem". Se o seu negócio opera no horário de Brasília, use **(GMT-03:00) America/Sao\_Paulo**. Uma venda feita às 23h pode cair no dia seguinte se o fuso estiver incorreto.

O fuso aparece, por exemplo, no seletor de datas do dashboard, indicando em qual horário o período está sendo calculado.

## Checklist de configuração inicial

Antes de começar a usar o projeto para valer, confira:

* [ ] **Nome** e **logo** definidos
* [ ] **Moeda padrão** correta para a operação
* [ ] **Fuso horário** correspondente ao seu negócio
* [ ] Primeiras [integrações](/integracoes/overview) conectadas
* [ ] [Container de rastreamento](/quickstart) instalado (se aplicável)

## Próximos passos

> **[Conectar integrações](/integracoes/overview)**
>
> Traga seus dados de anúncios e vendas para o projeto.

> **[Montar seu dashboard](/dashboard/overview)**
>
> Visualize as métricas do projeto em um painel personalizado.


# Organizações
Source: https://docs.metrito.com/conceitos/organizacoes

O que é uma organização no Metrito e como ela agrupa seus projetos, integrações e membros.

## O que é uma organização?

A **organização** é o nível mais alto da estrutura do Metrito. É a conta da sua empresa — o "guarda-chuva" que reúne tudo: seus projetos, suas integrações, seus membros de equipe e o seu plano de assinatura.

Pense na hierarquia assim:

```
Organização (sua empresa)
 └── Projeto (uma marca, um cliente, um produto)
      └── Integrações, dashboards, campanhas, vendas e leads
```

> [!NOTE]
>
> Toda conta tem pelo menos uma organização. Se você gerencia mais de uma empresa ou atende vários clientes, pode ter várias organizações separadas — cada uma com sua própria cobrança e seus próprios membros.

## O que vive dentro de uma organização?

| Recurso | Descrição |
| - | - |
| **Projetos** | Cada marca, cliente ou produto que você acompanha. Veja [Projetos](/conceitos/projetos). |
| **Integrações** | Contas de anúncio, checkouts e canais conectados. Podem ser **compartilhadas entre projetos** da mesma organização. |
| **Membros** | As pessoas com acesso. Você convida sua equipe e define o que cada um pode ver e fazer. |
| **Plano e cobrança** | A assinatura, os limites de uso e o faturamento ficam no nível da organização. |

## Quando criar mais de uma organização?

Na maioria dos casos, **uma organização basta** — você cria vários projetos dentro dela.

Crie organizações separadas apenas quando os contextos forem realmente independentes, por exemplo:

* Você é uma **agência** e quer manter a cobrança e os acessos de cada cliente totalmente isolados.
* Você tem **empresas diferentes** com equipes que não devem se cruzar.

> [!TIP]
>
> Se a sua dúvida é apenas "como separo a marca A da marca B?", a resposta normalmente é **criar dois projetos** dentro da mesma organização — não duas organizações. Projetos compartilham o plano e permitem reaproveitar integrações.

## Próximos passos

> **[Projetos](/conceitos/projetos)**
>
> Entenda o que é um projeto e como organizar os seus.

> **[Compartilhar integrações](/integracoes/compartilhar-integracoes)**
>
> Reaproveite uma mesma conexão em vários projetos da organização.


# Projetos
Source: https://docs.metrito.com/conceitos/projetos

O que é um projeto no Metrito, para que serve e como organizar os seus de forma eficiente.

## O que é um projeto?

Um **projeto** é o espaço de trabalho de uma marca, produto ou cliente dentro da sua [organização](/conceitos/organizacoes). É onde os dados ganham contexto: cada dashboard, campanha, venda, lead e integração pertence a um projeto.

Quando você entra na plataforma, está sempre **dentro de um projeto**. O seletor no topo da tela mostra o projeto atual e permite alternar entre todos os que você tem acesso.

Clique no nome do projeto ("**Clique para ver todos os projetos**") para trocar de projeto ou criar um novo.

O seletor de projetos fica no topo da plataforma.

## Para que servem os projetos?

Projetos servem para **isolar e organizar** os dados. Tudo o que pertence a um projeto fica contido nele:

* Os **dashboards** que você monta
* As **integrações** que alimentam aquele negócio (contas de anúncio, checkouts, WhatsApp)
* As telas de **campanhas**, **vendas** e **leads**
* As configurações de **rastreamento** (container de pixel, conversões)

Dados de projetos diferentes **nunca se misturam** em um relatório. Se você quer comparar duas marcas, faz isso trocando de projeto — não somando os números por engano.

## Como organizar seus projetos

Não existe uma regra única, mas estes são os modelos mais comuns:

> **Um projeto por marca**
>
> O modelo mais comum para quem tem o próprio negócio. Cada loja/marca vira um projeto.

> **Um projeto por cliente**
>
> Ideal para agências e gestores de tráfego. Cada cliente é um projeto isolado.

> **Um projeto por produto**
>
> Útil quando produtos têm operações, checkouts e públicos bem distintos.

> **Por ambiente / mercado**
>
> Separe operações em países ou moedas diferentes em projetos próprios.

> [!WARNING]
>
> Evite jogar **tudo em um único projeto** se as operações forem realmente distintas (moedas, fusos ou clientes diferentes). Misturar contextos atrapalha a leitura dos números — especialmente moeda e fuso horário, que são definidos **por projeto**.

## E os dados compartilhados?

Embora os dados de cada projeto sejam isolados, as **integrações podem ser compartilhadas** entre projetos da mesma organização. Assim, uma conta de anúncio conectada uma única vez pode alimentar mais de um projeto — sem precisar reconectar.

Veja [Compartilhar integrações](/integracoes/compartilhar-integracoes) para entender quando e por que fazer isso.

## Próximos passos

> **[Configurações do projeto](/conceitos/configuracoes-do-projeto)**
>
> Defina nome, logo, moeda padrão e fuso horário.

> **[Integrações](/integracoes/overview)**
>
> Conecte as fontes de dados que alimentam o projeto.


# Builder de dashboard
Source: https://docs.metrito.com/dashboard/builder

Como montar, configurar e organizar os widgets do seu dashboard no Metrito.

## O que é o builder?

O **builder** é o modo de edição do dashboard. É onde você arrasta widgets para o painel, configura cada um deles, reorganiza o layout e salva o resultado.

Para abrir o builder, clique em **Editar** (ícone de lápis) ao lado do nome do dashboard.

## A barra lateral: Templates e Widgets

No builder, uma barra lateral à esquerda traz duas abas:

> **Templates**
>
> Layouts prontos para começar rápido. Aplique um template e ajuste a partir dele. Veja [Templates](/dashboard/templates).

> **Widgets**
>
> A galeria de widgets disponíveis, organizada por categoria (Principais, Gráficos, Úteis, Especiais). Use a busca para encontrar rápido.

As categorias de widgets incluem:

* **Principais** — Card de Métrica, Tabela, Funil de Conversão
* **Gráficos** — Linha, Barras, Área, Pizza
* **Úteis** — Divisor
* **Especiais** — Vendas por Horário, Vendas por Dia da Semana, Taxa de Aprovação

Veja a lista completa em [Widgets disponíveis](/dashboard/widgets).

## Adicionar e organizar widgets

**1. Adicione um widget**

Clique no widget desejado na barra lateral. Ele é inserido no painel.

**2. Reposicione**

Arraste o widget para a posição desejada no grid.

**3. Redimensione**

Use a alça no canto inferior direito do widget para ajustar largura e altura.

## Configurar um widget

Ao passar o mouse sobre um widget no builder, aparecem três ações no canto superior:

| Ícone | Ação |
| - | - |
| **Duplicar** | Cria uma cópia do widget com as mesmas configurações. |
| **Configurar** (engrenagem) | Abre as opções do widget: métrica exibida, formato, cores, agrupamento e mais. |
| **Excluir** (lixeira) | Remove o widget do dashboard. |

> [!TIP]
>
> Em **Configurar** você define o que cada widget mostra — por exemplo, qual métrica um Card de Métrica exibe, ou quais colunas aparecem em uma Tabela. É aqui que o dashboard ganha a cara do seu negócio.

## Salvar e visualizar

O builder mostra o status de salvamento no topo (ex.: **Salvo**). Use os botões de **desfazer/refazer** para voltar atrás em mudanças e **Visualizar** para sair da edição e ver o painel como ele ficará.

> [!NOTE]
>
> Gostou do layout e quer reutilizá-lo em outros projetos? Salve-o como um [template](/dashboard/templates).

## Próximos passos

> **[Widgets disponíveis](/dashboard/widgets)**
>
> Veja cada tipo de widget e para que serve.

> **[Templates](/dashboard/templates)**
>
> Comece de um layout pronto ou salve o seu.


# Compartilhar o dashboard
Source: https://docs.metrito.com/dashboard/compartilhamento

Compartilhe seu dashboard por link externo com senha ou incorpore via embed (iframe).

O Metrito permite compartilhar um dashboard sem que a outra pessoa precise ter conta na plataforma. Clique em **Compartilhar** no topo do painel para abrir as opções. Há dois modos de distribuição.

> **Link externo (com senha)**
>
> Um link protegido por senha. Qualquer pessoa com o link e a senha consegue visualizar o painel.

> **Embed (token de acesso)**
>
> Um código `<iframe>` para incorporar o dashboard em sistemas externos. O acesso é controlado por um token gerado automaticamente.

## Link externo (com senha)

Ideal para enviar o painel a um cliente ou sócio de forma rápida e segura.

**1. Selecione “Link externo”**

No modal **Compartilhar Dashboard**, escolha o modo **Link externo**.

**2. Copie o link de acesso**

O Metrito gera uma URL no formato `https://app.metrito.com/d/XXXXXXXX`. Use o botão de copiar.

**3. Defina a senha de acesso**

Informe uma senha obrigatória (mínimo de 4 caracteres) e clique em **Salvar**. Sem a senha, o link não abre.

> [!WARNING]
>
> Quem tiver o link **e** a senha poderá ver o dashboard. Compartilhe a senha por um canal separado do link e troque-a se precisar revogar o acesso.

## Embed (incorporar via iframe)

Use o embed para exibir o dashboard dentro de outro sistema — um portal de cliente, uma área de membros ou uma intranet — sem pedir senha ao visitante.

**1. Selecione “Embed”**

No modal de compartilhamento, escolha o modo **Embed**.

**2. Habilite o embed**

Ative a opção **Habilitar embed**. Isso gera um **token único** que permite o acesso sem senha.

**3. Copie o código de incorporação**

O Metrito monta um `<iframe>` pronto. Cole-o na página onde quer exibir o painel:

```html theme={null}
<iframe
  src="https://app.metrito.com/embed/SEU_DASHBOARD?token=SEU_TOKEN"
  width="100%"
  height="600"
  frameborder="0"
></iframe>
```

> [!WARNING]
>
> Ao **desabilitar o embed**, o token é revogado e os iframes existentes param de funcionar. Reabilitar gera um novo token — e o código antigo deixa de valer.

## Qual modo escolher?

| Use **Link externo** quando… | Use **Embed** quando… |
| - | - |
| Quer enviar o painel a uma pessoa específica | Quer exibir o painel dentro de outro site/sistema |
| Prefere proteger com senha | Quer acesso sem senha, controlado por token |
| É um compartilhamento pontual | É uma integração permanente em outra plataforma |

## Próximos passos

> **[Filtros e granularidade](/dashboard/filtros-e-granularidade)**
>
> Ajuste a visão antes de compartilhar.

> **[Configurações do projeto](/conceitos/configuracoes-do-projeto)**
>
> Defina logo e nome — eles aparecem no painel compartilhado.


# Filtros e granularidade
Source: https://docs.metrito.com/dashboard/filtros-e-granularidade

Como filtrar por período, aplicar filtros de dados e ajustar a granularidade do dashboard.

Os controles no topo do dashboard recortam **todos os widgets** ao mesmo tempo. Esta página cobre os três mais importantes: **período**, **filtros** e **granularidade**.

## Filtrar por período (data)

O seletor de **período** define o intervalo de datas analisado. Ele traz atalhos prontos e a opção de intervalo personalizado:

| Opção | O que mostra |
| - | - |
| **Hoje** | O dia atual. |
| **Ontem** | O dia anterior. |
| **Este mês** | Do dia 1º do mês corrente até hoje. |
| **Este ano** | De 1º de janeiro até hoje. |
| **Últimos 7 dias** | A última semana. |
| **Últimos…** | Janela móvel personalizada (ex.: últimos 30 dias). |
| **Período atual** | O período corrente (ex.: este ano/mês). |
| **Intervalo personalizado** | Escolha a data inicial e final no calendário. |

> [!NOTE]
>
> O período é sempre calculado no **fuso horário do projeto** — exibido no rodapé do seletor (ex.: `(GMT-03:00) America/Sao_Paulo`). Se as datas parecerem "deslocadas", confira o [fuso do projeto](/conceitos/configuracoes-do-projeto).

Depois de escolher, clique em **Aplicar** para atualizar o painel.

## Aplicar filtros de dados

O botão **Filtros** restringe quais dados entram nos widgets. O número ao lado (ex.: **Filtros 1**) indica quantos filtros estão ativos.

Com filtros, você responde perguntas como:

* "Quanto faturei **só com vendas vindas do Facebook**?"
* "Como ficam os números **apenas do produto X**?"
* "E se eu olhar **só as vendas aprovadas**?"

> [!TIP]
>
> Filtros e período se combinam. Você pode, por exemplo, ver "as vendas do produto X, no Facebook, nos últimos 7 dias" aplicando filtro de produto + filtro de fonte + período — tudo ao mesmo tempo.

## Quais dados aparecem no dashboard?

Os widgets refletem os dados que entram no projeto pelas suas [integrações](/integracoes/overview) e pelo [rastreamento](/tracking/overview):

* **Vendas e faturamento** vêm dos checkouts/gateways conectados.
* **Gasto em anúncios, ROAS e ROI** vêm das contas de anúncio conectadas.
* **Cliques, visualizações, cadastros e conversões** vêm do rastreamento (pixel/UTM).

> [!NOTE]
>
> Se um número aparece zerado, normalmente é porque a fonte correspondente ainda não está conectada, está fora do período selecionado, ou foi excluída por um filtro ativo.

## Granularidade

A **granularidade** define como os dados são agrupados no tempo dentro dos gráficos — por hora, dia, semana ou mês.

No modo **`auto`** (padrão), o Metrito escolhe a melhor granularidade para o período selecionado: períodos curtos tendem a ser agrupados por dia; períodos longos, por semana ou mês. Você pode fixar uma granularidade manualmente quando quiser uma leitura específica.

> [!TIP]
>
> Use uma granularidade **menor** (dia/hora) para enxergar detalhes de períodos curtos e uma **maior** (semana/mês) para visualizar tendências de longo prazo sem ruído.

## Moeda e atualização

* **Moeda** — troca a moeda de exibição dos valores (ex.: BRL). A moeda padrão vem das [configurações do projeto](/conceitos/configuracoes-do-projeto).
* **Atualizar** — recarrega o painel com o período, os filtros e a granularidade atuais.

## Próximos passos

> **[Widgets disponíveis](/dashboard/widgets)**
>
> Veja o que cada widget pode exibir.

> **[Compartilhar dashboard](/dashboard/compartilhamento)**
>
> Compartilhe a visão filtrada com seu time ou cliente.


# Visão geral do Dashboard
Source: https://docs.metrito.com/dashboard/overview

O que é um dashboard no Metrito e como funciona a barra de controles do painel.

## O que é um dashboard?

O **dashboard** é o painel onde você acompanha as métricas do seu projeto em um só lugar: faturamento, gasto em anúncios, ROAS, lucro, conversões, vendas por produto e muito mais.

Cada projeto pode ter o seu dashboard, montado com os **widgets** que fizerem sentido para o seu negócio. Você decide o que aparece, em que ordem e como cada número é calculado.

> [!TIP]
>
> O dashboard é totalmente personalizável. Comece a partir de um [template](/dashboard/templates) pronto e ajuste, ou monte do zero no [builder](/dashboard/builder).

## Anatomia do dashboard

No topo do dashboard fica a **barra de controles**, que define o que e como você está vendo. Ela vale para o painel inteiro:

| Controle | O que faz |
| - | - |
| **Compartilhar** | Gera um link externo (com senha) ou um código de embed para incorporar o painel. Veja [Compartilhamento](/dashboard/compartilhamento). |
| **Filtros** | Restringe os dados exibidos (por fonte, produto, status, etc.). O número ao lado indica quantos filtros estão ativos. Veja [Filtros e granularidade](/dashboard/filtros-e-granularidade). |
| **Período (data)** | Define o intervalo de datas analisado (ex.: "Este mês", "Últimos 7 dias"). |
| **Granularidade** | Como os dados são agrupados no tempo (`auto`, por dia, semana, mês). |
| **Moeda** | A moeda de exibição dos valores (ex.: BRL). |
| **Atualizar** | Recarrega os dados do painel com os filtros e o período atuais. |

> [!NOTE]
>
> As alterações na barra de controles (período, filtros, moeda, granularidade) afetam **todos os widgets** ao mesmo tempo. É a forma rápida de "recortar" a mesma visão por outro ângulo.

## Modo de edição

O botão **Editar** (ícone de lápis ao lado do nome do dashboard) abre o **builder**, onde você adiciona, remove, reorganiza e configura os widgets. Ao terminar, é só salvar e voltar para o modo de visualização.

```mermaid theme={null}
flowchart LR
    view["Modo de visualização<br/>(acompanhar métricas)"] -->|Editar| build["Builder<br/>(montar e configurar widgets)"]
    build -->|Salvar| view
    view -->|Compartilhar| share["Link externo / Embed"]
```

## Próximos passos

> **[Builder de dashboard](/dashboard/builder)**
>
> Adicione, configure e organize os widgets do seu painel.

> **[Widgets disponíveis](/dashboard/widgets)**
>
> Conheça todos os tipos de widget que você pode usar.

> **[Filtros e granularidade](/dashboard/filtros-e-granularidade)**
>
> Recorte os dados por período, fonte, produto e mais.

> **[Compartilhar dashboard](/dashboard/compartilhamento)**
>
> Envie o painel por link com senha ou incorpore via iframe.


# Templates de dashboard
Source: https://docs.metrito.com/dashboard/templates

O que são templates, como aplicar um pronto e como salvar o seu próprio layout.

## O que é um template?

Um **template** é um layout de dashboard pronto — um conjunto de widgets já posicionados e configurados. Em vez de montar tudo do zero, você aplica um template e ajusta a partir dele.

Templates são úteis para:

* **Começar rápido** em um projeto novo.
* **Padronizar** o painel entre vários projetos ou clientes.
* **Reaproveitar** um layout que deu certo.

## Aplicar um template

**1. Abra o builder**

Clique em **Editar** no dashboard para entrar no modo de edição.

**2. Vá até a aba Templates**

Na barra lateral à esquerda, selecione a aba **Templates**.

**3. Escolha um template**

Selecione o layout desejado. Os widgets são adicionados ao painel já configurados.

**4. Ajuste e salve**

Reorganize, configure ou remova widgets conforme a sua necessidade e salve.

## Salvar seu próprio template

Montou um layout que funciona bem e quer reutilizá-lo? Salve-o como template para aplicar em outros projetos sem refazer o trabalho.

> [!TIP]
>
> Para agências e quem gerencia vários projetos, salvar um template é a forma mais rápida de entregar um dashboard consistente para cada novo cliente.

## Próximos passos

> **[Builder de dashboard](/dashboard/builder)**
>
> Ajuste o template aplicado adicionando e configurando widgets.

> **[Compartilhar dashboard](/dashboard/compartilhamento)**
>
> Entregue o painel para o cliente por link ou embed.


# Widgets disponíveis
Source: https://docs.metrito.com/dashboard/widgets

Conheça todos os widgets que você pode adicionar ao dashboard do Metrito e quando usar cada um.

## O que é um widget?

Um **widget** é um bloco do dashboard que exibe um dado ou um conjunto de dados. Cada widget é configurável: você escolhe a métrica, o formato e o recorte. Combine vários widgets para montar a visão ideal do seu negócio.

Os widgets ficam organizados por categoria na aba **Widgets** do [builder](/dashboard/builder).

## Principais

> **Card de Métrica**
>
> Exibe um único número em destaque — faturamento, ROAS, lucro, número de vendas, etc. É o widget mais usado do dashboard.

> **Tabela**
>
> Mostra dados em linhas e colunas, como vendas por fonte ou por produto. Ótimo para comparar itens lado a lado.

> **Funil de Conversão**
>
> Visualiza a jornada por etapas — cliques → visualizações → cadastros → checkout → vendas — com a taxa de conversão entre elas.

## Gráficos

> **Gráfico de Linha**
>
> Evolução de uma métrica ao longo do tempo. Ideal para acompanhar tendências (faturamento por dia, por exemplo).

> **Gráfico de Barras**
>
> Compara valores entre categorias ou períodos.

> **Gráfico de Área**
>
> Como o de linha, mas com a área preenchida — útil para enfatizar volume acumulado.

> **Gráfico de Pizza**
>
> Mostra a participação de cada parte no total, como vendas por produto ou por método de pagamento.

## Úteis

> **Divisor**
>
> Um separador visual para organizar o painel em seções. Não exibe dados — serve para dar respiro e estrutura ao layout.

## Especiais

> **Vendas por Horário**
>
> Distribui as vendas pelos horários do dia. Útil para identificar os melhores horários de conversão.

> **Vendas por Dia da Semana**
>
> Mostra em quais dias da semana você mais vende.

> **Taxa de Aprovação**
>
> Acompanha a taxa de aprovação por método de pagamento (cartão, Pix, boleto).

> [!TIP]
>
> Cada widget é configurado individualmente pelo ícone de **engrenagem** no [builder](/dashboard/builder). Lá você escolhe a métrica, o formato e o recorte de dados.

## Próximos passos

> **[Builder de dashboard](/dashboard/builder)**
>
> Adicione e configure esses widgets no seu painel.

> **[Filtros e granularidade](/dashboard/filtros-e-granularidade)**
>
> Recorte o que os widgets exibem por período e por filtros.


# Documentação Metrito
Source: https://docs.metrito.com/index

Rastreie cada ponto de contato, atribua cada conversão e unifique a jornada de cada cliente.

## Bem-vindo ao Metrito

O Metrito é uma plataforma de atribuição e rastreamento de marketing que conecta suas campanhas de anúncios à receita real. Do primeiro acesso anônimo até a compra final, o Metrito rastreia e atribui cada etapa da jornada do cliente — web, WhatsApp e integrações via API.

Esta é a base de conhecimento oficial. Use os guias abaixo para dominar a plataforma do zero.

> **[Comece em 5 minutos](/quickstart)**
>
> Instale o rastreamento, configure seus UTMs e comece a ver dados.

## Conceitos fundamentais

Entenda como o Metrito é organizado antes de mergulhar nas telas.

> **[Organizações](/conceitos/organizacoes)**
>
> O nível mais alto: sua empresa, seus membros e seu plano.

> **[Projetos](/conceitos/projetos)**
>
> Cada marca, cliente ou produto que você acompanha.

> **[Configurações do projeto](/conceitos/configuracoes-do-projeto)**
>
> Nome, logo, moeda padrão e fuso horário.

## Dashboard

Monte painéis personalizados para acompanhar suas métricas.

> **[Visão geral do Dashboard](/dashboard/overview)**
>
> A barra de controles e como o painel funciona.

> **[Builder e widgets](/dashboard/builder)**
>
> Adicione, configure e organize os widgets.

> **[Filtros e granularidade](/dashboard/filtros-e-granularidade)**
>
> Recorte os dados por período, fonte e produto.

> **[Compartilhar dashboard](/dashboard/compartilhamento)**
>
> Link com senha ou embed via iframe.

## Análise de dados

As telas onde você acompanha desempenho e resultados.

> **[Campanhas](/analise/campanhas)**
>
> Desempenho dos anúncios cruzado com resultados de negócio.

> **[Vendas](/analise/vendas)**
>
> Todas as transações e pedidos do projeto.

> **[Leads](/analise/leads)**
>
> Os contatos identificados ao longo da jornada.

## Integrações

Conecte as fontes que alimentam toda a plataforma.

> **[O que são integrações](/integracoes/overview)**
>
> O conceito de fonte de entrada, status e a coluna tracking.

> **[Adicionar uma integração](/integracoes/adicionar-integracao)**
>
> Conecte contas de anúncio, checkouts e WhatsApp.

> **[Checkouts e comissões](/integracoes/checkouts-e-comissoes)**
>
> Configure moeda, fuso e tipo de comissão.

> **[Integração personalizada](/integracoes/integracao-personalizada)**
>
> Envie pedidos de qualquer sistema próprio.

## Rastreamento

A base da atribuição: pixel, UTMs e jornada do cliente.

> **[Visão geral do rastreamento](/tracking/overview)**
>
> Projetos, eventos, sessões e identificação de usuários.

> **[Instalação do pixel web](/tracking/web-setup)**
>
> Instale o script do Metrito no seu site.

> **[Configuração de UTMs](/tracking/utm-configuration)**
>
> Atribuição completa de campanhas, conjuntos e criativos.

> **[Rastreamento via WhatsApp](/tracking/whatsapp)**
>
> Conecte conversas do WhatsApp às sessões web.


# Adicionar uma integração
Source: https://docs.metrito.com/integracoes/adicionar-integracao

Passo a passo para conectar uma nova fonte de dados ao seu projeto no Metrito.

## Como adicionar

Adicionar uma integração no Metrito é simples e leva poucos cliques.

**1. Acesse a tela de Integrações**

No menu lateral, abra a seção de **Integrações**.

**2. Clique em “Adicionar Integração”**

O botão verde fica no **canto superior direito** da tela.

**3. Escolha o tipo de integração**

Um modal abre com todas as fontes disponíveis, organizadas por categoria. Use os filtros rápidos para encontrar mais fácil:

* **Tráfego** — plataformas de anúncios (ex.: Meta Ads)
* **Pagamentos** — checkouts e gateways (ex.: Shopify, Hotmart, Kiwify, Eduzz, Stripe)
* **Mensagens** — canais de mensageria (ex.: WhatsApp)

**4. Siga o fluxo de conexão**

Cada fonte tem o seu fluxo: autorização (OAuth) para contas de anúncio, webhook para checkouts e, no WhatsApp, QR Code (Metrito API) ou a Cloud API oficial. Conclua os passos indicados.

> [!TIP]
>
> Não encontrou o seu checkout na lista? Use a [**Integração personalizada**](/integracoes/integracao-personalizada) — ela aceita pedidos de qualquer sistema, desde que sigam o formato esperado pelo Metrito.

## Depois de conectar

Assim que a conexão é criada, ela aparece na tabela de [Integrações](/integracoes/overview) com seu **status**, a coluna **tracking**, **timezone**, **moeda** e **comissão**. A partir daí, os dados começam a alimentar o dashboard e as telas de campanhas, vendas e leads.

## Próximos passos

> **[Contas de anúncio](/integracoes/contas-de-anuncio)**
>
> Detalhes da conexão com Meta Ads e seus status.

> **[Checkouts e comissões](/integracoes/checkouts-e-comissoes)**
>
> Configure comissão, moeda e fuso da conexão de vendas.

> **[WhatsApp](/integracoes/whatsapp)**
>
> Conecte um número pela Metrito API (QR Code) ou pela Cloud API.

> **[Integração personalizada](/integracoes/integracao-personalizada)**
>
> Conecte qualquer sistema próprio.


# ApplyFy
Source: https://docs.metrito.com/integracoes/applyfy

Conecte a ApplyFy ao Metrito por webhook para receber vendas, reembolsos e chargebacks com a comissão real do produtor.

## Como funciona

A ApplyFy envia cada venda para o Metrito por **webhook**. O Metrito gera uma URL exclusiva para a sua conexão, você cadastra essa URL na ApplyFy e, a partir daí, cada venda aparece em [Vendas](/analise/vendas) com o status atualizado.

São três partes:

1. Criar a conexão no Metrito e copiar a URL do webhook.
2. Cadastrar a URL na ApplyFy.
3. Ligar a conexão ao container em **Rastreamento → Checkouts**, se quiser disparar o `Purchase` nos pixels.

## 1. Crie a conexão no Metrito

**1. Abra Adicionar Integração**

No menu lateral, abra **Integrações** e clique em **Adicionar Integração**.

**2. Escolha ApplyFy**

No modal **Integrações disponíveis**, use o filtro **Pagamentos** (ou busque por "ApplyFy") e selecione **ApplyFy**.

**3. Dê um nome à conexão**

Em **Nome da conexão**, use um nome que identifique a conta (ex.: "ApplyFy Principal") e clique em **Próximo**.

**4. Escolha o modo de valor**

Em **Modo de valor**, escolha **Valor líquido** (o que você recebe de fato, já sem taxas e comissões) ou **Valor total da venda** (o valor cheio pago pelo cliente). Veja [Checkouts e comissões](/integracoes/checkouts-e-comissoes) para decidir.

**5. Confira o fuso horário**

Em **Fuso horário**, mantenha o padrão (horário de São Paulo) ou escolha o fuso da sua operação.

**6. Copie a URL do webhook**

No passo **Cadastrar webhook**, o Metrito cria a conexão e mostra a URL dela, no formato:

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

Clique em **Copiar URL do webhook**. Depois clique em **Próximo** e, na tela **Conexão criada**, em **Concluir**.

> [!WARNING]
>
> Trate essa URL como uma senha: quem tiver o endereço consegue enviar vendas para a sua conexão. Cadastre só na ApplyFy e não publique.

## 2. Cadastre a URL na ApplyFy

**1. Abra os webhooks**

No painel da ApplyFy, abra a área de webhooks (ou postback) da sua conta.

**2. Crie um webhook**

Crie um novo webhook e cole a URL que você copiou no Metrito.

**3. Escolha os eventos**

Marque todos os eventos de venda: criada, paga, recusada, expirada, reembolsada e chargeback. Eventos que não são de venda são ignorados pelo Metrito.

**4. Salve**

Salve o webhook. As próximas vendas já chegam ao Metrito.

## 3. Ligue a ApplyFy ao rastreamento

Com a conexão criada, as vendas já aparecem em [Vendas](/analise/vendas). Para cada pagamento aprovado também disparar o `Purchase` nos pixels:

**1. Abra os checkouts do container**

No menu lateral, abra **Rastreamento** e vá à seção **Checkouts**.

**2. Ative a conexão**

No card **Conectar Checkouts**, encontre a conexão da ApplyFy (use a busca **Buscar por 'nome' ou 'gateway'**) e **ligue o interruptor** dela.

Veja [Checkouts](/tracking/checkouts).

## Como o Metrito lê as vendas da ApplyFy

* **O valor líquido é a comissão que a ApplyFy repassa** a você em cada venda, já sem taxas.
* **Reembolso e chargeback atualizam a venda** sem nunca devolvê-la para pendente.
* **Meios de pagamento:** PIX, cartão e boleto.

## Próximos passos

> **[Checkouts e comissões](/integracoes/checkouts-e-comissoes)**
>
> Entenda o modo de valor e como o Metrito calcula o valor líquido.

> **[Vendas](/analise/vendas)**
>
> Acompanhe as compras e a receita atribuída.


# Attract Pay
Source: https://docs.metrito.com/integracoes/attract

Conecte a Attract Pay ao Metrito por webhook para receber vendas, MED, reembolsos e chargebacks.

## Como funciona

A Attract Pay envia cada venda para o Metrito por **webhook**. O Metrito gera uma URL exclusiva para a sua conexão, você cadastra essa URL na Attract Pay e, a partir daí, cada venda aparece em [Vendas](/analise/vendas) com o status atualizado.

São três partes:

1. Criar a conexão no Metrito e copiar a URL do webhook.
2. Cadastrar a URL na Attract Pay.
3. Ligar a conexão ao container em **Rastreamento → Checkouts**, se quiser disparar o `Purchase` nos pixels.

## 1. Crie a conexão no Metrito

**1. Abra Adicionar Integração**

No menu lateral, abra **Integrações** e clique em **Adicionar Integração**.

**2. Escolha Attract Pay**

No modal **Integrações disponíveis**, use o filtro **Pagamentos** (ou busque por "Attract Pay") e selecione **Attract Pay**.

**3. Dê um nome à conexão**

Em **Nome da conexão**, use um nome que identifique a conta (ex.: "Attract Pay Principal") e clique em **Próximo**.

**4. Escolha o modo de valor**

Em **Modo de valor**, escolha **Valor líquido** (o que você recebe de fato, já sem taxas e comissões) ou **Valor total da venda** (o valor cheio pago pelo cliente). Veja [Checkouts e comissões](/integracoes/checkouts-e-comissoes) para decidir.

**5. Confira o fuso horário**

Em **Fuso horário**, mantenha o padrão (horário de São Paulo) ou escolha o fuso da sua operação.

**6. Copie a URL do webhook**

No passo **Cadastrar webhook**, o Metrito cria a conexão e mostra a URL dela, no formato:

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

Clique em **Copiar URL do webhook**. Depois clique em **Próximo** e, na tela **Conexão criada**, em **Concluir**.

> [!WARNING]
>
> Trate essa URL como uma senha: quem tiver o endereço consegue enviar vendas para a sua conexão. Cadastre só na Attract Pay e não publique.

## 2. Cadastre a URL na Attract Pay

**1. Abra os webhooks**

No painel da Attract Pay, abra a área de webhooks (ou postback) da sua conta.

**2. Crie um webhook**

Crie um novo webhook e cole a URL que você copiou no Metrito.

**3. Escolha os eventos**

Marque todos os eventos de venda: criada, paga, recusada, expirada, reembolsada e chargeback. Eventos que não são de venda são ignorados pelo Metrito.

**4. Salve**

Salve o webhook. As próximas vendas já chegam ao Metrito.

## 3. Ligue a Attract Pay ao rastreamento

Com a conexão criada, as vendas já aparecem em [Vendas](/analise/vendas). Para cada pagamento aprovado também disparar o `Purchase` nos pixels:

**1. Abra os checkouts do container**

No menu lateral, abra **Rastreamento** e vá à seção **Checkouts**.

**2. Ative a conexão**

No card **Conectar Checkouts**, encontre a conexão da Attract Pay (use a busca **Buscar por 'nome' ou 'gateway'**) e **ligue o interruptor** dela.

Veja [Checkouts](/tracking/checkouts).

## Como o Metrito lê as vendas da Attract Pay

* **MED (contestação do PIX) aparece como venda em análise** até a decisão; se virar chargeback ou reembolso, o status muda sozinho.
* **UTMs e parâmetros do checkout** (src, sck e utm\_\*) entram em cada venda.
* **Meios de pagamento:** PIX, cartão e boleto.

## Próximos passos

> **[Checkouts e comissões](/integracoes/checkouts-e-comissoes)**
>
> Entenda o modo de valor e como o Metrito calcula o valor líquido.

> **[Vendas](/analise/vendas)**
>
> Acompanhe as compras e a receita atribuída.


# B4You
Source: https://docs.metrito.com/integracoes/b4you

Conecte a B4You ao Metrito por webhook para receber as vendas, os order bumps e os reembolsos.

## Como funciona

A B4You envia cada venda para o Metrito por **webhook**. O Metrito gera uma URL exclusiva para a sua conexão, você cadastra essa URL na B4You e, a partir daí, cada venda aparece em [Vendas](/analise/vendas) com o status atualizado: PIX gerado, pagamento aprovado, recusado, PIX expirado e reembolso.

São três partes:

1. Criar a conexão no Metrito e copiar a URL do webhook.
2. Cadastrar a URL na B4You.
3. Ligar a conexão ao container em **Rastreamento → Checkouts**, se quiser disparar o `Purchase` nos pixels.

## 1. Crie a conexão no Metrito

**1. Abra Adicionar Integração**

No menu lateral, abra **Integrações** e clique em **Adicionar Integração**.

**2. Escolha B4You**

No modal **Integrações disponíveis**, use o filtro **Pagamentos** (ou busque por "B4You") e selecione **B4You**.

**3. Dê um nome à conexão**

Em **Nome da conexão**, use um nome que identifique a conta (ex.: "B4You Principal") e clique em **Próximo**.

**4. Escolha o modo de valor**

Em **Modo de valor**, escolha entre:

* **Comissão do produtor**: só o que você recebe como produtor (padrão).
* **Valor total**: o preço cheio da venda, sem descontar comissões.
* **Comissão personalizada**: some os tipos que quiser entre **Produtor**, **Coprodutor**, **Afiliado** e **Gerente**.

Veja [Checkouts e comissões](/integracoes/checkouts-e-comissoes) para decidir.

**5. Decida sobre as vendas de afiliados**

A B4You envia para o webhook do produtor todas as vendas do produto, inclusive as feitas por afiliados. Ligue **Ignorar vendas de afiliados** se quiser contar só as suas vendas diretas.

**6. Confira o fuso horário**

Em **Fuso horário**, mantenha o padrão (horário de São Paulo) ou escolha o fuso da sua operação.

**7. Copie a URL do webhook**

No passo **Cadastrar webhook**, o Metrito cria a conexão e mostra a URL dela, no formato:

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

Clique em **Copiar URL do webhook**. Depois clique em **Próximo** e, na tela **Conexão criada**, em **Concluir**.

> [!WARNING]
>
> Trate essa URL como uma senha: quem tiver o endereço consegue enviar vendas para a sua conexão. Cadastre só na B4You e não publique.

## 2. Cadastre a URL na B4You

**1. Abra os webhooks**

No painel da B4You, abra a área de webhooks do seu produto.

**2. Crie um webhook**

Crie um novo webhook e cole a URL que você copiou no Metrito.

**3. Escolha os eventos**

Marque os eventos de venda: pagamento aprovado, PIX gerado, boleto gerado, PIX expirado, pagamento recusado e reembolso. Se marcar também o carrinho abandonado, tudo bem: o Metrito ignora esse evento.

**4. Salve**

Salve o webhook. As próximas vendas já chegam ao Metrito.

## 3. Ligue a B4You ao rastreamento

Com a conexão criada, as vendas já aparecem em [Vendas](/analise/vendas). Para cada pagamento aprovado também disparar o `Purchase` nos pixels:

**1. Abra os checkouts do container**

No menu lateral, abra **Rastreamento** e vá à seção **Checkouts**.

**2. Ative a conexão**

No card **Conectar Checkouts**, encontre a conexão da B4You (use a busca **Buscar por 'nome' ou 'gateway'**) e **ligue o interruptor** dela.

Veja [Checkouts](/tracking/checkouts).

## Como o Metrito lê as vendas da B4You

* **Order bump é uma venda separada.** A B4You manda o produto principal e cada bump como vendas próprias, ligadas pelo mesmo grupo. No Metrito cada uma aparece com o próprio produto e o próprio valor.
* **O valor da venda é o preço do produto**, já com o cupom aplicado e sem os juros do parcelamento no cartão.
* **Assinaturas** ainda não são tratadas como recorrência: cada cobrança entra como uma venda.

## Próximos passos

> **[Checkouts e comissões](/integracoes/checkouts-e-comissoes)**
>
> Entenda o modo de valor e como o Metrito calcula o valor líquido.

> **[Vendas](/analise/vendas)**
>
> Acompanhe as compras e a receita atribuída.


# Checkouts e comissões
Source: https://docs.metrito.com/integracoes/checkouts-e-comissoes

Conecte checkouts e gateways, ative o tracking e escolha o tipo de comissão para ver o valor líquido correto.

## Conexões de checkout

As integrações de **checkout/gateway** trazem as suas vendas para o Metrito via **webhook**. Cada compra registrada vira um pedido na tela de [Vendas](/analise/vendas) e pode alimentar o dashboard.

Exemplos: Hotmart, Shopify, Kiwify, Eduzz, Stripe, e vários outros. Para conectar, use **Adicionar Integração** → categoria **Pagamentos** (veja [Adicionar uma integração](/integracoes/adicionar-integracao)). Para a Hotmart e a B4You, siga o passo a passo em [Hotmart](/integracoes/hotmart) e [B4You](/integracoes/b4you).

## Configurações da conexão

No momento de adicionar (e depois, ao editar a conexão) você define:

| Campo | Para que serve |
| - | - |
| **Tracking** | Toggle. Quando ativado, cada compra aprovada dispara um evento `Purchase` de rastreamento. |
| **Timezone** | O fuso horário usado para os pedidos dessa conexão. |
| **Moeda** | A moeda de origem dos valores recebidos. |
| **Comissão** | Como o Metrito calcula o seu **valor líquido** (ver abaixo). |

## Comissão e valor líquido

O Metrito mostra o **valor líquido** das suas vendas, não apenas o bruto. Isso porque você raramente recebe o valor cheio da compra — o checkout retém taxas, e o valor recebido depende do seu **papel** naquela venda.

> Em uma venda de **R$ 300**, você provavelmente recebe algo como **R$ 280–290**, dependendo da taxa do checkout.

## Modo de valor

Todo checkout pergunta o **modo de valor** no momento de conectar. É a escolha entre registrar o valor cheio da venda ou só o que sobra para você:

| Modo de valor | O que o Metrito registra |
| - | - |
| **Valor total** | O valor cheio pago pelo cliente, sem descontar taxas nem comissões. |
| **Valor líquido** | O que você recebe de fato, já sem taxas e comissões. |

Em checkouts que informam a comissão por papel, o **Valor líquido** se desdobra em duas opções: **Comissão do produtor** (o padrão) ou **Comissão personalizada**, que abre a escolha dos tipos abaixo.

## Tipos de comissão

Quando o checkout informa a comissão por papel, o **tipo de comissão** define qual fatia da venda é a sua:

| Tipo de comissão | Quando usar |
| - | - |
| **Produtor** | Você é o dono do produto. |
| **Co-produtor** | Você participa como co-produtor da oferta. |
| **Afiliado** | Você promove o produto de outra pessoa como afiliado. |

Selecionando mais de um, o valor final é a **soma** dos tipos escolhidos.

> [!NOTE]
>
> As opções variam por checkout — **alguns oferecem mais formatos de comissão do que outros**. As opções disponíveis aparecem no momento de adicionar a conexão (e podem ser ajustadas depois).

> [!TIP]
>
> Escolher a comissão certa é essencial para que **lucro, margem e ROAS** fiquem corretos no dashboard. Se os valores líquidos parecerem altos demais, confira o tipo de comissão configurado na conexão.

## Próximos passos

> **[Tela de Vendas](/analise/vendas)**
>
> Acompanhe os pedidos vindos dos seus checkouts.

> **[Integração personalizada](/integracoes/integracao-personalizada)**
>
> Não achou seu checkout? Envie pedidos por uma fonte personalizada.


# Compartilhar integrações entre projetos
Source: https://docs.metrito.com/integracoes/compartilhar-integracoes

Use uma mesma conexão em vários projetos da organização, sem reconectar.

## Por que compartilhar uma integração?

Uma integração é conectada **uma vez**, mas os seus dados podem ser úteis em **mais de um projeto** da mesma [organização](/conceitos/organizacoes). Em vez de reconectar a mesma conta de anúncio ou checkout em cada projeto, você a **compartilha**.

Compartilhar uma integração faz com que os dados daquela conexão fiquem disponíveis em todos os projetos escolhidos — alimentando os dashboards e as telas de campanhas, vendas e leads de cada um.

## Quando isso é útil

> **Conta de anúncio que atende várias marcas**
>
> Uma mesma conta do Meta roda campanhas de produtos que você acompanha em projetos diferentes.

> **Agência com visões por cliente**
>
> Centralize a conexão e distribua os dados para os projetos de cada cliente.

> **Checkout com múltiplos produtos**
>
> Um checkout vende produtos que você prefere analisar em projetos separados.

> **Evitar reconexões e tokens duplicados**
>
> Menos conexões para manter — e menos pontos de falha (como token expirado).

## Como funciona

O compartilhamento acontece **dentro da mesma organização**: a conexão de origem continua sendo a "dona" dos dados, e os projetos selecionados passam a enxergar esses dados.

> [!NOTE]
>
> Compartilhar uma integração **não duplica** os dados nem cria uma nova conexão — é a mesma fonte, vista por mais de um projeto. Manutenção (reconexão, status) continua sendo feita em um lugar só.

> [!TIP]
>
> Lembre-se da diferença: **dados de projeto são isolados**, mas **integrações podem ser compartilhadas**. Essa é a forma recomendada de reaproveitar fontes sem misturar os relatórios. Veja [Projetos](/conceitos/projetos).

## Próximos passos

> **[O que são integrações](/integracoes/overview)**
>
> Revise o conceito de fonte de entrada de dados.

> **[Organizações](/conceitos/organizacoes)**
>
> Entenda o nível onde as integrações são compartilhadas.


# Conectar Metrito pelo checkout
Source: https://docs.metrito.com/integracoes/conectar-metrito

Como criar a integração direto do painel do seu checkout, sem procurar nada dentro do Metrito.

Alguns checkouts parceiros têm um botão **Conectar Metrito** dentro do próprio painel. Ele encurta o caminho: em vez de abrir o Metrito, procurar a integração na lista e preencher o passo a passo, você cai direto na tela certa, com a integração já escolhida e o nome já sugerido.

O resultado é o mesmo de [adicionar a integração pelo Metrito](/integracoes/adicionar-integracao). Muda só o caminho.

## Como funciona

**1. Clique em “Conectar Metrito” no seu checkout**

O botão fica na área de integrações do painel do checkout.

**2. Entre ou crie sua conta**

Se você já tem conta, clique em **Já tenho uma conta** e entre normalmente — você volta para esta tela logo depois.

Se ainda não tem, **Criar conta grátis** abre o cadastro.

> [!NOTE]
>
> Depois de criar a conta, volte ao painel do checkout e clique em **Conectar Metrito** de novo. O cadastro não devolve você automaticamente para o fluxo da integração.

**3. Escolha a organização e o projeto**

É onde as vendas do checkout vão aparecer. Se você só tem um projeto, ele já vem selecionado.

> [!WARNING]
>
> Se você atende vários clientes na mesma conta, confira a organização antes de continuar. As vendas vão para o projeto escolhido aqui e mudar depois dá trabalho.

**4. Escolha o modo de valor**

Define qual valor da venda o Metrito registra. Veja [Checkouts e comissões](/integracoes/checkouts-e-comissoes) para entender as opções.

**5. Copie a URL do webhook**

O Metrito gera a URL na hora. Copie e cole no cadastro de webhooks do seu checkout — é isso que faz as vendas chegarem.

## O nome da integração

O Metrito sugere um nome no formato `Checkout → Metrito`. Se já existir uma integração com esse nome na mesma organização, o novo ganha um número no fim: `Checkout → Metrito (2)`.

Dá para renomear quando quiser nas configurações da integração.

## Fuso horário

Integrações criadas por esse caminho nascem com fuso **America/Sao\_Paulo**. Se o seu checkout opera em outro fuso, mude nas configurações da integração depois de criar — o fuso define em que dia cada venda é contada.

## Próximos passos

> **[Checkouts e comissões](/integracoes/checkouts-e-comissoes)**
>
> Modo de valor, tipos de comissão, moeda e fuso horário.

> **[Rastrear o checkout](/tracking/checkouts)**
>
> Ligar a integração ao contêiner de rastreamento para disparar o evento de compra.


# Contas de anúncio
Source: https://docs.metrito.com/integracoes/contas-de-anuncio

Conecte contas de anúncio ao Metrito, entenda os status e resolva o token expirado.

## O que são

As **contas de anúncio** são as integrações que trazem os dados de mídia paga para o Metrito — gasto, impressões, campanhas, conjuntos e anúncios. Esses dados alimentam a tela de [Campanhas](/analise/campanhas) e métricas do dashboard como **ROAS** e **ROI**.

| Plataforma | Disponibilidade |
| - | - |
| **Meta Ads** | Disponível |
| **Google Ads** | Em breve |
| **TikTok Ads** | Em breve |

## Como conectar

Adicione pela tela de Integrações (botão **Adicionar Integração** → categoria **Tráfego**). A conexão usa **autorização (OAuth)** com a plataforma — você concede acesso e o Metrito passa a sincronizar os dados das contas autorizadas. Veja [Adicionar uma integração](/integracoes/adicionar-integracao).

## Status da conta

O status indica se a conta está saudável e sincronizando:

| Status | Significado |
| - | - |
| **Ativo** | Conta autorizada e sincronizando normalmente. |
| **Sincronizando** | Importando dados (primeira sincronização ou ciclo em andamento). |
| **Token expirado** | A autorização com a plataforma expirou — os dados param de atualizar. |
| **Débito pendente** | Há um débito não liquidado na conta de anúncio. |
| **Bloqueado** | A conta foi desabilitada na plataforma de origem. |

## Resolvendo o "Token expirado"

O **token expirado** é o problema mais comum em contas de anúncio. Ele acontece quando a autorização com a plataforma deixa de valer (troca de senha, revogação de acesso, expiração natural, etc.).

> [!WARNING]
>
> Com o token expirado, **os dados da conta param de ser atualizados**. As campanhas podem continuar aparecendo, mas com números desatualizados.

A solução é direta:

**1. Remova a conta**

Na tela de Integrações, remova a conexão que está com **Token expirado**.

**2. Adicione a conta novamente**

Use **Adicionar Integração** e reconecte a mesma conta, refazendo a autorização.

**3. Aguarde a sincronização**

O Metrito volta a importar os dados e o status retorna para **Ativo**.

## Próximos passos

> **[Tela de Campanhas](/analise/campanhas)**
>
> Veja o desempenho das campanhas dessas contas.

> **[Compartilhar integrações](/integracoes/compartilhar-integracoes)**
>
> Use a mesma conta de anúncio em vários projetos.


# Hotmart
Source: https://docs.metrito.com/integracoes/hotmart

Conecte a Hotmart ao Metrito por webhook para receber as vendas e disparar a compra aprovada nos pixels.

## Como funciona

A Hotmart envia cada venda para o Metrito por **webhook**. O Metrito gera uma URL exclusiva para a sua conexão, você cadastra essa URL na Hotmart e, a partir daí, cada compra aparece em [Vendas](/analise/vendas) e pode disparar o evento `Purchase` nos seus pixels.

São três partes:

1. Criar a conexão no Metrito e copiar a URL do webhook.
2. Cadastrar a URL na Hotmart.
3. Ligar a conexão ao container em **Rastreamento → Checkouts**.

> **[Prefere vídeo?](https://youtu.be/-6fdDpDQkUU)**
>
> Assista ao tutorial em vídeo de como conectar a Hotmart.

## 1. Crie a conexão no Metrito

**1. Abra Adicionar Integração**

No menu lateral, abra **Integrações** e clique em **Adicionar Integração**.

**2. Escolha Hotmart**

No modal **Integrações disponíveis**, use o filtro **Pagamentos** (ou busque por "Hotmart") e selecione **Hotmart**.

**3. Dê um nome à conexão**

Em **Nome da conexão**, use um nome que identifique a conta (ex.: "Hotmart Principal") e clique em **Próximo**.

**4. Escolha o modo de valor**

Em **Modo de valor**, escolha **Valor líquido** (o que você recebe de fato, já sem taxas e comissões) ou **Valor total da venda** (o valor cheio pago pelo cliente). Veja [Checkouts e comissões](/integracoes/checkouts-e-comissoes) para decidir.

**5. Confira o fuso horário**

Em **Fuso horário**, mantenha o padrão (horário de São Paulo) ou escolha o fuso da sua operação.

**6. Copie a URL do webhook**

No passo **Cadastrar webhook**, o Metrito cria a conexão e mostra a URL dela, no formato:

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

Clique em **Copiar URL do webhook**. Depois clique em **Próximo** e, na tela **Conexão criada**, em **Concluir**.

> [!WARNING]
>
> Trate essa URL como uma senha: quem tiver o endereço consegue enviar vendas para a sua conexão. Cadastre só na Hotmart e não publique.

## 2. Cadastre a URL na Hotmart

**1. Abra a tela de webhooks**

Na Hotmart, abra o menu **Ferramentas** e entre em **Webhook (API e Notificações)**. Se não aparecer de cara, clique em **Ver todas** e procure por "Webhook".

**2. Crie uma nova configuração**

Clique no botão de cadastrar um novo webhook e dê um nome à configuração (ex.: "Metrito").

**3. Cole a URL do Metrito**

No campo da URL de envio de dados, cole a URL que você copiou no Metrito.

**4. Escolha a versão 2.0.0**

Selecione a versão **2.0.0**. É o formato que o Metrito lê.

**5. Escolha produtos e eventos**

Aplique a configuração a todos os produtos ou só aos que você quer rastrear. Em eventos, marque os de compra (aprovada, completa, cancelada, reembolsada, chargeback, aguardando pagamento e as demais), ou simplesmente **Todos**: eventos que não são de compra, como abandono de carrinho, são ignorados pelo Metrito.

**6. Salve**

Clique em **Salvar**. As próximas vendas já chegam ao Metrito.

> [!NOTE]
>
> Os nomes dos botões variam um pouco entre versões da tela da Hotmart. O que importa é o caminho **Ferramentas → Webhook (API e Notificações)**, a URL do Metrito e a versão **2.0.0**.

## 3. Ligue a Hotmart ao rastreamento

Com a conexão criada, as vendas já aparecem em [Vendas](/analise/vendas). Para cada compra aprovada também disparar o `Purchase` nos pixels:

**1. Abra os checkouts do container**

No menu lateral, abra **Rastreamento** e vá à seção **Checkouts**.

**2. Ative a conexão**

No card **Conectar Checkouts**, encontre a conexão da Hotmart (use a busca **Buscar por 'nome' ou 'gateway'**) e **ligue o interruptor** dela.

Ao ligar o primeiro checkout, o Metrito cria sozinho o evento **Compra aprovada**, que envia `Purchase` para os pixels a cada venda aprovada. Veja [Checkouts](/tracking/checkouts).

## Atribuição das vendas da Hotmart

Nas páginas com o script do Metrito, os links diretos de checkout da Hotmart (`pay.hotmart.com/...`) saem com o parâmetro `xcod` preenchido automaticamente com o **Lead ID** do visitante e os **UTMs**. A Hotmart devolve esse `xcod` no webhook da venda, e é por ele que o Metrito liga a compra à sessão e à campanha de origem.

> [!TIP]
>
> Se a página também tem um player como VTurb ou Panda, ou se o rastreamento parece "sumir" no caminho até o checkout, confira o **Parâmetro de Identificação de Visitante** em [Avançado](/tracking/avancado).

## Próximos passos

> **[Checkouts e comissões](/integracoes/checkouts-e-comissoes)**
>
> Entenda o modo de valor e como o Metrito calcula o valor líquido.

> **[Vendas](/analise/vendas)**
>
> Acompanhe as compras e a receita atribuída.


# HyperCash
Source: https://docs.metrito.com/integracoes/hypercash

Conecte a HyperCash ao Metrito por webhook para receber vendas e assinaturas, com histórico de 12 meses pela chave de API.

## Como funciona

A HyperCash envia cada venda para o Metrito por **webhook**. O Metrito gera uma URL exclusiva para a sua conexão, você cadastra essa URL na HyperCash e, a partir daí, cada venda aparece em [Vendas](/analise/vendas) com o status atualizado.

São três partes:

1. Criar a conexão no Metrito e copiar a URL do webhook.
2. Cadastrar a URL na HyperCash.
3. Ligar a conexão ao container em **Rastreamento → Checkouts**, se quiser disparar o `Purchase` nos pixels.

## 1. Crie a conexão no Metrito

**1. Abra Adicionar Integração**

No menu lateral, abra **Integrações** e clique em **Adicionar Integração**.

**2. Escolha HyperCash**

No modal **Integrações disponíveis**, use o filtro **Pagamentos** (ou busque por "HyperCash") e selecione **HyperCash**.

**3. Dê um nome à conexão**

Em **Nome da conexão**, use um nome que identifique a conta (ex.: "HyperCash Principal") e clique em **Próximo**.

**4. Informe a chave de API (opcional)**

Em **Chave de API**, cole a chave secreta da sua conta HyperCash para trazer as vendas dos últimos 12 meses assim que a conexão for criada. Sem ela, entram só as vendas novas.

**5. Escolha o modo de valor**

Em **Modo de valor**, escolha **Valor líquido** (o que você recebe de fato, já sem taxas e comissões) ou **Valor total da venda** (o valor cheio pago pelo cliente). Veja [Checkouts e comissões](/integracoes/checkouts-e-comissoes) para decidir.

**6. Confira o fuso horário**

Em **Fuso horário**, mantenha o padrão (horário de São Paulo) ou escolha o fuso da sua operação.

**7. Copie a URL do webhook**

No passo **Cadastrar webhook**, o Metrito cria a conexão e mostra a URL dela, no formato:

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

Clique em **Copiar URL do webhook**. Depois clique em **Próximo** e, na tela **Conexão criada**, em **Concluir**.

> [!WARNING]
>
> Trate essa URL como uma senha: quem tiver o endereço consegue enviar vendas para a sua conexão. Cadastre só na HyperCash e não publique.

## 2. Cadastre a URL na HyperCash

**1. Abra os webhooks**

No painel da HyperCash, abra a área de webhooks (ou postback) da sua conta.

**2. Crie um webhook**

Crie um novo webhook e cole a URL que você copiou no Metrito.

**3. Escolha os eventos**

Marque todos os eventos de venda: criada, paga, recusada, expirada, reembolsada e chargeback. Eventos que não são de venda são ignorados pelo Metrito.

**4. Salve**

Salve o webhook. As próximas vendas já chegam ao Metrito.

## 3. Ligue a HyperCash ao rastreamento

Com a conexão criada, as vendas já aparecem em [Vendas](/analise/vendas). Para cada pagamento aprovado também disparar o `Purchase` nos pixels:

**1. Abra os checkouts do container**

No menu lateral, abra **Rastreamento** e vá à seção **Checkouts**.

**2. Ative a conexão**

No card **Conectar Checkouts**, encontre a conexão da HyperCash (use a busca **Buscar por 'nome' ou 'gateway'**) e **ligue o interruptor** dela.

Veja [Checkouts](/tracking/checkouts).

## Como o Metrito lê as vendas da HyperCash

* **Assinaturas:** a primeira cobrança vira assinatura iniciada e as seguintes entram como renovação, com o número do ciclo.
* **Histórico:** com a chave de API, os últimos 12 meses de vendas entram ao criar a conexão.
* **Meios de pagamento:** PIX, cartão e boleto.

## Próximos passos

> **[Checkouts e comissões](/integracoes/checkouts-e-comissoes)**
>
> Entenda o modo de valor e como o Metrito calcula o valor líquido.

> **[Vendas](/analise/vendas)**
>
> Acompanhe as compras e a receita atribuída.


# Integração personalizada
Source: https://docs.metrito.com/integracoes/integracao-personalizada

Conecte qualquer sistema ao Metrito enviando pedidos no formato de payload esperado.

## O que é a integração personalizada?

A **integração personalizada** é uma conexão de checkout genérica: em vez de um checkout pronto da lista, você envia os pedidos por conta própria, no **formato de payload que o Metrito espera**.

Com ela, **qualquer fonte** pode gerar pedidos dentro do Metrito — um sistema próprio, um CRM, uma área de membros, um ERP, o que for.

> [!NOTE]
>
> **O que é um pedido no Metrito?** É uma venda aprovada em um checkout. Ao chegar, o pedido pode disparar um evento de rastreamento (e ser enviado ao Meta), entra na tela de [Vendas](/analise/vendas) e influencia os números do [dashboard](/dashboard/overview) e da tela de [Campanhas](/analise/campanhas).

## Como funciona

**1. Crie a conexão personalizada**

Em **Adicionar Integração**, escolha a opção de integração **personalizada** (categoria Pagamentos). O Metrito gera uma **URL de webhook única** com a chave da sua conexão.

**2. Envie os pedidos no formato esperado**

O seu sistema dispara um `POST` em JSON para essa URL a cada mudança de status de pedido, seguindo o schema abaixo.

**3. Pronto**

O Metrito valida o payload, faz a atribuição via UTMs e o pedido passa a aparecer nas Vendas e nos relatórios.

## Formato do payload

O Metrito **valida o payload e rejeita** o que estiver fora do schema. Estrutura mínima de um pedido aprovado:

```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"
  }
}
```

### Campos obrigatórios

| Campo | Tipo | Descrição |
| - | - | - |
| `transaction.id` | string | ID único do pedido. |
| `transaction.status` | enum | Status padronizado (ver abaixo). |
| `transaction.commission_currency` | string | Moeda ISO de 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 fuso. |
| `transaction.updated_at` | string | ISO 8601 com fuso. |

> [!WARNING]
>
> Valores são sempre **em centavos** (inteiros). `9990` significa R\$ 99,90 — não envie `99.90`.

### Status aceitos

`pending`, `approved`, `authorized`, `failed`, `refunded`, `chargeback`, `under_analysis`, `cancelled`.

> [!TIP]
>
> **Envie um webhook a cada mudança de status** — não só no `approved`. O Metrito precisa de `refunded`, `chargeback`, etc. para manter a atribuição e os relatórios precisos. A deduplicação é automática: o evento de **Purchase** não é enviado ao Meta mais de uma vez para o mesmo pedido.

> [!WARNING]
>
> **UTMs são essenciais para a atribuição.** Inclua os parâmetros UTM da sessão original do comprador no payload. Sem eles, o pedido é registrado, mas não consegue ser atribuído a uma campanha na tela de [Campanhas](/analise/campanhas).

## Próximos passos

> **[Referência da API — Pedidos](/tracking/events-api)**
>
> Detalhes do endpoint e dos campos opcionais.

> **[Tela de Vendas](/analise/vendas)**
>
> Acompanhe os pedidos enviados pela sua integração.


# O que são integrações
Source: https://docs.metrito.com/integracoes/overview

Integrações são as fontes de entrada de dados do Metrito. Entenda o conceito, os status e a coluna tracking.

## O conceito de integração

A **integração** (ou **conexão**) é a peça que conecta uma fonte externa ao Metrito. Pense nela como o **plug**: é por onde os dados **entram** e onde ficam **guardados**.

Cada integração é uma **fonte de entrada** independente. A partir dela, os dados se propagam para o resto da plataforma:

```mermaid theme={null}
flowchart LR
    subgraph fontes [Integrações - fontes de entrada]
        ads["Contas de anúncio<br/>(Meta Ads)"]
        checkout["Checkouts / Gateways<br/>(webhooks)"]
        wpp["WhatsApp"]
        custom["Integração personalizada"]
    end
    fontes --> metrito[(Metrito)]
    metrito --> dash["Dashboard"]
    metrito --> camp["Campanhas"]
    metrito --> vendas["Vendas"]
    metrito --> leads["Leads"]
```

Conectou uma vez, os dados passam a alimentar o **dashboard**, a tela de **campanhas**, a tela de **vendas** e a de **leads**.

## Tipos de integração

| Categoria | Exemplos | O que traz |
| - | - | - |
| **Tráfego** | Meta Ads (Google Ads e TikTok Ads em breve) | Gasto, impressões, campanhas, conjuntos e anúncios |
| **Pagamentos** | Hotmart, Shopify, Stripe, Kiwify, Eduzz, e outros checkouts/gateways | Pedidos, produtos, status de pagamento, receita |
| **Mensagens** | WhatsApp | Conversas e eventos para atribuição |
| **Personalizada** | Qualquer sistema próprio | Pedidos via payload no formato do Metrito |

## A tabela de integrações

Na tela de **Integrações**, cada conexão aparece em uma linha com informações importantes:

| Coluna | O que significa |
| - | - |
| **Status** | A situação atual da conexão (ver abaixo). |
| **Tracking** | Um toggle. Quando **ativado**, aquele checkout/gateway dispara eventos de rastreamento dentro do Metrito. |
| **Timezone** | O fuso horário da conexão dentro do Metrito. |
| **Moeda** | A moeda de origem dos valores daquela conexão. |
| **Comissão** | O tipo de comissão usado para calcular o valor líquido (ver [Checkouts e comissões](/integracoes/checkouts-e-comissoes)). |

### A coluna *tracking*

A coluna **tracking** é o que liga uma conexão de checkout ao rastreamento. Com o toggle **ativado**, cada compra aprovada naquela conexão dispara um evento de rastreamento (e pode ser enviada ao Meta). Com ele desativado, os pedidos ainda aparecem em [Vendas](/analise/vendas), mas **não** geram evento de rastreamento.

## Status das conexões

O status indica a saúde da conexão. Os principais:

| Status | Significado | O que fazer |
| - | - | - |
| **Ativo / Conectado** | Tudo certo, dados fluindo. | Nada. |
| **Sincronizando** | Buscando os dados (primeira sincronização ou ciclo em andamento). | Aguardar. |
| **Token expirado** | A autorização com a plataforma expirou. | **Remover a conta e adicioná-la novamente** (ver abaixo). |
| **Débito pendente** | Há um débito não liquidado na conta de anúncio. | Regularizar na plataforma de origem. |
| **Bloqueado** | A conta foi desabilitada na origem. | Verificar a conta na plataforma de origem. |
| **Aguardando leitura de QR Code** | Conexão de WhatsApp aguardando pareamento. | Ler o QR Code (ver [WhatsApp](/integracoes/whatsapp)). |

> [!TIP]
>
> **Token expirado?** A solução é simples: **remova a conexão e adicione-a novamente**. Isso refaz a autorização e restabelece o fluxo de dados.

## Próximos passos

> **[Adicionar uma integração](/integracoes/adicionar-integracao)**
>
> Passo a passo para conectar uma nova fonte.

> **[Compartilhar integrações](/integracoes/compartilhar-integracoes)**
>
> Use a mesma conexão em vários projetos.

> **[Contas de anúncio](/integracoes/contas-de-anuncio)**
>
> Conecte Meta Ads e gerencie status.

> **[Checkouts e comissões](/integracoes/checkouts-e-comissoes)**
>
> Configure moeda, fuso e tipo de comissão.


# Conexão de WhatsApp
Source: https://docs.metrito.com/integracoes/whatsapp

Conecte um número de WhatsApp ao Metrito pela Metrito API (QR Code) ou pela Cloud API oficial da Meta.

## O que é a conexão de WhatsApp?

A conexão de **WhatsApp** liga um número ao Metrito para que as conversas gerem **eventos de rastreamento**. É ela que permite atribuir leads, conversas e vendas às campanhas que os originaram.

Você escolhe como conectar o número:

> **Metrito API (QR Code)**
>
> A solução nativa do Metrito. Você lê um **QR Code** e pareia o aparelho, igual ao WhatsApp Web. Serve para números do app WhatsApp e do WhatsApp Business.

> **Cloud API**
>
> A conexão **oficial** pela Cloud API da Meta, para números que já estão na plataforma de API do WhatsApp Business. Sem QR Code: você adiciona a Metrito como parceira e escolhe os números.

> [!NOTE]
>
> **Não há risco de "cair o chip".** O Metrito apenas **escuta** os eventos que acontecem no WhatsApp para gerar o rastreamento. Ele não dispara mensagens em massa nem realiza ações que coloquem o número em risco.

## Comece pela tela de Integrações

**1. Abra Adicionar Integração**

No menu lateral, abra **Integrações** e clique em **Adicionar Integração**.

**2. Escolha WhatsApp**

No modal **Integrações disponíveis**, use o filtro **Mensagens** e selecione **WhatsApp**.

**3. Escolha a forma de conexão**

No passo **Como conectar o WhatsApp**, selecione **Metrito API** ou **Cloud API** e siga as instruções abaixo.

> [!NOTE]
>
> O **Zapito**, que fazia a conexão por QR Code antes, foi descontinuado e aparece na lista como **Indisponível**. Números do Zapito que continuam conectados seguem funcionando, mas para parear um aparelho de novo crie uma conexão pela **Metrito API**. Dependendo da sua conta, a lista também mostra outras opções, como **Evolution GO**, **DataCrazy** e **Chatwoot**, para quem já usa essas ferramentas. As que ainda não foram liberadas aparecem com o selo **Em breve...**.

## Conectar pela Metrito API (QR Code)

**1. Dê um nome à conexão**

Em **Nome da conexão**, use um nome que identifique o número (ex.: "WhatsApp Principal").

**2. Escolha quem vai ler o QR Code**

No passo **Como você quer conectar**:

* **Tenho o celular em mãos**: o QR Code aparece na tela para você ler agora.
* **Enviar link para alguém**: copia um link para a pessoa que está com o celular abrir e ler o QR Code no aparelho dela.

**3. Leia o QR Code**

No celular, abra o **WhatsApp**, toque em **⋮** (Android) ou **Configurações** (iPhone), depois em **Aparelhos conectados** e em **Conectar um aparelho**. Aponte a câmera para o QR Code.

Não tire print: o código expira e se renova sozinho. Leia direto da tela.

**4. Conexão concluída**

A tela mostra **WhatsApp Conectado com Sucesso!** e o Metrito passa a escutar as conversas do número.

### Status da conexão

| Status | Significado |
| - | - |
| **Aguardando leitura de QR Code** | A conexão foi criada e espera o pareamento. |
| **Conectado** | O aparelho está pareado e as conversas estão sendo escutadas. |
| **Desconectado** | O pareamento caiu. Reconecte lendo o QR Code novamente. |

## Conectar pela Cloud API

Use a Cloud API se o número já está na plataforma de API do WhatsApp Business, dentro de uma conta do WhatsApp Business no seu Business Manager.

**1. Adicione a Metrito como parceira**

No Business Manager, vá em **Configurações do negócio → Contas do WhatsApp → (sua conta) → Parceiros → Adicionar → Compartilhar com um parceiro** e informe o ID da Metrito que aparece nesse passo (clique nele para copiar).

Sem essa parceria, a conexão dos números não funciona.

**2. Autentique com o Facebook**

Clique em **Entrar com Facebook** e autorize com a sua conta. O Metrito usa essa autorização só para listar os números de WhatsApp a que você tem acesso.

**3. Selecione os números**

Marque o(s) número(s) que quer conectar e clique em **Conectar**. Números que já estão no Metrito aparecem como **Já conectado**.

> [!TIP]
>
> Conexões pela Cloud API não dependem de um aparelho pareado, então não passam pelos status de QR Code: aparecem como **Conectado** desde o início.

## Ligue o número ao rastreamento

Conectar o número é só a primeira parte. Para as conversas entrarem na jornada do cliente e as conversões irem para os pixels, **ligue o número ao container**: em **Rastreamento → WhatsApp**, no card **Conectar WhatsApp**, ative o interruptor ao lado dele.

> **[Rastreamento no WhatsApp](/tracking/whatsapp)**
>
> Veja como ligar o número ao container, como as conversas são atribuídas às campanhas e como levar o lead do WhatsApp para o site.

## Próximos passos

> **[Tela de Leads](/analise/leads)**
>
> Veja os contatos identificados, inclusive pelo WhatsApp.

> **[Adicionar uma integração](/integracoes/adicionar-integracao)**
>
> Conecte outras fontes de dados ao projeto.


# Primeiros Passos
Source: https://docs.metrito.com/quickstart

Coloque o rastreamento do Metrito funcionando no seu site em menos de 5 minutos

## Configure o rastreamento em três etapas

**1. Crie um container de rastreamento**

Um **container** é o espaço dedicado ao seu negócio dentro do Metrito. Ele organiza todos os seus dados de rastreamento, fontes de eventos e destinos de conversão. Cada container possui um identificador único no formato `MTC-XXXXXXX`.

1. Acesse a [Plataforma Metrito](https://app.metrito.com)
2. No menu lateral, clique em **Rastreamento**
3. Se o projeto ainda não tem container, a tela **Criar um novo Container** abre sozinha. Dê um nome em **Nome do Container (opcional)** e clique em **Criar Container**
4. Copie o **ID do Container** (ex: `MTC-5X35GWQ`). Ele aparece logo abaixo do nome do container, no topo do menu do **Rastreamento**: clique nele para copiar

> [!NOTE]
>
> Se o projeto já tem um container, clicar em **Rastreamento** abre direto esse container. Cada projeto usa um container.

> [!TIP]
>
> Cada container é completamente isolado: eventos, leads e dados de atribuição de um container nunca se misturam com os de outro.

**2. Instale o Pixel de Rastreamento**

Adicione o script do Metrito em todas as páginas do seu site, antes do fechamento da tag `</head>`:

```html theme={null}
<!-- Metrito Tracking Code -->
<script>
  !(function(t,r,a,c,k,i,n,g){
  a="mtrt";c="script";k=window;i=document;n=new URL(location);g=n.searchParams;
  if(k[a])return;t="/"+a+"tag.js?id="+(g.get(a+"id")||t);n.host="sst."+n.host.replace(/^w{3}\./i,"");
  [g.get(a+"url")||n.origin].concat(r).reduce(function(w,x){return w.catch(x?new Promise(function(y,z){
  n=i.createElement(c);n.src=x+t;n.async=!0;n.onload=y;n.onerror=z;
  g=i.getElementsByTagName(c)[0];g.parentNode.insertBefore(n,g)}):
  Promise.reject())},Promise.reject());a=k[a]=function(){a.track?
  a.track.apply(a,arguments):a.queue.push(arguments)};a.ver=1;a.queue=[];
  k.metrito||(k.metrito=a)})(
  "MTC-XXXXXXX",["https://api.metrito.com/v2"]);
</script>
<!-- End Metrito Tracking Code -->
```

Substitua:

* `MTC-XXXXXXX` pelo ID do seu container

> [!NOTE]
>
> O pixel captura automaticamente: visualizações de página, parâmetros UTM, referenciador, cookies (`_fbp`, `_ga`) e informações do
> dispositivo.

Veja o guia completo em [Instalação do Pixel Web](/tracking/web-setup).

**3. Configure os Parâmetros UTM**

Adicione estes parâmetros de URL nas suas campanhas do Meta Ads para que o Metrito identifique qual campanha, conjunto de anúncios e criativo gerou cada conversão:

```
utm_source=facebook&utm_campaign={{campaign.name}}|{{campaign.id}}&utm_medium={{adset.name}}|{{adset.id}}&utm_content={{ad.name}}|{{ad.id}}&utm_term={{placement}}
```

No **Gerenciador de Anúncios da Meta**: Campanha > Editar > Rastreamento > Parâmetros de URL.

O Metrito interpreta automaticamente o formato `nome|id` para extrair tanto o nome legível quanto o ID técnico de cada campanha.

Veja o guia completo em [Configuração de UTMs](/tracking/utm-configuration).

## O que acontece depois

Com o pixel instalado, o Metrito começa a rastrear imediatamente:

* **Visualizações de página** são capturadas com atribuição completa de UTM
* **Leads** são identificados quando e-mail ou telefone é enviado via formulário
* **Sessões** são criadas e agrupadas para atribuição multi-toque
* **Identidade entre canais** conecta visitas anônimas ao site com conversas no WhatsApp e compras

## Próximos passos

> **[Visão Geral do Rastreamento](/tracking/overview)**
>
> Entenda como contêineres, eventos, sessões e jornadas funcionam juntos.

> **[API de Eventos](/tracking/events-api)**
>
> Envie eventos pelo servidor a partir do Shopify, WooCommerce ou qualquer backend.

> **[Rastreamento via WhatsApp](/tracking/whatsapp)**
>
> Conecte conversas do WhatsApp às sessões web.

> **[Testes e Diagnóstico](/tracking/testing)**
>
> Verifique sua instalação e resolva problemas.


# Avançado
Source: https://docs.metrito.com/tracking/avancado

Ajuste o parâmetro de identificação de visitante e encaminhe os eventos para outros sistemas.

## Parâmetro de Identificação de Visitante

O Metrito usa um parâmetro na URL para **identificar o visitante** entre páginas. Por padrão, esse parâmetro é o **`src`**.

O problema é que **`src` é um nome muito comum** — alguns players de vídeo e checkouts também usam. Se houver conflito, o rastreamento pode quebrar. Por isso, em **Avançado**, você pode trocar o **Parâmetro de Identificação de Visitante** por outro valor.

### Quando trocar

> **Players de vídeo (VTurb, Panda)**
>
> Players como **VTurb** e **Panda Video** usam `src` para carregar o vídeo. Se você tem um desses na mesma página, **troque o parâmetro do Metrito para `sck`** (ou outro valor) para evitar o conflito.

> **Checkout Hotmart**
>
> A **Hotmart** trabalha com `src` / `xcod`. Para a atribuição casar, **alinhe o parâmetro** ao que a Hotmart envia (`src` ou `xcod`).

> [!WARNING]
>
> Se você usa uma VSL com VTurb/Panda **e** rastreia com o Metrito na mesma página, conferir esse parâmetro é praticamente obrigatório — é uma das causas mais comuns de "o rastreamento parou de funcionar".

> [!TIP]
>
> Na dúvida, abra uma página com o player/checkout instalado e veja qual parâmetro já aparece na URL. Configure o Metrito para **não** colidir com ele.

## Encaminhamento de Eventos

Ainda em **Avançado**, você pode cadastrar **URLs de encaminhamento de eventos**. O Metrito envia uma **cópia idêntica do payload** de cada evento — via **Webhook (POST)** — para os sistemas que você listar.

Isso transforma o Metrito em um **hub**: ele rastreia, atribui e ainda **notifica suas ferramentas**. Casos comuns:

* **n8n**, **Make** ou **Zapier** — para disparar automações a cada evento.
* **Sistema próprio** — para receber os eventos no seu backend e usá-los como quiser.

**1. Cadastre a URL de destino**

Informe a URL do webhook (do n8n, Make, Zapier ou do seu sistema) que vai receber os eventos.

**2. Receba o payload**

A cada evento, o Metrito faz um `POST` com o mesmo payload que processa internamente.

**3. Use como quiser**

Trate o payload no seu fluxo — notificar um CRM, enviar um e-mail, atualizar uma planilha, etc.

> [!WARNING]
>
> **Não há retentativa automática em caso de erro.** Se o seu endpoint estiver fora do ar ou responder com erro no momento do disparo, aquele evento **não é reenviado**. Garanta que o destino seja estável e responda rápido.

## Próximos passos

> **[Sessões e leads](/tracking/sessoes)**
>
> Veja o payload exato que é capturado e encaminhado.

> **[API de Eventos](/tracking/events-api)**
>
> Envie eventos pelo servidor, direto para o container.


# Checkouts
Source: https://docs.metrito.com/tracking/checkouts

Conecte seu checkout ao container para disparar a compra aprovada (Purchase) automaticamente.

## Por que conectar o checkout

A compra é o evento mais importante do funil. Quando você conecta seu **checkout** ao container, o Metrito recebe cada **compra aprovada** direto da plataforma de pagamento — pelo servidor, via webhook — e dispara o evento **`Purchase`** para os pixels da Meta, sem depender de o cliente cair numa página de obrigado.

É o jeito mais confiável de rastrear vendas: não se perde por bloqueio de navegador, aba fechada ou redirect que falhou.

## A tela Checkouts

Na seção **Checkouts** do tracking, o card **Conectar Checkouts** mostra:

> *Selecione os sistemas de checkout conectados a este domínio para enviar dados de Compra para Pixels.*

Cada linha é um checkout ou gateway já conectado à sua conta. Use a busca **Buscar por 'nome' ou 'gateway'** para encontrá-lo e **ligue o interruptor** para ativar o rastreamento daquele checkout neste container.

**1. Conecte o checkout (se ainda não conectou)**

Clique em **Nova conexão Checkout** para adicionar uma plataforma. Você pode também criar a conexão pela tela de [Integrações](/integracoes/checkouts-e-comissoes).

**2. Ative o rastreamento**

Ligue o interruptor da conexão. A partir daí, cada compra aprovada vira um evento `Purchase`.

> [!NOTE]
>
> Se nenhuma conexão aparecer, a tela mostra **"Nenhuma conexão no momento."** — conecte um checkout primeiro pela tela de Integrações.

## O evento de compra é criado sozinho

Ao conectar o primeiro checkout, o Metrito cria automaticamente o evento **Compra aprovada**, que dispara `Purchase` para a Meta a cada venda aprovada. Você não precisa configurá-lo na tela de [Eventos](/tracking/eventos) — mas pode editá-lo lá se quiser.

> [!WARNING]
>
> O `Purchase` só dispara se o interruptor do checkout estiver **ativado**. Confira em dois lugares: aqui, na seção **Checkouts**, ou na tela de [Integrações](/integracoes/overview), na coluna **Tracking**.

## Atribuição: ligando a venda à campanha

Quando a compra chega, o Metrito cruza os dados do pedido (e-mail, telefone) com as sessões já rastreadas e **atribui a venda à campanha de origem** — mesmo que o clique no anúncio tenha sido dias antes. É assim que a tela de [Campanhas](/analise/campanhas) consegue mostrar receita por anúncio.

> [!TIP]
>
> Você pode **auditar o webhook** que gerou cada compra na tela de [Sessões e leads](/tracking/sessoes): clique no evento de `Purchase` e veja o payload bruto que o checkout enviou.

## E a Shopify?

A Shopify trata scripts de terceiros de forma diferente e **não** deve receber o script direto no tema. Para Shopify, use o caminho de integração dedicado — fale com o time do Metrito. Veja o aviso em [Instalação no site](/tracking/web-setup).

## Próximos passos

> **[Pixels](/tracking/pixels)**
>
> Garanta que há um pixel cadastrado para receber o `Purchase`.

> **[Vendas](/analise/vendas)**
>
> Acompanhe as compras aprovadas e a receita atribuída.


# Integração com o CRM DataCrazy 
Source: https://docs.metrito.com/tracking/datacrazy-crm

Envie leads criados no DataCrazy para o Metrito via automação usando o gatilho 'Lead created' e o nó de API.

Este guia ensina como conectar o **DataCrazy** ao Metrito usando o painel de **Automações**. Quando um lead for criado no CRM, a automação disparará uma requisição HTTP para o endpoint de eventos do Metrito. Isso é fundamental para a **atribuição no Meta Ads**, inclusive em cenários com **Click to WhatsApp (CTWA)**.

## Pré-requisitos

* Uma conta ativa no Metrito com um **contêiner de rastreamento** (você precisará do código **MTC**).
* Uma **Chave de API** do Metrito com permissão para enviar eventos (escopo de rastreamento).
* Acesso à área de **Automações** no painel do DataCrazy para criar o fluxo.

## 1. Criar o gatilho da automação

1. No DataCrazy, acesse a página de **Automações**.
2. Crie um novo fluxo ou abra um já existente.
3. No bloco inicial (**Start**), adicione um novo gatilho.
4. Selecione a opção **Lead created** (*When a lead is created* / Quando um lead for criado).

Com isso, o fluxo será acionado automaticamente sempre que um novo lead entrar no CRM.

## 2. Adicionar o nó de API

1. A partir do ponto de saída do bloco **Start** (onde diz *When the event occurs, then*), conecte o próximo passo.
2. Adicione um nó de requisição externa. Na interface do DataCrazy, ele pode se chamar **API**, **HTTP** ou **Webhook**.
3. Esse nó será o responsável por enviar os dados do lead para o Metrito via um método **POST**.

## 3. Configurar URL e método

Preencha as configurações do nó de API com os seguintes valores:

| Campo | Valor |
| - | - |
| **Método** | `POST` |
| **URL** | `https://api.metrito.com/v3/tracking/events` |

> [!TIP]
>
> Se quiser que o processamento seja feito na hora (modo **síncrono**) e receber uma resposta JSON imediata com o status do lead, adicione `?sync=true` ao final da URL:
> `https://api.metrito.com/v3/tracking/events?sync=true`

## 4. Cabeçalhos (Headers)

Adicione os seguintes cabeçalhos na configuração do nó:

| Nome do Header | Valor do Header |
| - | - |
| `Content-Type` | `application/json` |
| `Authorization` | `Bearer SUA_CHAVE_DE_API` |

Substitua `SUA_CHAVE_DE_API` pela chave real que você gerou no Metrito. O valor final deve conter a palavra `Bearer`, seguida de um espaço e o token (exemplo: `Bearer mtk_live_Jw_LnFIkve...`).

### Onde gerar a chave no Metrito?

1. Acesse o painel da plataforma Metrito.
2. Navegue até **Configurações** → **Chaves de API** (ou **API keys**).
3. Crie uma nova chave certificando-se de conceder a permissão de rastreamento (`tracking:write`).
4. Copie o token gerado e cole-o na sua automação.

> [!WARNING]
>
> Sua chave de API é uma credencial sensível. Nunca a compartilhe publicamente. Se o DataCrazy oferecer um cofre de segredos ou variáveis de ambiente seguras, prefira utilizá-los.

## 5. Corpo da requisição (JSON)

O corpo da requisição (*body* ou *payload*) deve ser enviado no formato **JSON**. No DataCrazy, as variáveis dinâmicas usam o padrão **`${nomeDaVariavel}`** (cifrão + chaves). Os nomes são **os mesmos para todos os usuários** (ex.: `${leadSourceUrl}` para a URL de origem).

Aqui está um exemplo de payload para enviar o lead como evento **Contact** na Meta, já com o padrão de variáveis do DataCrazy:

```json theme={null}
{
  "container_id": "MTC-XXXXXXXX",
  "sourceKey": "whatsapp",
  "config": {
    "name": "Lead Criado",
    "facebook": {
      "name": "Contact",
      "trackCustom": false,
      "sourceKey": "business_messaging"
    }
  },
  "lead": {
    "name": "${leadName}",
    "email": "${leadEmail}",
    "phone": "${leadPhone}"
  },
  "utm": {
    "source_id": "${leadSourceId}",
    "utm_content": "${leadSourceId}",
    "utm_medium": "ctwa_ad"
  },
  "cookies": {
    "ctwaClid": "${leadCtwaId}"
  },
  "meta": {
    "url": "${leadSourceUrl}"
  }
}
```

### Explicação dos campos principais:

* **`container_id`**: É o seu código **MTC** (ex.: `MTC-55AEW53Y`). Para encontrar este código:
  1. No Metrito, acesse **Rastreamento**.
  2. Escolha o contêiner desejado.
  3. Você verá o código **MTC-XXXXXX** logo abaixo do nome do contêiner. Copie-o e substitua `MTC-XXXXXXXX` no JSON acima (valor fixo, não é variável do DataCrazy).
* **`sourceKey`**: Fonte exibida na coluna **Fonte** do histórico do lead. Use `whatsapp` para que a jornada inteira (Contact, Lead, Purchase) apareça agrupada como WhatsApp, e não dividida entre WhatsApp e API. Se omitido, o evento é rotulado como `api`.
* **`config.facebook`**: Informa ao Metrito como esse evento deve ser encaminhado para a API de Conversões da Meta. O `sourceKey: "business_messaging"` dentro deste bloco é o que faz a Meta receber o evento como mensagem (e não como evento de site) — **só funciona se o contêiner tiver um pixel de WhatsApp vinculado**.
* **`utm.source_id`** e **`utm_content`**: ID do anúncio na Meta — use `${leadSourceId}` nos dois quando fizer sentido para o seu fluxo. Com `source_id`, o Metrito pode **enriquecer** campanha, conjunto e pixel (se a conexão Facebook Marketing estiver ativa).
* **`cookies.ctwaClid`**: Identificador CTWA — `${leadCtwaId}`.
* **`meta.url`**: URL de origem do lead — **`${leadSourceUrl}`** (mesmo nome em todas as contas DataCrazy).

As expressões `${leadName}`, `${leadEmail}`, `${leadPhone}`, `${leadSourceId}`, `${leadCtwaId}` e `${leadSourceUrl}` são resolvidas pelo DataCrazy no momento em que a automação roda.

## 6. Testes e validação

1. Salve a automação no DataCrazy.
2. Execute a automação com um lead de teste (caso o CRM ofereça a opção de testar o nó).
3. No painel do Metrito, acesse os detalhes do contêiner e verifique se o evento e os dados do lead foram recebidos com sucesso.
4. Se você enviou o evento para a Meta, verifique o Gerenciador de Eventos (modo de teste do servidor) para confirmar o recebimento do payload de conversão.

## Próximos passos

Na aba **Referência de API** da documentação (em **API de Rastreamento** → **Eventos**), você encontra o contrato completo do endpoint **POST /v3/tracking/events**, incluindo todos os parâmetros opcionais.

> **[API de eventos (visão geral)](/tracking/events-api)**
>
> Conheça melhor os conceitos de `container_id`, `config.name` e `config.facebook.name`.

**Dica de resolução de problemas:** Se o nó de API retornar `401` ou `403`, confira o header `Authorization`: deve ser a palavra `Bearer`, um espaço e o token da chave copiado do Metrito (valor fixo). **Não** use `${...}` no header — o padrão `${variável}` do DataCrazy vale para o corpo JSON, não para a chave de API.


# Domínios e bypass
Source: https://docs.metrito.com/tracking/dominios

Rode o tracking no seu próprio domínio (first-party) e fuja de bloqueios de iOS e ad blockers.

## Por que usar seu próprio domínio

Por padrão, o script do Metrito carrega de um domínio do Metrito. Navegadores como o Safari/iOS e extensões de bloqueio de anúncios costumam **bloquear ou encurtar** dados de domínios de rastreamento de terceiros — e você perde captura.

O **bypass** resolve isso fazendo o tracking rodar em um **subdomínio seu** (`sst.seudominio.com`). Como as requisições saem do seu próprio domínio (*first-party*), elas **não são bloqueadas** — e a taxa de captura sobe bastante.

> [!NOTE]
>
> Esse recurso usa um **proxy DNS** (via Cloudflare) para evitar bloqueios de Safari/iOS e ad blockers que impediriam a captura. É opcional, mas **altamente recomendado**.

## A tela Domínios

Na seção **Domínios**, o card **Domínios Verificados** lista os domínios já configurados:

> *Gerencie os domínios verificados para este container. Quando o DNS for verificado, subdomínios serão automaticamente permitidos.*

Se você ainda não tem nenhum, aparece **"Nenhum domínio verificado"** com a dica *Adicione um domínio para habilitar o tracking invisível.*

> [!NOTE]
>
> Os Domínios Verificados estão disponíveis **apenas para containers V3**.

## Adicionar e verificar um domínio

**1. Adicione o domínio**

Clique em **Adicionar Domínio** e informe o **domínio principal (TLD)** — ex.: `seudominio.com`, **sem** subdomínios.

**2. Crie o registro CNAME**

No seu provedor de DNS, adicione o registro abaixo.

| Tipo | Host/Nome | Valor | TTL |
| - | - | - | - |
| `CNAME` | `sst` | `sst.metrito.com` | `14400` |

**3. Verifique o DNS**

De volta ao Metrito, clique em **Verificar DNS** no domínio adicionado. A propagação pode levar **até 24 horas**.

> [!TIP]
>
> O host `sst` cria o subdomínio `sst.seudominio.com`. Se o seu provedor pedir o host completo, use `sst.seudominio.com`; alguns aceitam apenas `sst`.

## Status do domínio

Cada domínio mostra um selo de status:

| Status | O que significa |
| - | - |
| **Ativo** | DNS verificado. O bypass está funcionando e **todos os subdomínios** são permitidos automaticamente. |
| **Pendente** | Aguardando a verificação/propagação do DNS. Use **Verificar DNS**. |
| **Falhou** | A verificação não passou. Confira o registro CNAME e tente de novo. |
| **Inativo** | O domínio não está em uso no momento. |

Quando um domínio fica **Ativo**, aparece a indicação **Bypass de IOS/AdBlockers habilitado** e a data de verificação.

## O que muda quando o bypass está ativo

* O **script** passa a carregar do seu subdomínio (`sst.seudominio.com`).
* Os **links de redirect** passam a usar o seu domínio em vez do domínio padrão do Metrito.
* A captura fica mais resistente a Safari/iOS e ad blockers.

> [!WARNING]
>
> Ao **remover** um domínio verificado, o hostname associado é apagado e o tracking invisível **deixa de funcionar** para aquele domínio. Remova só se tiver certeza.

## Próximos passos

> **[Instalação no site](/tracking/web-setup)**
>
> Volte para instalar (ou reinstalar) o script já com o bypass.

> **[Parâmetros e UTMs](/tracking/utm-configuration)**
>
> Configure os UTMs dos anúncios para a atribuição completa.


# Eventos
Source: https://docs.metrito.com/tracking/eventos

Configure quais ações viram eventos de conversão e como cada acionador é disparado.

## O que é um evento no Metrito

Um **evento** é uma ação que aconteceu — uma visualização de página, um envio de formulário, uma compra, uma mensagem no WhatsApp. Na tela de **Eventos** você define **quais ações** o Metrito registra e **quais delas são enviadas como conversão** para os pixels da Meta.

Cada evento pode ser:

* **Só no Metrito** — para acompanhamento interno (funil, sessões, relatórios).
* **Enviado também à Meta (CAPI)** — quando você associa o evento a um evento padrão da Meta (ex.: `Purchase`, `Lead`, `Contact`).

## Eventos criados automaticamente

Dois eventos nascem sozinhos — você não precisa criá-los:

> **Visualização de Página (PageView)**
>
> Criado automaticamente quando o container é criado. Dispara a cada página carregada. Pode ser removido, se quiser.

> **Compra aprovada (Purchase)**
>
> Criado automaticamente quando você conecta um [checkout](/tracking/checkouts). Dispara `Purchase` para a Meta a cada compra aprovada em qualquer checkout conectado e ativo.

> [!NOTE]
>
> Para o `Purchase` disparar, o rastreamento do checkout precisa estar **ativado**. Confira o interruptor na tela de [Integrações](/integracoes/overview) (coluna **Tracking**) ou na seção de [Checkouts](/tracking/checkouts).

## Criar um evento

Clique em **Novo evento**. O assistente tem três passos: **Evento**, **Acionador** e **Ajustes**.

**1. Evento**

Dê um nome ao evento e, se quiser enviá-lo à Meta, associe-o a um evento padrão (ex.: `Lead`, `Contact`, `Purchase`).

**2. Acionador**

Escolha **o que** dispara o evento (veja a lista de acionadores abaixo).

**3. Ajustes**

Refine **onde** e **quando** o acionador vale — páginas incluídas/excluídas, elemento-alvo, termos, etc.

## Os acionadores

O acionador é o gatilho do evento. Eles cobrem ações no **site**, **WhatsApp**, **checkout**, **links rastreáveis** e eventos enviados pela **API**:

| Acionador | Dispara quando… |
| - | - |
| **Visualização de Página** | uma página é carregada |
| **Duração da Visualização** | o visitante fica X tempo na página |
| **Duração da Visualização de Vídeo** | o vídeo é assistido por X tempo |
| **Envio de Formulário** | um formulário é enviado |
| **Clique em Elemento** | um elemento específico é clicado |
| **Visualização de Elemento** | um elemento entra na tela |
| **Hover em Elemento** | o mouse passa sobre um elemento |
| **Profundidade de Rolagem** | o visitante rola até X% da página |
| **Compra aprovada no checkout** | um checkout conectado aprova uma compra (dispara `Purchase`) |
| **Mensagem no WhatsApp** | uma mensagem contém os termos configurados |
| **Clique em link rastreável** | um link de redirect é clicado |
| **API** | o seu sistema, CRM ou automação envia o evento pela [Events API](/tracking/events-api) |

### Eventos que chegam pela API

Você não precisa cadastrar um evento antes de enviá-lo pela [Events API](/tracking/events-api). Quando um evento chega com um `config.name` que ainda não existe neste container, o Metrito cria a conversão automaticamente com o acionador **API**. Ela aparece na lista de eventos com a marcação "Criado automaticamente" e já pode ser usada como coluna na tabela de campanhas ("Nome do evento" e "Custo por Nome do evento") e como métrica nos widgets do dashboard.

Ao escolher o acionador **API** no cadastro manual, o Metrito mostra o `curl` e o exemplo em Node.js já preenchidos com o ID do container e o nome do evento.

> [!NOTE]
>
> Se você apagar uma conversão criada automaticamente e o evento continuar chegando, ela volta no próximo disparo. Cada container recebe até 100 conversões criadas automaticamente pela API; acima disso os eventos continuam sendo gravados, mas não entram no catálogo sozinhos.

## Configurando os acionadores mais usados

### Acionadores de site (página e elemento)

Nos **Ajustes**, você decide o alcance do acionador:

* **Em todo o site, com exceções** — vale em todas as páginas, menos as que você excluir.
* **Apenas em páginas específicas** — vale só nas páginas que você listar.

Para **Clique em Elemento** (e similares), você identifica o elemento-alvo de uma destas formas:

* **Por link** — cole o link inteiro **ou um trecho**. Um trecho funciona: por exemplo, `pay.hotmart.com` casa com qualquer link de checkout da Hotmart, sem precisar do ID específico.
* **Por classe CSS** — ex.: `.btn-comprar`.
* **Por ID CSS** — ex.: `#finalizar-compra`.

> [!TIP]
>
> Usar **trecho de link** é ótimo para checkouts: coloque só até a barra (ex.: `pay.hotmart.com/`) e o acionador pega qualquer produto daquele checkout.

### Mensagem no WhatsApp

Esse acionador usa **Termos de acionamento** — *quais palavras/frases inclusas na mensagem devem disparar o evento?* Sempre que o **operador** envia ao lead uma mensagem que contém um dos termos, o evento dispara.

> [!WARNING]
>
> A mensagem precisa ser **idêntica** ao termo configurado, incluindo **acentuação, espaços e letras maiúsculas**. Use termos específicos (ex.: "Pagamento aprovado ✅") para evitar disparos por engano.

### Clique em link rastreável

Associa o evento a um [link de redirect](/tracking/links-de-redirect): toda vez que o link é clicado, o evento dispara. Útil para medir cliques em botões de WhatsApp, bio do Instagram, etc.

## Próximos passos

> **[Checkouts](/tracking/checkouts)**
>
> Conecte seu checkout para o `Purchase` disparar sozinho.

> **[Sessões e leads](/tracking/sessoes)**
>
> Veja os eventos disparando em ordem e audite cada um.


# API de Eventos
Source: https://docs.metrito.com/tracking/events-api

Envie eventos de rastreamento pelo servidor a partir de qualquer plataforma usando a API pública v3 do Metrito

A API de Eventos permite enviar eventos de rastreamento a partir de qualquer sistema — backends, ferramentas de automação (n8n, Make, Zapier), CRMs, plataformas de e-commerce ou integrações personalizadas.

Na versão **v3**, a API suporta envios assíncronos (padrão) e síncronos, e introduz o suporte à autenticação via Chave de API, recomendada para maior segurança e controle. IDs são gerados automaticamente quando não fornecidos.

## Endpoint

```http theme={null}
POST https://api.metrito.com/v3/tracking/events
```

| Propriedade | Valor |
| - | - |
| **Método** | POST |
| **Autenticação** | Opcional (Obrigatória para `?sync=true`) |
| **Content-Type** | `application/json` |

## Autenticação e Sincronismo

A API suporta dois modos de funcionamento:

1. **Modo Assíncrono (Padrão)**: O evento é enfileirado e processado em segundo plano. Não exige chave de API. Responde com sucesso quase imediatamente.
2. **Modo Síncrono (`?sync=true`)**: O evento é processado na hora da requisição. Retorna um objeto JSON com o ID do evento, ID do lead e status de criação no banco de dados. **Exige autenticação**.

Para autenticar a requisição, adicione o seguinte cabeçalho (header):

```text theme={null}
Authorization: Bearer SUA_CHAVE_DE_API
```

Você pode criar suas chaves de API no painel do Metrito em **Configurações → Chaves de API**. A chave deve ter permissão de escrita para rastreamento (`tracking:write`).

## Campos Obrigatórios

Toda requisição precisa de pelo menos a indicação do contêiner e do nome do evento.

```json theme={null}
{
  "container_id": "MTC-55AEW53Y",
  "config": {
    "name": "NomeDoEvento"
  }
}
```

| Campo | Descrição |
| - | - |
| `container_id` | ID MTC (ex: `MTC-5X35GWQ`) ou o domínio do seu contêiner (ex: `sujaloja.com.br`). |
| `config.name` | Nome do evento para exibição em dashboards e relatórios do Metrito. |

> [!NOTE]
>
> **Catálogo automático.** Um `config.name` que ainda não existe no contêiner vira uma conversão com acionador **API** na página de Eventos, sem cadastro prévio, e passa a estar disponível como coluna na tabela de campanhas e como métrica no dashboard. Se o payload trouxer `config.facebook.name`, é esse nome que identifica o evento no Metrito.

## Campos Opcionais Relevantes

### `sourceKey` — a fonte do evento

Define como o evento aparece na coluna **Fonte** do histórico do lead. Eventos enviados por esta API são rotulados como **API** por padrão.

| Valor | Quando usar |
| - | - |
| `api` | **Padrão.** Integrações de CRM, backend, automações. |
| `whatsapp` | O evento nasceu numa conversa de WhatsApp e você quer agrupá-lo como tal. |
| `website` | O evento representa uma ação no site. |

Valores fora dessa lista são ignorados e o evento volta para `api`.

```json theme={null}
{
  "container_id": "MTC-55AEW53Y",
  "sourceKey": "whatsapp",
  "config": { "name": "QualifiedLead" }
}
```

### `config.facebook.sourceKey` — o action\_source da Meta

Campo **diferente** do anterior, apesar do nome parecido: este governa o `action_source` enviado à API de Conversões da Meta, não o rótulo de fonte no Metrito.

Use `"business_messaging"` quando o evento pertencer a uma conversa de WhatsApp (Click to WhatsApp). Com ele, a Meta recebe o evento como mensagem — e não como evento de site — e a atribuição usa o dataset de WhatsApp.

```json theme={null}
{
  "config": {
    "name": "QualifiedLead",
    "facebook": { "name": "Lead", "sourceKey": "business_messaging" }
  }
}
```

> [!WARNING]
>
> O marcador só tem efeito se o contêiner tiver um **pixel de WhatsApp vinculado**. Sem esse dataset, o evento continua saindo como `website`.

### Campos do `lead`

Todos opcionais. Além de identificar o lead (dedupe/upsert por e-mail, telefone e documento), esses campos alimentam o *advanced matching* da Meta — quanto mais campos, melhor a nota de correspondência (EMQ).

| Campo | Descrição |
| - | - |
| `id` | ID do lead no Metrito (`lead_...`), quando você já o tem. |
| `name` | Nome completo. |
| `email` | E-mail. |
| `phone` | Telefone (E.164 de preferência). |
| `doc` | Documento (CPF/CNPJ). |
| `gender` | `m` ou `f`. |
| `birth` | Data de nascimento — `YYYY-MM-DD`, `DD/MM/YYYY` ou `YYYYMMDD`. |
| `address` | Endereço (rua/logradouro). |
| `city` / `state` / `country` / `postal` | Localização. Merge por campo com a geolocalização por IP: o que você mandar vence, o resto é preenchido automaticamente. |

## Exemplo Completo

Veja um exemplo de payload enviando dados de lead, informações de compra e encaminhamento para a Meta (Facebook), usando uma Chave de API no modo síncrono:

```bash theme={null}
curl -X POST "https://api.metrito.com/v3/tracking/events?sync=true" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mtk_live_SuaChaveAqui" \
  -d '{
    "container_id": "MTC-55AEW53Y",
    "config": {
      "name": "Purchase",
      "facebook": {
        "name": "Purchase",
        "trackCustom": false
      }
    },
    "data": {
      "value": 99.90,
      "currency": "BRL"
    },
    "lead": {
      "name": "João da Silva",
      "email": "joao@exemplo.com",
      "phone": "+5511999999999",
      "doc": "12345678900",
      "birth": "10/05/1990",
      "city": "Florianópolis",
      "state": "SC",
      "country": "BR",
      "postal": "88000-000"
    },
    "utm": {
      "source_id": "120242075681610084",
      "utm_medium": "ctwa_ad"
    },
    "meta": {
      "url": "https://sujaloja.com.br/checkout"
    }
  }'
```

Resposta de sucesso (modo síncrono):

```json theme={null}
{
  "success": true,
  "event_id": "1758388123_kk78h7u5sf",
  "lead_id": "lead_20250920_xyz789",
  "lead_status": "created",
  "timestamp": 1758388123
}
```

> [!NOTE]
>
> O `eventId` e o `leadId` são gerados automaticamente quando não enviados no payload. O Metrito utiliza deduplicação e *upsert* de leads baseado em e-mail, telefone e documento para evitar registros duplicados.

## config.name vs config.facebook.name

Esses dois campos têm finalidades distintas e é importante entender a diferença:

| Campo | Usado por | Descrição |
| - | - | - |
| `config.name` | **Metrito** | Nome interno do evento exibido nos dashboards do Metrito. |
| `config.facebook.name` | **Meta (Facebook/Instagram)** | Nome do evento enviado à API de Conversões da Meta. Deve seguir o padrão oficial (ex: `Purchase`, `Lead`, `Contact`). |

> [!WARNING]
>
> Se o objeto `config.facebook` for omitido, o evento é registrado no Metrito mas **não** é enviado para a Meta. Se você deseja que a conversão seja atribuída no Meta Ads (CAPI), este bloco é obrigatório.

## Próximos Passos

> **[Integração com o CRM DataCrazy](/tracking/datacrazy-crm)**
>
> Veja um tutorial prático de envio de eventos (incluindo Click to WhatsApp) a partir do CRM DataCrazy.

> **[Testar a Integração](/tracking/testing)**
>
> Verifique se os eventos estão sendo recebidos e processados corretamente.


# Links de redirect
Source: https://docs.metrito.com/tracking/links-de-redirect

Crie links inteligentes que distribuem tráfego e leads entre vários destinos, já rastreados.

## O que são os links de redirect

Um **link de redirect** é um link curto do Metrito que, ao ser clicado, **captura o rastreamento** (UTMs, parâmetros, IP, navegador, geolocalização) e **redireciona** o usuário para um ou mais destinos. São ideais para **testes A/B**, **split de tráfego** e para **distribuir leads** entre vários números de WhatsApp.

Na seção **Links de Redirecionamento** você cria e gerencia esses links:

> *Crie e gerencie links de redirecionamento para suas campanhas. Ideal para testes A/B e split de tráfego.*

## Os dois tipos de link

> **Smart Web**
>
> Para redirecionar usuários para **múltiplos sites**. Use em testes A/B de landing pages ou para dividir tráfego entre páginas.

> **Smart WhatsApp**
>
> Para distribuir leads entre **múltiplos números** de WhatsApp, com uma mensagem padrão que carrega o rastreamento.

## Criar um link

Clique em **Novo Link de Redirecionamento**. No modal **Criar novo link rastreável**:

**1. Nomeie o link**

Em **Nome do Link**, use algo descritivo (ex.: "Campanha Black Friday 2025").

**2. Escolha o tipo**

Selecione **Smart Web** ou **Smart WhatsApp**.

**3. (Smart WhatsApp) Escreva a mensagem padrão**

O campo **Mensagem padrão** é obrigatório — é o texto pré-preenchido na conversa. Ele carrega o rastreamento até o WhatsApp. O usuário pode sobrescrever pela URL com o parâmetro `text` (ex.: `?text=Mensagem personalizada`).

**4. Defina a estratégia de roteamento**

Escolha como os cliques são distribuídos entre os destinos (veja abaixo).

**5. Adicione os destinos**

Em **Smart Web**, informe as **URLs de Destino**. Em **Smart WhatsApp**, informe os **Números do WhatsApp** (formato `+55 11 99999-9999`).

**6. Crie o link**

Clique em **Criar Link de Redirecionamento**. O link gerado é único e pode ser compartilhado em campanhas, redes sociais, bio, etc.

## Estratégias de roteamento

A **Estratégia de Roteamento** define como os usuários são distribuídos entre os destinos:

| Estratégia | Como distribui |
| - | - |
| **Único** | Sempre redireciona para o primeiro destino |
| **Round Robin** | Alterna entre os destinos de forma circular |
| **Aleatório** | Escolhe um destino aleatoriamente |
| **Ponderado** | Distribui com base em **pesos** configurados (a soma deve dar 100%) |
| **Baseado em Horário** | Redireciona conforme o **horário/dia da semana** |

## Avançar por clique ou por mensagem

Para **Smart WhatsApp** com estratégia **Round Robin** ou **Ponderado**, você define quando o roteamento avança para o próximo número — em **Passar para o próximo destino quando:**

> **O link for clicado**
>
> Roda assim que o usuário clica. Mais simples e **não requer** conexão de WhatsApp.

> **Uma mensagem for recebida**
>
> Roda só quando o lead realmente **envia uma mensagem**. **Requer** números conectados na plataforma.

> [!TIP]
>
> "Uma mensagem for recebida" distribui de forma mais justa (cada número recebe leads que realmente escreveram), mas exige que os números estejam [conectados](/tracking/whatsapp). "O link for clicado" funciona sem conexão.

## Rastreamento de WhatsApp via link

O link **Smart WhatsApp** é a forma mais confiável de rastrear conversas: no clique, o Metrito embute os **UTMs e parâmetros** na mensagem padrão. Quando o lead envia a mensagem, o sistema recupera esses dados e **atribui a conversa à campanha**.

> [!WARNING]
>
> A atribuição só se perde se o lead **apagar toda a mensagem padrão** antes de enviar. Por isso a mensagem padrão é obrigatória. Veja mais em [Rastreamento no WhatsApp](/tracking/whatsapp).

## Métricas e edição

Cada link mostra a estratégia, a contagem de **destinos** e métricas:

* **Cliques** — total de cliques no link.
* **Mensagens** — mensagens confirmadas (apenas em Smart WhatsApp).

Só **links inteligentes** (Smart Web e Smart WhatsApp) podem ser editados. Um link **não pode ser excluído** se estiver vinculado a um acionador de evento — desvincule-o na tela de [Eventos](/tracking/eventos) primeiro.

## Disparar evento ao clicar

Quer contar o clique no link como conversão? Crie um evento com o acionador **Clique em link rastreável** na seção de [Eventos](/tracking/eventos) e associe-o a este link.

## Próximos passos

> **[WhatsApp](/tracking/whatsapp)**
>
> Conecte os números que vão receber os leads distribuídos.

> **[Campanhas](/analise/campanhas)**
>
> Veja a atribuição dos cliques e conversas às campanhas.


# Visão geral do rastreamento
Source: https://docs.metrito.com/tracking/overview

Entenda o que é o tracking do Metrito, como ele organiza os dados e o que a tela de Visão Geral mostra.

## O que é o rastreamento do Metrito

O **rastreamento** (ou *tracking*) é a base de tudo no Metrito. É ele que captura cada ponto de contato do cliente — da primeira visita anônima ao seu site até a compra final, passando pelo WhatsApp e por qualquer outro canal — e une tudo em uma jornada só.

Diferente de um analytics comum, o tracking do Metrito:

* **Rastreia em vários canais** — site, WhatsApp, checkout e API
* **Identifica a pessoa** — conecta visitas anônimas a um lead com e-mail e telefone
* **Atribui a receita** — liga cada venda à campanha, conjunto e anúncio que a originou
* **Envia conversões de volta** — repassa os eventos para a Meta (CAPI), otimizando seus anúncios

## O container de rastreamento

Todo o rastreamento de um [projeto](/conceitos/projetos) acontece dentro de um **container** (contêiner de rastreamento). Ele é o "cérebro" que recebe os eventos, identifica os leads e decide para onde mandar cada conversão — parecido com um container do Google Tag Manager, só que pensado para atribuição.

Cada container tem um **ID único** no formato `MTC-XXXXXXX`. Esse ID aparece dentro do script de instalação e identifica o seu projeto em todos os lugares (script, API, extensão de diagnóstico).

> [!NOTE]
>
> Um projeto tem **um** container. Os dados de tracking de projetos diferentes nunca se misturam — cada evento, sessão e lead pertence a exatamente um container.

## Conceitos que você vai encontrar

> **Evento**
>
> Uma ação individual: uma visualização de página, um envio de formulário, um clique ou uma compra.

> **Sessão**
>
> Um período de atividade de um visitante no seu site, com origem, UTMs, dispositivo e localização.

> **Lead**
>
> O contato identificado por trás das sessões — nome, e-mail, telefone e todo o histórico unificado.

> **Jornada**
>
> O caminho completo da pessoa pelo seu funil, juntando várias sessões e canais ao longo do tempo.

### Como a identificação funciona

O Metrito conecta automaticamente as interações de uma mesma pessoa, mesmo que aconteçam em canais e momentos diferentes. Quando o sistema descobre que dois registros são da mesma pessoa (por e-mail, telefone ou outro identificador em comum), ele **unifica** o histórico: visitas ao site, conversas no WhatsApp, formulários e compras passam a viver no mesmo lead.

Na prática, isso significa que **a campanha que trouxe o cliente pela primeira vez recebe o crédito pela venda** — mesmo que ela aconteça dias depois, por outro canal.

## A tela de Visão Geral

Ao abrir o tracking do seu projeto, a primeira tela é a **Visão Geral**. Ela responde à pergunta mais importante: *"meu rastreamento está funcionando agora?"*

No topo fica o card **Status de Recebimento (últimas 24h)**, com um indicador por canal:

| Status | O que significa |
| - | - |
| **Recebendo dados** (verde) | O container recebeu eventos nas últimas 24 horas. Mostra também há quanto tempo foi o último evento. |
| **Sem dados recentes** (vermelho) | Nenhum evento recebido nas últimas 24 horas. Vale conferir a instalação. |

Se você tiver o WhatsApp instalado, aparece um indicador separado para o canal **Web** e outro para o **WhatsApp**, cada um com seu próprio status.

Logo abaixo, a Visão Geral lista os eventos mais recentes por nome (com a contagem e quando foram disparados pela última vez) e os sites/origens que estão enviando dados — incluindo os **Eventos via API**, quando você envia eventos direto pelo servidor.

> [!TIP]
>
> Acabou de instalar o script? Pode levar alguns minutos até o primeiro evento aparecer. Se continuar em **Sem dados recentes**, use a página de [Testes e diagnóstico](/tracking/testing) para investigar.

## As seções do tracking

O menu lateral do tracking espelha as etapas da configuração. Você vai passar por elas nesta documentação:

> **[Instalação no site](/tracking/web-setup)**
>
> Cole o script no seu site e comece a capturar visitantes.

> **[Domínios](/tracking/dominios)**
>
> Rode o tracking no seu próprio domínio e fuja de bloqueios.

> **[Parâmetros/UTM](/tracking/utm-configuration)**
>
> Configure os UTMs dos anúncios para atribuição completa.

> **[Pixels](/tracking/pixels)**
>
> Conecte seus pixels da Meta para receber as conversões (CAPI).

> **[Eventos](/tracking/eventos)**
>
> Crie e configure os eventos e seus acionadores.

> **[Sessões e leads](/tracking/sessoes)**
>
> Audite cada sessão e dispare eventos manualmente.

> **[WhatsApp](/tracking/whatsapp)**
>
> Rastreie conversas e atribua vendas do WhatsApp.

> **[Links de redirect](/tracking/links-de-redirect)**
>
> Distribua tráfego e leads com links inteligentes.


# Pixels
Source: https://docs.metrito.com/tracking/pixels

Cadastre os pixels da Meta que vão receber as conversões do Metrito via API de Conversões (CAPI).

## Para que servem os pixels

O Metrito rastreia tudo dentro do container, mas para **otimizar suas campanhas** ele precisa devolver as conversões para a Meta. Quem recebe essas conversões é o **pixel**. Sem um pixel cadastrado, os eventos ficam só no Metrito e não chegam ao **Gerenciador de Eventos** da Meta.

O envio é feito pela **API de Conversões (CAPI)** — server-side — o que aumenta a qualidade e a cobertura dos dados em relação ao pixel só no navegador.

## Cadastrar um pixel

No menu lateral, abra **Rastreamento** e vá à seção **Pixels**. O card **Conectar Pixels** lista os pixels do container.

**1. Abra o cadastro**

Clique em **Cadastrar novo Pixel**. Abre o modal **Configurações do Pixel**.

**2. Preencha os campos**

| Campo | O que é |
| - | - |
| **ID do Pixel** | O ID do pixel no Gerenciador de Eventos da Meta. Só números, geralmente com 15 ou 16 dígitos. |
| **Nome do Pixel** | Um nome para você identificar (ex.: "Pixel Loja Principal"). |
| **Tipo do Pixel** | **Web (Website)** ou **WhatsApp Business** (veja abaixo). |
| **Token de Acesso da API** | O token da API de Conversões gerado no Gerenciador de Eventos. |

**3. Valide o pixel**

Clique em **Validar Pixel**. O Metrito confere o ID e o token na API da Meta e mostra **Pixel validado com sucesso!** quando está tudo certo.

**4. Crie o pixel**

Clique em **Criar Pixel**. O botão só libera depois da validação: antes disso ele aparece como **Valide o pixel primeiro**.

Depois de criado, o pixel aparece no card **Conectar Pixels** com o seu status: **Ativo**, **Modo de teste** ou **Com problemas**.

> [!TIP]
>
> O **Token de Acesso da API** é gerado no Gerenciador de Eventos da Meta, nas configurações do pixel → **API de Conversões** → **Gerar token de acesso**. É ele que autoriza o Metrito a enviar eventos em nome do seu pixel.

## Web ou WhatsApp Business: qual escolher

Essa é a parte mais importante — e a que mais gera confusão.

> **Web (Website)**
>
> O pixel comum, que todo mundo usa. É o **padrão** e cobre a grande maioria dos casos: site, landing page, checkout e **links de redirect** (inclusive Smart WhatsApp).

> **WhatsApp Business**
>
> Um pixel de **mensagem**, usado **apenas** quando suas campanhas são **100% nativas** de mensagem (direto para o WhatsApp, sem link de redirect).

> [!WARNING]
>
> Um pixel de mensagem **precisa ter sido criado como pixel de mensagem** lá no Gerenciador de Eventos, desde o início. Você **não** pode pegar um pixel Web e simplesmente marcá-lo como **WhatsApp Business** aqui. Se você não criou um pixel de mensagem na Meta, **não** selecione **WhatsApp Business**.

Na dúvida, use **Web (Website)**. Regra prática:

* Usa **link de redirect** (Smart WhatsApp ou Smart Web)? → **Web (Website)**.
* Campanhas **nativas de mensagem** com pixel de mensagem criado na Meta? → **WhatsApp Business**.

## Modo de teste

Em **Configurações de Teste**, você pode ativar o **Modo de Teste** e informar um **Código de Teste**.

Com o modo de teste ligado, os eventos são enviados para a aba de **Testar eventos** do Gerenciador de Eventos — onde você vê cada evento chegando e sendo **deduplicado** quase em tempo real. Esses eventos **não contam como métricas de produção**.

> [!WARNING]
>
> Enquanto o **Modo de Teste** estiver ligado, o pixel **para de enviar eventos reais** e manda tudo só para o ambiente de teste. **Desligue assim que terminar de testar**, ou você fica sem rastreamento de produção.

Fluxo recomendado:

**1. Pegue o código de teste na Meta**

No Gerenciador de Eventos, abra o pixel → aba **Testar eventos** e copie o código exibido.

**2. Ative o Modo de Teste no Metrito**

Cole o código em **Código de Teste** e ligue o **Modo de Teste**.

**3. Dispare eventos e confira**

Navegue no site, faça uma compra de teste ou dispare um evento manual e veja-os chegarem na aba **Testar eventos**.

**4. Desligue o Modo de Teste**

Terminou? Desligue para voltar a enviar eventos de produção.

## Próximos passos

> **[Eventos](/tracking/eventos)**
>
> Defina quais ações são enviadas como conversão para os pixels.

> **[Sessões e leads](/tracking/sessoes)**
>
> Audite o payload exato enviado à Meta e a resposta da CAPI.


# Sessões e leads
Source: https://docs.metrito.com/tracking/sessoes

Audite cada sessão, veja o payload exato enviado à Meta e dispare eventos manuais (offline).

## O que é uma sessão

Uma **sessão** é o conjunto de eventos atribuídos a um **mesmo contato**. O Metrito identifica que aquilo é a mesma pessoa e agrupa tudo:

* **No site** — ao entrar, o visitante recebe um **ID de lead** automático, salvo como cookie no navegador. Os eventos seguintes caem na mesma sessão.
* **No WhatsApp** — o **número de telefone** é o identificador da sessão; as mensagens da conversa vão se acumulando ali.

A tela de **Sessões** é onde você audita, evento por evento, o que o Metrito capturou e o que enviou para a Meta.

## Filtrar e navegar

Você pode filtrar as sessões por:

* **Data** — recorte o período que quer auditar.
* **Origem** — de onde veio o lead.
* **Destino** — para onde foi.

Cada sessão mostra seus eventos **em ordem**, inclusive os **eventos personalizados** que você criou no funil. Assim dá para ver a pessoa avançando: `PageView` → `ViewContent` → `InitiateCheckout` → `Purchase`, por exemplo.

## Auditar um evento

Clique em um evento para abrir todos os seus dados auditáveis:

* **Identificação** — nome do evento, quando foi disparado, fonte, status de rastreamento, **ID do evento**.
* **Lead** — ID do lead, quando foi criado e atualizado, nome, e-mail, telefone, estado, país e geolocalização.
* **Cookies da Meta** — `_fbp` e `_fbc`.
* **API de Conversões** — o **payload exato** enviado à Meta **e a resposta** que a Meta devolveu.

> [!TIP]
>
> Ver o **payload exato da CAPI e a resposta da Meta** é um diferencial do Metrito. Em vez de adivinhar por que um evento "não casou", você lê o que de fato foi enviado e o que voltou.

Para eventos vindos de [checkout](/tracking/checkouts), você também consegue auditar o **webhook** que gerou aquele evento — normalmente uma compra aprovada (`Purchase`).

## Disparar um evento manual (offline)

Algumas conversões acontecem **fora do site**: venda por telefone, fechamento no WhatsApp, atendimento presencial. Para registrá-las, use o **evento manual**.

Clique no botão **Evento manual** (ou no "+" de um lead). No modal **Disparar evento manual**:

**1. Preencha os dados do lead**

Em **Dados do lead**, complete o que faltar: **Nome**, **Email** e **Telefone**.

**2. Selecione o evento**

Em **Selecionar evento**, escolha qualquer evento que você já tenha criado. Por padrão, o evento de compra (`Purchase`) já vem selecionado quando existe.

**3. Para compras, informe valor e moeda**

Se for um evento de compra, preencha **Moeda** (BRL, USD, EUR, GBP, ARS, CLP, MXN) e **Valor** — o valor é obrigatório para eventos de compra.

**4. Dispare**

Clique em **Disparar evento**. Em até 1 minuto o evento é processado e enviado à Meta.

> [!NOTE]
>
> O evento manual só lista eventos que **já existem** no container. Precisa disparar algo que ainda não criou? Crie primeiro na tela de [Eventos](/tracking/eventos) e ele aparecerá aqui.

> [!TIP]
>
> O evento manual é perfeito para quem vende offline ou de forma consultiva: leva a conversão de volta à Meta e melhora a otimização das campanhas, mesmo sem o cliente passar pelo site.

## Logs de eventos

No canto superior direito há o link **Logs de eventos**: uma tela que lista **todos os eventos, um por um**. Filtre por **data**, **fonte** e **nome do evento** para depurar um caso específico — ideal quando você precisa rastrear exatamente um disparo.

## Próximos passos

> **[Eventos](/tracking/eventos)**
>
> Crie os eventos que aparecem aqui e no disparo manual.

> **[Testes e diagnóstico](/tracking/testing)**
>
> Confirme que tudo está chegando e resolva problemas comuns.


# Testes e diagnóstico
Source: https://docs.metrito.com/tracking/testing

Confirme que o rastreamento está funcionando e resolva os problemas mais comuns.

## Como saber se está funcionando

Há quatro formas de confirmar que o tracking está ativo — da mais rápida à mais técnica.

### 1. Verificação de instalação (na própria tela)

Na tela de [Instalação no site](/tracking/web-setup), depois de publicar o site, use o botão de **verificação de instalação**. O Metrito acessa seu site e, se encontrar o script, o card fica verde com o selo **Verificado** e mostra em quantas páginas o script foi detectado.

### 2. Status de Recebimento (últimas 24h)

Abra a [Visão Geral](/tracking/overview). O card **Status de Recebimento (últimas 24h)** mostra, por canal:

* **Recebendo dados** (verde) — chegaram eventos nas últimas 24 horas.
* **Sem dados recentes** (vermelho) — nada nas últimas 24 horas; vale investigar.

Se aparecer **Recebendo dados** no canal **Web**, a instalação está ok. O mesmo vale para o canal **WhatsApp**.

### 3. Extensão Metrito Pixel Helper

A extensão **Metrito Pixel Helper** (Chrome) confirma o rastreamento em tempo real. Com ela instalada, acesse uma página com o pixel e veja:

* se o script foi detectado e qual o **ID do container** (`MTC-XXXXXXX`);
* os **dados do lead** salvos no navegador (ID, nome, e-mail, telefone);
* os **eventos** disparando, conforme acontecem.

O link de instalação da extensão está no botão **Como verificar a instalação**, na tela de instalação do site.

### 4. Ferramentas de desenvolvedor

Abra o DevTools (`F12` ou `Cmd+Shift+I`):

* **Console** — `typeof window.metrito` deve retornar `"function"`.
* **Rede (Network)** — filtre por `mtrt` ou `metrito`. Você deve ver o `mtrttag.js` carregando e requisições `POST` para o seu **subdomínio `sst.`** (ou para a API do Metrito) quando eventos disparam.

## Auditar um evento específico

Para ir além do "chegou ou não", use a tela de [Sessões e leads](/tracking/sessoes): clique em um evento e veja o **payload exato enviado à Meta** e a **resposta da CAPI**. É o jeito mais preciso de entender por que um evento não casou.

## Problemas comuns

### O script não é detectado

> **O script não está carregando**
>
> **Sintomas:** sem selo Verificado, `window.metrito` não existe, nenhuma requisição na aba Rede.
>
> **Possíveis causas e soluções:**
>
> * O script não foi colado na `<head>` de todas as páginas → confira o código-fonte (`Ctrl+U`) e procure por `mtrt`/`MTC-`.
> * Uma **CSP (Content Security Policy)** está bloqueando → libere o domínio do script (e o seu `sst.` se usar bypass) na diretiva `script-src`.

> **É uma loja Shopify**
>
> A Shopify trata scripts de terceiros de forma diferente e a instalação manual no tema **pode não funcionar**. Para Shopify, use o caminho de integração dedicado — fale com o time do Metrito.

> **Bloqueador de anúncios / Safari / iOS interferindo**
>
> **Sintomas:** o script carrega para uns visitantes e não para outros.
>
> **Solução:** ative o **bypass** rodando o tracking no seu próprio domínio. Veja [Domínios e bypass](/tracking/dominios) — requisições para `sst.seudominio.com` são de primeira parte e não são bloqueadas.

### Conflito de parâmetro (VTurb, Panda, Hotmart)

> **O rastreamento 'para' em páginas com player de vídeo ou checkout Hotmart**
>
> **Causa:** players como **VTurb/Panda** usam `src`, e a **Hotmart** usa `src`/`xcod` — o mesmo parâmetro que o Metrito usa por padrão para identificar o visitante.
>
> **Solução:** em [Avançado](/tracking/avancado), troque o **Parâmetro de Identificação de Visitante** (ex.: para `sck`) ou alinhe-o ao que a Hotmart envia (`xcod`).

### UTMs não aparecem

> **Os parâmetros somem após o clique no anúncio**
>
> **Causa:** o template de UTM não está configurado na plataforma de anúncios, ou está no nível errado.
>
> **Solução:** confira se o template está salvo no nível da **campanha** no Gerenciador de Anúncios, e se usa chaves duplas (`{{campaign.id}}`, não `{campaign.id}`). Veja [Parâmetros e UTMs](/tracking/utm-configuration).

> **Os parâmetros são removidos por um redirecionamento**
>
> **Causa:** um encurtador, CDN ou builder de landing page está descartando a query string.
>
> **Solução:** teste colando a URL completa no navegador e garanta que suas regras de redirect **preservam os parâmetros**.

### Eventos não chegam à Meta

> **A compra (Purchase) não dispara**
>
> **Causa:** o rastreamento do checkout está desligado.
>
> **Solução:** ative o interruptor do checkout na seção de [Checkouts](/tracking/checkouts) ou na coluna **Tracking** das [Integrações](/integracoes/overview).

> **Os eventos aparecem só em 'Testar eventos' e não como métrica**
>
> **Causa:** o **Modo de Teste** do pixel ficou ligado.
>
> **Solução:** desligue o Modo de Teste em [Pixels](/tracking/pixels) para voltar a enviar eventos de produção.

> **Nenhum pixel cadastrado**
>
> **Causa:** sem pixel, os eventos ficam só no Metrito.
>
> **Solução:** cadastre um pixel com ID e token válidos e use **Validar Pixel**. Veja [Pixels](/tracking/pixels).

### WhatsApp sem atribuição

> **Conversas do WhatsApp não contam nas Campanhas**
>
> **Causa:** a conversa chegou sem UTM — por perda de **CTWA** (o cliente desativou o rastreamento no aparelho) ou porque a mensagem padrão do link foi apagada.
>
> **Solução:** prefira o link **Smart WhatsApp**, que carrega os UTMs na mensagem padrão. Veja [Rastreamento no WhatsApp](/tracking/whatsapp).

> **O número não está enviando dados**
>
> **Causa:** a instância do WhatsApp não está vinculada ao container.
>
> **Solução:** ative a instância na seção [WhatsApp](/tracking/whatsapp) (card **Conectar WhatsApp**).

## Lista de verificação

**1. Script instalado**

Selo **Verificado** verde na tela de instalação, ou `window.metrito` retorna `"function"` no console.

**2. Recebendo dados**

A Visão Geral mostra **Recebendo dados** nas últimas 24h para o canal Web (e WhatsApp, se usar).

**3. UTMs capturados**

Acesse o site com UTMs de teste e confira a atribuição numa sessão.

**4. Leads identificados**

Envie um formulário com e-mail/telefone e veja o lead na tela de Sessões.

**5. Pixel recebendo**

Eventos com pixel cadastrado aparecem no Gerenciador de Eventos da Meta (pode levar alguns minutos).

**6. Checkout ativo**

O interruptor do checkout está ligado e o `Purchase` dispara nas compras.

## Próximos passos

> **[Sessões e leads](/tracking/sessoes)**
>
> Audite o payload e a resposta da Meta evento por evento.

> **[API de Eventos](/tracking/events-api)**
>
> Envie eventos pelo servidor a partir de qualquer sistema.


# Parâmetros e UTMs
Source: https://docs.metrito.com/tracking/utm-configuration

Configure os parâmetros de URL dos seus anúncios para atribuir cada conversão à campanha certa.

## Por que os UTMs importam

Os parâmetros UTM são o que diz ao Metrito **qual campanha, conjunto e anúncio** trouxe cada visitante. Sem eles, o tráfego é registrado, mas o Metrito não consegue ligar a conversão ao anúncio — e a tela de [Campanhas](/analise/campanhas) fica sem dados de resultado.

O Metrito usa o formato **`nome|id`**: cada parâmetro carrega o nome legível (para os relatórios) **e** o ID técnico (para conciliar com a plataforma) de uma vez só.

## A tela Parâmetros/UTM

Na seção **Parâmetros/UTM** do tracking há um card do **Meta Ads** que já monta a string de UTM pronta para você. Clique em **Copiar template** (ou clique na própria string) e cole nos parâmetros de URL dos seus anúncios.

A string gerada segue este padrão:

```
utm_source=facebook&utm_campaign={{campaign.name}}|{{campaign.id}}&utm_medium={{adset.name}}|{{adset.id}}&utm_content={{ad.name}}|{{ad.id}}&utm_term={{placement}}
```

Cada parâmetro tem um papel:

| Parâmetro | Papel | Valor dinâmico |
| - | - | - |
| `utm_source` | Fonte | `facebook` (fixo) |
| `utm_campaign` | Campanha | `{{campaign.name}}\|{{campaign.id}}` |
| `utm_medium` | Conjunto | `{{adset.name}}\|{{adset.id}}` |
| `utm_content` | Anúncio | `{{ad.name}}\|{{ad.id}}` |
| `utm_term` | Posicionamento | `{{placement}}` |
| `fbclid` | Click ID | capturado automaticamente da URL |

## Como configurar no Meta Ads

**1. Copie o template no Metrito**

Na seção **Parâmetros/UTM**, clique em **Copiar template** no card do Meta Ads.

**2. Abra o Gerenciador de Anúncios**

Acesse o [Gerenciador de Anúncios](https://adsmanager.facebook.com), selecione a campanha e clique em **Editar**.

**3. Cole nos Parâmetros de URL**

Role até a seção **Rastreamento** e cole o template no campo **Parâmetros de URL**.

**4. Publique**

Clique em **Publicar**. Todos os anúncios passam a incluir os parâmetros automaticamente.

> [!TIP]
>
> Configure no **nível da campanha** para que todos os conjuntos e anúncios herdem os parâmetros. A Meta substitui os `{{placeholders}}` pelos valores reais no momento do clique.

### O que o Metrito extrai

De uma URL como:

```
https://seusite.com.br/produtos?utm_source=facebook&utm_campaign=Promoção Verão|123456789&utm_medium=Mobile iOS|987654321&utm_content=Vídeo 50%25 Off|456789123&utm_term=feed&fbclid=IwAR1a2b3c
```

O Metrito interpreta e guarda:

| Campo | Valor |
| - | - |
| Fonte | `facebook` |
| Campanha | `Promoção Verão` · ID `123456789` |
| Conjunto | `Mobile iOS` · ID `987654321` |
| Anúncio | `Vídeo 50% Off` · ID `456789123` |
| Posicionamento | `feed` |

## Outras plataformas

Embora a tela traga o template do Meta pronto, você pode aplicar o mesmo padrão `nome|id` em outras fontes.

> **Google Ads**
>
> Use um **modelo de acompanhamento** no nível da campanha (Configurações → Opções de URL da campanha):
>
> ```
> {lpurl}?utm_source=google&utm_campaign={campaignname}|{campaignid}&utm_medium={adgroupname}|{adgroupid}&utm_content={creative}&utm_term={keyword}&gclid={gclid}
> ```

> **TikTok Ads**
>
> Em **Rastreamento → Parâmetros de URL**, use:
>
> ```
> utm_source=tiktok&utm_campaign={{campaign.name}}|{{campaign_id}}&utm_medium={{adgroup.name}}|{{adgroup_id}}&utm_content={{ad.name}}|{{ad_id}}&ttclid={{ttclid}}
> ```

## Boas práticas

1. **Configure no nível da campanha** — vale para todos os anúncios de uma vez.
2. **Mantenha o padrão `nome|id`** — garante nomes legíveis e IDs técnicos.
3. **Teste antes de escalar** — rode uma campanha pequena e confira a atribuição na tela de Campanhas.
4. **Não troque o padrão no meio do caminho** — pode quebrar a atribuição histórica.
5. **Use nomes limpos e consistentes** — relatórios melhores começam em nomes bons.

## Próximos passos

> **[Pixels](/tracking/pixels)**
>
> Conecte seus pixels da Meta para receber as conversões.

> **[Campanhas](/analise/campanhas)**
>
> Veja o desempenho dos anúncios cruzado com os resultados.


# Instalação no site
Source: https://docs.metrito.com/tracking/web-setup

Cole o script do Metrito no seu site para rastrear visitantes, sessões e conversões.

## Antes de começar

A primeira tela do tracking é a **Configure seu Tracking**. Nela você escolhe onde quer rastrear seus leads: no **Site / Landing Page**, no **WhatsApp Business**, ou nos dois. Esta página cobre a instalação no site.

Você vai precisar de:

1. Acesso à [plataforma](https://app.metrito.com) com o projeto já criado
2. Acesso para editar o HTML do seu site (ou ao gerenciador de tags)

## Passo 1 — Adicione o script no site

No card **Adicione o script no site**, copie o código do tracking e cole **dentro da tag `<head>`** de todas as páginas. O script já vem com o ID do seu container (`MTC-XXXXXXX`) preenchido.

```html theme={null}
<!-- Metrito Tracking Code -->
<script>
  !(function(t,r,a,c,k,i,n,g){
  a="mtrt";c="script";k=window;i=document;n=new URL(location);g=n.searchParams;
  if(k[a])return;t="/"+a+"tag.js?id="+(g.get(a+"id")||t);n.host="sst."+n.host.replace(/^w{3}\./i,"");
  [g.get(a+"url")||n.origin].concat(r).reduce(function(w,x){return w.catch(x?new Promise(function(y,z){
  n=i.createElement(c);n.src=x+t;n.async=!0;n.onload=y;n.onerror=z;
  g=i.getElementsByTagName(c)[0];g.parentNode.insertBefore(n,g)}):
  Promise.reject())},Promise.reject());a=k[a]=function(){a.track?
  a.track.apply(a,arguments):a.queue.push(arguments)};a.ver=1;a.queue=[];
  k.metrito||(k.metrito=a)})(
  "MTC-XXXXXXX",["https://api.metrito.com/v2"]);
</script>
<!-- End Metrito Tracking Code -->
```

A tela oferece dois botões para facilitar:

> **Copiar script**
>
> Copia o código pronto para colar manualmente no `<head>`.

> **Copiar prompt**
>
> Copia o código **já embrulhado em um prompt** para colar em ferramentas de IA e *builders* como Lovable, v0, Cursor, Claude Code e similares — a IA instala o script para você.

> [!WARNING]
>
> **Não instale o script direto no tema da Shopify.** A Shopify trata scripts de terceiros de forma diferente e a instalação manual no `<head>` pode não funcionar como esperado. Para Shopify, fale com o time do Metrito para usar o caminho de integração dedicado.

> [!NOTE]
>
> O script deve carregar em **todas** as páginas que você quer rastrear — inclusive páginas de obrigado, checkout e landing pages. Quanto mais cedo no `<head>`, melhor a captura.

## Passo 2 — Verifique a instalação

Depois de publicar o site com o script, volte à tela e use o botão de **verificação de instalação**. O Metrito acessa o seu site e confirma se o script está presente. Quando encontra, o card fica verde com o selo **Verificado** e mostra em quantas páginas o script foi detectado.

Você também pode confirmar em tempo real com a extensão **Metrito Pixel Helper** — veja [Testes e diagnóstico](/tracking/testing).

## Passo 3 — Ative o bypass (recomendado)

Logo abaixo da instalação fica o passo **Bypass IOS / Ad Blockers**. Ele faz o script rodar no **seu próprio domínio** (first-party), evitando bloqueios de navegadores como Safari/iOS e de extensões de bloqueio de anúncios — o que aumenta bastante a taxa de captura de dados.

É opcional, mas altamente recomendado. A configuração é feita na seção de [Domínios](/tracking/dominios).

## O que o script captura automaticamente

Assim que carrega, o script dispara um evento de **PageView** a cada página e coleta, sem nenhum código a mais:

| Dado | De onde vem |
| - | - |
| URL, título e referenciador da página | Navegador |
| Parâmetros UTM (`utm_source`, `utm_campaign`, etc.) | Query string da URL |
| IDs de clique (`fbclid`, `gclid`, `ttclid`) | Query string da URL |
| Parâmetro de identificação (`src` / `sck`) | Query string da URL |
| Cookies de primeira parte (`_fbp`, `_ga`) | Navegador |
| Dispositivo, navegador e idioma | User-Agent |
| Geolocalização (país, cidade, região) | IP do visitante |

Os UTMs da entrada são guardados em cookie e se mantêm pela sessão inteira, então todos os eventos seguintes carregam a atribuição original.

## Próximos passos

> **[Domínios e bypass](/tracking/dominios)**
>
> Rode o tracking no seu domínio e fuja dos bloqueios.

> **[Parâmetros e UTMs](/tracking/utm-configuration)**
>
> Configure os UTMs dos anúncios para atribuir as campanhas.


# Rastreamento no WhatsApp
Source: https://docs.metrito.com/tracking/whatsapp

Conecte suas conversas do WhatsApp ao container para atribuir vendas e enviar conversões aos pixels.

## Por que rastrear o WhatsApp

No Brasil, boa parte das vendas passa pelo WhatsApp: o cliente vê o anúncio, clica, conversa e só então compra. Se o WhatsApp ficar de fora do rastreamento, esse tráfego vira "venda sem origem" — e o anúncio que trouxe o cliente não recebe o crédito.

O Metrito conecta suas **conexões de WhatsApp** ao container. A partir daí, cada conversa entra na mesma [jornada](/tracking/overview) das sessões do site, e as conversões são enviadas de volta aos **pixels da Meta**, otimizando suas campanhas.

> [!NOTE]
>
> O rastreamento de WhatsApp do V3 **não usa mais** o antigo parâmetro `wa_session` na URL. A ligação é feita conectando a instância do WhatsApp ao container, como descrito abaixo.

## Conecte seu WhatsApp

São duas etapas: primeiro você **conecta o número** na tela de Integrações; depois **liga esse número ao container** no Rastreamento.

**1. Conecte o número em Integrações**

No menu lateral, abra **Integrações** e clique em **Adicionar Integração**. No filtro **Mensagens**, escolha **WhatsApp**.

**2. Escolha como conectar**

No passo **Como conectar o WhatsApp**, escolha **Metrito API** (QR Code, na infraestrutura da Metrito) ou **Cloud API** (a API oficial da Meta) e siga o fluxo. O passo a passo de cada uma está em [Conexão de WhatsApp](/integracoes/whatsapp).

**3. Ligue o número ao container**

Volte ao **Rastreamento** e abra a seção **WhatsApp**. No card **Conectar WhatsApp**, ligue o interruptor ao lado do número.

O card **Conectar WhatsApp** lista todos os números já conectados ao projeto:

> *Selecione as instâncias do WhatsApp conectadas a este domínio para enviar dados de interação e conversão para os Pixels.*

Cada linha é uma instância (número). Só as que estão com o interruptor **ligado** enviam conversas e conversões deste container para os pixels. Use a busca **Buscar por 'nome' ou 'número'** para achar uma instância. Se ainda não houver nenhuma, a tela mostra **"Nenhuma conexão WhatsApp no momento."**

> [!WARNING]
>
> Não use o botão **Nova conexão WhatsApp**, logo abaixo do card. Ele ainda abre o fluxo antigo de QR Code, do Zapito, e a criação falha com a mensagem **"O Zapito foi descontinuado. Conexões por QR Code agora são feitas pela API Metrito."** Conecte o número sempre por **Integrações** → **Adicionar Integração**, como no passo 1.

## As duas formas de rastrear o WhatsApp

Existem dois caminhos para levar uma conversa de WhatsApp até a atribuição. Eles podem (e costumam) conviver.

### 1. Campanha nativa de mensagem (CTWA)

Quando você roda **campanhas de mensagem nativas** — com o número vinculado na BM e o anúncio levando direto para o WhatsApp — o clique chega com o **CTWA** (*Click to WhatsApp*). Aquela primeira mensagem traz a "miniatura" do anúncio.

Nesse momento, o Metrito **dispara o evento `Contact` automaticamente**, cria o lead, inicia a sessão e passa a capturar os eventos seguintes da conversa.

> [!WARNING]
>
> **O CTWA pode se perder.** Se o cliente desativou o rastreamento do WhatsApp no aparelho dele (uma opção do iPhone, por exemplo), o CTWA não chega — e isso é **impossível de corrigir**, porque a campanha é nativa e o usuário sai do Instagram/Facebook direto para o WhatsApp. Nesses casos, alguns disparos de `Contact` podem ser perdidos.

### 2. Link de redirect (Smart WhatsApp)

A forma mais robusta é usar um **link de redirect do tipo Smart WhatsApp**. Em vez de mandar o tráfego direto, o anúncio leva a um link do Metrito que redireciona para o WhatsApp já com tudo rastreado.

Como funciona: no clique, o Metrito captura os **UTMs e parâmetros** e os embute na **mensagem padrão** que vai para o WhatsApp. Quando o cliente envia a mensagem, o sistema recupera esses dados e atribui a conversa à campanha correta.

> [!WARNING]
>
> A única forma de perder a atribuição aqui é se o cliente **apagar toda a mensagem padrão** antes de enviar. Por isso a mensagem padrão é obrigatória nesse tipo de link.

**Vantagens do redirect:** como o redirecionamento passa pela web, ele também captura **IP, navegador e geolocalização** — dados que a campanha nativa não traz.

> **[Criar um link Smart WhatsApp](/tracking/links-de-redirect)**
>
> Veja como criar o link, escolher a estratégia de roteamento e distribuir entre vários números.

## Por que os UTMs são decisivos

A tela de [Campanhas](/analise/campanhas) usa **UTMs** para atribuir o resultado. Se uma conversa perde o CTWA ou chega sem UTM, ela **não aparece como venda atribuída** ali — mesmo que a venda tenha acontecido. É por isso que o link de redirect, que garante os UTMs na mensagem, é o caminho mais confiável.

## Disparar eventos a partir de mensagens

Você pode transformar **palavras ou frases** de uma conversa em um evento de conversão — por exemplo, disparar uma compra quando o operador envia "Pedido confirmado".

Isso é configurado na seção de [Eventos](/tracking/eventos), com o acionador **Mensagem no WhatsApp** e os **Termos de acionamento**.

> [!WARNING]
>
> Os termos precisam **bater exatamente** com o que foi enviado — incluindo acentos, espaços e maiúsculas/minúsculas.

## Do WhatsApp para o site: identifique o lead com `mlid`

Muitas vezes a conversa começa no WhatsApp e o lead segue para uma página do seu site: uma página de vendas, um formulário, a página que leva ao checkout. Para essa visita entrar na **mesma jornada** da conversa, o link que você manda no WhatsApp precisa levar o **Lead ID** do contato no parâmetro `mlid`:

```
https://seusite.com/oferta?mlid=lead_5511999998888
```

O Lead ID de um contato do WhatsApp é `lead_` seguido do número completo, **só com dígitos**: DDI + DDD + número, sem `+`, espaços, parênteses ou traços.

| Número do contato | O que vai no link |
| - | - |
| +55 (11) 99999-8888 | `?mlid=lead_5511999998888` |
| +351 912 345 678 | `?mlid=lead_351912345678` |

Quando a página abre com o `mlid`, o script do Metrito reconhece o visitante como o mesmo lead da conversa, guarda esse Lead ID e passa a repassá-lo nos links que saem da página, como os de checkout.

> [!WARNING]
>
> Nas páginas do site, o lead **só** é identificado pelo `mlid`. Colocar o Lead ID em um UTM, como `utm_content=lead_5511999998888`, **não funciona** no site: a visita não é ligada à conversa do WhatsApp.

> [!NOTE]
>
> Nos checkouts é diferente. A venda chega pelo webhook do checkout, e o Metrito procura o `lead_...` em **todos** os parâmetros que o checkout repassa, inclusive nos UTMs. Por isso `utm_content=lead_...` funciona num link direto de checkout, mas não numa página do seu site.

## Boas práticas

1. **Prefira o link de redirect** — garante UTMs, `Contact` e dados de web mesmo quando o CTWA falha.
2. **Mantenha a mensagem padrão** nos links Smart WhatsApp — apagá-la quebra a atribuição.
3. **Conecte o número certo ao container certo** — cada container é um [projeto](/conceitos/projetos); não misture marcas.
4. **Use termos de acionamento específicos** — evita disparar conversão em qualquer "oi".

## Próximos passos

> **[Links de redirect](/tracking/links-de-redirect)**
>
> Distribua leads entre números e garanta a atribuição.

> **[Pixels](/tracking/pixels)**
>
> Entenda quando usar pixel Web e quando usar pixel de mensagem.