# 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.
</Warning>

## 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.
</Tip>

## 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.
</Note>

## 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.
</Tip>

## 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

<CardGroup>
  <Card title="Configuração de UTMs" icon="bullseye-arrow" href="/tracking/utm-configuration">
    Configure os UTMs para que cadastros e vendas apareçam por campanha.
  </Card>

  <Card title="Contas de anúncio" icon="rectangle-ad" href="/integracoes/contas-de-anuncio">
    Conecte e gerencie as contas que alimentam esta tela.
  </Card>
</CardGroup>


# 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.
</Note>

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.
</Tip>

## 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

<CardGroup>
  <Card title="Rastreamento via WhatsApp" icon="comment-dots" href="/tracking/whatsapp">
    Entenda como as conversas viram leads identificados.
  </Card>

  <Card title="Visão geral do rastreamento" icon="chart-mixed" href="/tracking/overview">
    Como o Metrito identifica e unifica os contatos.
  </Card>
</CardGroup>


# 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.
</Note>

## 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.
</Tip>

## 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

<CardGroup>
  <Card title="Checkouts e comissões" icon="credit-card" href="/integracoes/checkouts-e-comissoes">
    Entenda como a comissão define o valor líquido das vendas.
  </Card>

  <Card title="Integração personalizada" icon="puzzle-piece" href="/integracoes/integracao-personalizada">
    Envie pedidos de qualquer sistema próprio para o Metrito.
  </Card>
</CardGroup>


# 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.</Warning>


# 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

<CardGroup>
  <Card title="API Key (Recomendado)" icon="key">
    Chave de serviço com escopos granulares. Ideal para integrações, automações e acesso programático.
  </Card>

  <Card title="JWT Token" icon="lock">
    Token obtido via login com e-mail e senha. Usado para integrações que precisam de contexto de usuário.
  </Card>

  <Card title="OAuth 2.0" icon="arrows-rotate" href="/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.
  </Card>
</CardGroup>

***

## 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..."
```

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

### Como criar uma API Key

<Steps>
  <Step title="Acesse as Configurações">
    Na plataforma Metrito, clique no menu lateral e acesse **Configurações** (ícone de engrenagem).
  </Step>

  <Step title="Vá até Chaves de API">
    Na página de configurações, selecione a aba **Chaves de API**.
  </Step>

  <Step title="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
  </Step>

  <Step title="Copie o token">
    Após a criação, copie o token imediatamente. **Ele não será exibido novamente** por segurança.
  </Step>
</Steps>

### 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.</Warning>

***

## 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.</Note>

***

## 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

<CardGroup>
  <Card title="Plataforma" icon="grid-2" href="/api-reference/autenticar-na-plataforma">
    Login, listagem de projetos e conexões. Ponto de partida para descobrir IDs.
  </Card>

  <Card title="Rastreamento" icon="satellite-dish" href="/api-reference/enviar-evento">
    Envie eventos de rastreamento e webhooks de transação de qualquer plataforma.
  </Card>

  <Card title="Dados" icon="chart-mixed" href="/api-reference/listar-campos-disponíveis">
    Consulte métricas de anúncios com filtros, granularidade temporal e conversão de moeda.
  </Card>
</CardGroup>

## Fluxo Típico de Integração

<Steps>
  <Step title="Autentique-se">
    Crie uma [API Key](/api-reference/authentication) na plataforma ou faça [login](/api-reference/autenticar-na-plataforma) para obter um JWT.
  </Step>

  <Step title="Descubra seus projetos">
    Use `GET /v3/projects` para listar os projetos disponíveis e obter o `project_id`.
  </Step>

  <Step title="Liste as conexões">
    Use `GET /v3/projects/{project_id}/connections` para ver as fontes de dados conectadas.
  </Step>

  <Step title="Consulte campos disponíveis">
    Use `GET /v3/fields` para descobrir quais métricas e dimensões estão disponíveis.
  </Step>

  <Step title="Consulte métricas">
    Use `POST /v3/query` com o `project_id`, campos desejados e período para obter os dados.
  </Step>
</Steps>


# 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.

  <a href="mailto:contato@metrito.com">
    → Entrar em contato com o time do Metrito
  </a>

  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.
</Warning>

***

## Como funciona o fluxo

<Steps>
  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## 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..."
```

<Info>
  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.
</Info>

***

## 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

<CardGroup>
  <Card title="Códigos de uso único" icon="shield-check">
    O código de autorização (`code`) expira em 5 minutos e é invalidado imediatamente após o primeiro uso. Não pode ser reutilizado.
  </Card>

  <Card title="Proteção contra CSRF" icon="lock">
    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.
  </Card>

  <Card title="redirect_uri obrigatória" icon="link">
    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.
  </Card>

  <Card title="client_secret no servidor" icon="server">
    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.
  </Card>
</CardGroup>

***

## 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:

<Card title="Solicitar client_id e client_secret" icon="envelope" href="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.
</Card>


# 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.</Tip>

### 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.</Warning>

***

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

<Info>
  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.
</Info>

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.
</Warning>

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

<CardGroup>
  <Card title="Conectar integrações" icon="plug" href="/integracoes/overview">
    Traga seus dados de anúncios e vendas para o projeto.
  </Card>

  <Card title="Montar seu dashboard" icon="gauge" href="/dashboard/overview">
    Visualize as métricas do projeto em um painel personalizado.
  </Card>
</CardGroup>


# 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.
</Note>

## 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.
</Tip>

## Próximos passos

<CardGroup>
  <Card title="Projetos" icon="folder" href="/conceitos/projetos">
    Entenda o que é um projeto e como organizar os seus.
  </Card>

  <Card title="Compartilhar integrações" icon="share-nodes" href="/integracoes/compartilhar-integracoes">
    Reaproveite uma mesma conexão em vários projetos da organização.
  </Card>
</CardGroup>


# 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.

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

## 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:

<CardGroup>
  <Card title="Um projeto por marca" icon="store">
    O modelo mais comum para quem tem o próprio negócio. Cada loja/marca vira um projeto.
  </Card>

  <Card title="Um projeto por cliente" icon="users">
    Ideal para agências e gestores de tráfego. Cada cliente é um projeto isolado.
  </Card>

  <Card title="Um projeto por produto" icon="box">
    Útil quando produtos têm operações, checkouts e públicos bem distintos.
  </Card>

  <Card title="Por ambiente / mercado" icon="globe">
    Separe operações em países ou moedas diferentes em projetos próprios.
  </Card>
</CardGroup>

<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**.
</Warning>

## 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

<CardGroup>
  <Card title="Configurações do projeto" icon="gear" href="/conceitos/configuracoes-do-projeto">
    Defina nome, logo, moeda padrão e fuso horário.
  </Card>

  <Card title="Integrações" icon="plug" href="/integracoes/overview">
    Conecte as fontes de dados que alimentam o projeto.
  </Card>
</CardGroup>


# 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:

<CardGroup>
  <Card title="Templates" icon="layer-group">
    Layouts prontos para começar rápido. Aplique um template e ajuste a partir dele. Veja [Templates](/dashboard/templates).
  </Card>

  <Card title="Widgets" icon="shapes">
    A galeria de widgets disponíveis, organizada por categoria (Principais, Gráficos, Úteis, Especiais). Use a busca para encontrar rápido.
  </Card>
</CardGroup>

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

<Steps>
  <Step title="Adicione um widget">
    Clique no widget desejado na barra lateral. Ele é inserido no painel.
  </Step>

  <Step title="Reposicione">
    Arraste o widget para a posição desejada no grid.
  </Step>

  <Step title="Redimensione">
    Use a alça no canto inferior direito do widget para ajustar largura e altura.
  </Step>
</Steps>

## 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.
</Tip>

## 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).
</Note>

## Próximos passos

<CardGroup>
  <Card title="Widgets disponíveis" icon="shapes" href="/dashboard/widgets">
    Veja cada tipo de widget e para que serve.
  </Card>

  <Card title="Templates" icon="layer-group" href="/dashboard/templates">
    Comece de um layout pronto ou salve o seu.
  </Card>
</CardGroup>


# 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.

<CardGroup>
  <Card title="Link externo (com senha)" icon="link">
    Um link protegido por senha. Qualquer pessoa com o link e a senha consegue visualizar o painel.
  </Card>

  <Card title="Embed (token de acesso)" icon="code">
    Um código `<iframe>` para incorporar o dashboard em sistemas externos. O acesso é controlado por um token gerado automaticamente.
  </Card>
</CardGroup>

## Link externo (com senha)

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

<Steps>
  <Step title="Selecione “Link externo”">
    No modal **Compartilhar Dashboard**, escolha o modo **Link externo**.
  </Step>

  <Step title="Copie o link de acesso">
    O Metrito gera uma URL no formato `https://app.metrito.com/d/XXXXXXXX`. Use o botão de copiar.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<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.
</Warning>

## 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.

<Steps>
  <Step title="Selecione “Embed”">
    No modal de compartilhamento, escolha o modo **Embed**.
  </Step>

  <Step title="Habilite o embed">
    Ative a opção **Habilitar embed**. Isso gera um **token único** que permite o acesso sem senha.
  </Step>

  <Step title="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>
    ```
  </Step>
</Steps>

<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.
</Warning>

## 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

<CardGroup>
  <Card title="Filtros e granularidade" icon="filter" href="/dashboard/filtros-e-granularidade">
    Ajuste a visão antes de compartilhar.
  </Card>

  <Card title="Configurações do projeto" icon="gear" href="/conceitos/configuracoes-do-projeto">
    Defina logo e nome — eles aparecem no painel compartilhado.
  </Card>
</CardGroup>


# 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.      |

<Info>
  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).
</Info>

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.
</Tip>

## 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.
</Note>

## 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.
</Tip>

## 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

<CardGroup>
  <Card title="Widgets disponíveis" icon="shapes" href="/dashboard/widgets">
    Veja o que cada widget pode exibir.
  </Card>

  <Card title="Compartilhar dashboard" icon="share-nodes" href="/dashboard/compartilhamento">
    Compartilhe a visão filtrada com seu time ou cliente.
  </Card>
</CardGroup>


# 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).
</Tip>

## 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.
</Note>

## 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

<CardGroup>
  <Card title="Builder de dashboard" icon="table-cells" href="/dashboard/builder">
    Adicione, configure e organize os widgets do seu painel.
  </Card>

  <Card title="Widgets disponíveis" icon="shapes" href="/dashboard/widgets">
    Conheça todos os tipos de widget que você pode usar.
  </Card>

  <Card title="Filtros e granularidade" icon="filter" href="/dashboard/filtros-e-granularidade">
    Recorte os dados por período, fonte, produto e mais.
  </Card>

  <Card title="Compartilhar dashboard" icon="share-nodes" href="/dashboard/compartilhamento">
    Envie o painel por link com senha ou incorpore via iframe.
  </Card>
</CardGroup>


# 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

<Steps>
  <Step title="Abra o builder">
    Clique em **Editar** no dashboard para entrar no modo de edição.
  </Step>

  <Step title="Vá até a aba Templates">
    Na barra lateral à esquerda, selecione a aba **Templates**.
  </Step>

  <Step title="Escolha um template">
    Selecione o layout desejado. Os widgets são adicionados ao painel já configurados.
  </Step>

  <Step title="Ajuste e salve">
    Reorganize, configure ou remova widgets conforme a sua necessidade e salve.
  </Step>
</Steps>

## 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.
</Tip>

## Próximos passos

<CardGroup>
  <Card title="Builder de dashboard" icon="table-cells" href="/dashboard/builder">
    Ajuste o template aplicado adicionando e configurando widgets.
  </Card>

  <Card title="Compartilhar dashboard" icon="share-nodes" href="/dashboard/compartilhamento">
    Entregue o painel para o cliente por link ou embed.
  </Card>
</CardGroup>


# 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

<CardGroup>
  <Card title="Card de Métrica" icon="hashtag">
    Exibe um único número em destaque — faturamento, ROAS, lucro, número de vendas, etc. É o widget mais usado do dashboard.
  </Card>

  <Card title="Tabela" icon="table">
    Mostra dados em linhas e colunas, como vendas por fonte ou por produto. Ótimo para comparar itens lado a lado.
  </Card>

  <Card title="Funil de Conversão" icon="filter">
    Visualiza a jornada por etapas — cliques → visualizações → cadastros → checkout → vendas — com a taxa de conversão entre elas.
  </Card>
</CardGroup>

## Gráficos

<CardGroup>
  <Card title="Gráfico de Linha" icon="chart-line">
    Evolução de uma métrica ao longo do tempo. Ideal para acompanhar tendências (faturamento por dia, por exemplo).
  </Card>

  <Card title="Gráfico de Barras" icon="chart-column">
    Compara valores entre categorias ou períodos.
  </Card>

  <Card title="Gráfico de Área" icon="chart-area">
    Como o de linha, mas com a área preenchida — útil para enfatizar volume acumulado.
  </Card>

  <Card title="Gráfico de Pizza" icon="chart-pie">
    Mostra a participação de cada parte no total, como vendas por produto ou por método de pagamento.
  </Card>
</CardGroup>

## Úteis

<Card title="Divisor" icon="grip-lines">
  Um separador visual para organizar o painel em seções. Não exibe dados — serve para dar respiro e estrutura ao layout.
</Card>

## Especiais

<CardGroup>
  <Card title="Vendas por Horário" icon="clock">
    Distribui as vendas pelos horários do dia. Útil para identificar os melhores horários de conversão.
  </Card>

  <Card title="Vendas por Dia da Semana" icon="calendar-days">
    Mostra em quais dias da semana você mais vende.
  </Card>

  <Card title="Taxa de Aprovação" icon="percent">
    Acompanha a taxa de aprovação por método de pagamento (cartão, Pix, boleto).
  </Card>
</CardGroup>

<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.
</Tip>

## Próximos passos

<CardGroup>
  <Card title="Builder de dashboard" icon="table-cells" href="/dashboard/builder">
    Adicione e configure esses widgets no seu painel.
  </Card>

  <Card title="Filtros e granularidade" icon="filter" href="/dashboard/filtros-e-granularidade">
    Recorte o que os widgets exibem por período e por filtros.
  </Card>
</CardGroup>


# 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.

<Card title="Comece em 5 minutos" icon="rocket" href="/quickstart">
  Instale o rastreamento, configure seus UTMs e comece a ver dados.
</Card>

## Conceitos fundamentais

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

<Columns>
  <Card title="Organizações" icon="building" href="/conceitos/organizacoes">
    O nível mais alto: sua empresa, seus membros e seu plano.
  </Card>

  <Card title="Projetos" icon="folder" href="/conceitos/projetos">
    Cada marca, cliente ou produto que você acompanha.
  </Card>

  <Card title="Configurações do projeto" icon="gear" href="/conceitos/configuracoes-do-projeto">
    Nome, logo, moeda padrão e fuso horário.
  </Card>
</Columns>

## Dashboard

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

<Columns>
  <Card title="Visão geral do Dashboard" icon="gauge" href="/dashboard/overview">
    A barra de controles e como o painel funciona.
  </Card>

  <Card title="Builder e widgets" icon="shapes" href="/dashboard/builder">
    Adicione, configure e organize os widgets.
  </Card>

  <Card title="Filtros e granularidade" icon="filter" href="/dashboard/filtros-e-granularidade">
    Recorte os dados por período, fonte e produto.
  </Card>

  <Card title="Compartilhar dashboard" icon="share-nodes" href="/dashboard/compartilhamento">
    Link com senha ou embed via iframe.
  </Card>
</Columns>

## Análise de dados

As telas onde você acompanha desempenho e resultados.

<Columns>
  <Card title="Campanhas" icon="rectangle-ad" href="/analise/campanhas">
    Desempenho dos anúncios cruzado com resultados de negócio.
  </Card>

  <Card title="Vendas" icon="cart-shopping" href="/analise/vendas">
    Todas as transações e pedidos do projeto.
  </Card>

  <Card title="Leads" icon="user-group" href="/analise/leads">
    Os contatos identificados ao longo da jornada.
  </Card>
</Columns>

## Integrações

Conecte as fontes que alimentam toda a plataforma.

<Columns>
  <Card title="O que são integrações" icon="plug" href="/integracoes/overview">
    O conceito de fonte de entrada, status e a coluna tracking.
  </Card>

  <Card title="Adicionar uma integração" icon="circle-plus" href="/integracoes/adicionar-integracao">
    Conecte contas de anúncio, checkouts e WhatsApp.
  </Card>

  <Card title="Checkouts e comissões" icon="credit-card" href="/integracoes/checkouts-e-comissoes">
    Configure moeda, fuso e tipo de comissão.
  </Card>

  <Card title="Integração personalizada" icon="puzzle-piece" href="/integracoes/integracao-personalizada">
    Envie pedidos de qualquer sistema próprio.
  </Card>
</Columns>

## Rastreamento

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

<Columns>
  <Card title="Visão geral do rastreamento" icon="chart-mixed" href="/tracking/overview">
    Projetos, eventos, sessões e identificação de usuários.
  </Card>

  <Card title="Instalação do pixel web" icon="code" href="/tracking/web-setup">
    Instale o script do Metrito no seu site.
  </Card>

  <Card title="Configuração de UTMs" icon="bullseye-arrow" href="/tracking/utm-configuration">
    Atribuição completa de campanhas, conjuntos e criativos.
  </Card>

  <Card title="Rastreamento via WhatsApp" icon="comment-dots" href="/tracking/whatsapp">
    Conecte conversas do WhatsApp às sessões web.
  </Card>
</Columns>


# 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.

<Steps>
  <Step title="Acesse a tela de Integrações">
    No menu lateral, abra a seção de **Integrações**.
  </Step>

  <Step title="Clique em “Adicionar integração”">
    O botão verde fica no **canto superior direito** da tela.
  </Step>

  <Step title="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)
  </Step>

  <Step title="Siga o fluxo de conexão">
    Cada fonte tem o seu fluxo: autorização (OAuth) para contas de anúncio, webhook para checkouts, leitura de QR Code para WhatsApp. Conclua os passos indicados.
  </Step>
</Steps>

<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.
</Tip>

## 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

<CardGroup>
  <Card title="Contas de anúncio" icon="rectangle-ad" href="/integracoes/contas-de-anuncio">
    Detalhes da conexão com Meta Ads e seus status.
  </Card>

  <Card title="Checkouts e comissões" icon="credit-card" href="/integracoes/checkouts-e-comissoes">
    Configure comissão, moeda e fuso da conexão de vendas.
  </Card>

  <Card title="WhatsApp" icon="whatsapp" href="/integracoes/whatsapp">
    Conecte um número via QR Code.
  </Card>

  <Card title="Integração personalizada" icon="puzzle-piece" href="/integracoes/integracao-personalizada">
    Conecte qualquer sistema próprio.
  </Card>
</CardGroup>


# 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)).

## 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.

Por isso, ao conectar, você escolhe o **tipo de comissão** — é ele que 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. |

<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).
</Note>

<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.
</Tip>

## Próximos passos

<CardGroup>
  <Card title="Tela de Vendas" icon="cart-shopping" href="/analise/vendas">
    Acompanhe os pedidos vindos dos seus checkouts.
  </Card>

  <Card title="Integração personalizada" icon="puzzle-piece" href="/integracoes/integracao-personalizada">
    Não achou seu checkout? Envie pedidos por uma fonte personalizada.
  </Card>
</CardGroup>


# 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

<CardGroup>
  <Card title="Conta de anúncio que atende várias marcas" icon="rectangle-ad">
    Uma mesma conta do Meta roda campanhas de produtos que você acompanha em projetos diferentes.
  </Card>

  <Card title="Agência com visões por cliente" icon="users">
    Centralize a conexão e distribua os dados para os projetos de cada cliente.
  </Card>

  <Card title="Checkout com múltiplos produtos" icon="credit-card">
    Um checkout vende produtos que você prefere analisar em projetos separados.
  </Card>

  <Card title="Evitar reconexões e tokens duplicados" icon="key">
    Menos conexões para manter — e menos pontos de falha (como token expirado).
  </Card>
</CardGroup>

## 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ó.
</Note>

<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).
</Tip>

## Próximos passos

<CardGroup>
  <Card title="O que são integrações" icon="plug" href="/integracoes/overview">
    Revise o conceito de fonte de entrada de dados.
  </Card>

  <Card title="Organizações" icon="building" href="/conceitos/organizacoes">
    Entenda o nível onde as integrações são compartilhadas.
  </Card>
</CardGroup>


# 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.
</Warning>

A solução é direta:

<Steps>
  <Step title="Remova a conta">
    Na tela de Integrações, remova a conexão que está com **Token expirado**.
  </Step>

  <Step title="Adicione a conta novamente">
    Use **Adicionar integração** e reconecte a mesma conta, refazendo a autorização.
  </Step>

  <Step title="Aguarde a sincronização">
    O Metrito volta a importar os dados e o status retorna para **Ativo**.
  </Step>
</Steps>

## Próximos passos

<CardGroup>
  <Card title="Tela de Campanhas" icon="rectangle-ad" href="/analise/campanhas">
    Veja o desempenho das campanhas dessas contas.
  </Card>

  <Card title="Compartilhar integrações" icon="share-nodes" href="/integracoes/compartilhar-integracoes">
    Use a mesma conta de anúncio em vários projetos.
  </Card>
</CardGroup>


# 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).
</Note>

## Como funciona

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Pronto">
    O Metrito valida o payload, faz a atribuição via UTMs e o pedido passa a aparecer nas Vendas e nos relatórios.
  </Step>
</Steps>

## 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`.
</Warning>

### 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.
</Tip>

<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).
</Warning>

## Próximos passos

<CardGroup>
  <Card title="Referência da API — Pedidos" icon="terminal" href="/tracking/events-api">
    Detalhes do endpoint e dos campos opcionais.
  </Card>

  <Card title="Tela de Vendas" icon="cart-shopping" href="/analise/vendas">
    Acompanhe os pedidos enviados pela sua integração.
  </Card>
</CardGroup>


# 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.
</Tip>

## Próximos passos

<CardGroup>
  <Card title="Adicionar uma integração" icon="circle-plus" href="/integracoes/adicionar-integracao">
    Passo a passo para conectar uma nova fonte.
  </Card>

  <Card title="Compartilhar integrações" icon="share-nodes" href="/integracoes/compartilhar-integracoes">
    Use a mesma conexão em vários projetos.
  </Card>

  <Card title="Contas de anúncio" icon="rectangle-ad" href="/integracoes/contas-de-anuncio">
    Conecte Meta Ads e gerencie status.
  </Card>

  <Card title="Checkouts e comissões" icon="credit-card" href="/integracoes/checkouts-e-comissoes">
    Configure moeda, fuso e tipo de comissão.
  </Card>
</CardGroup>


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

Conecte um número de WhatsApp ao Metrito via QR Code para gerar eventos de rastreamento.

## 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** — peça importante para atribuir leads e conversas às campanhas que os originaram.

Hoje a conexão é feita pela **API não oficial**: você lê um **QR Code** e pareia o seu aparelho, igual ao WhatsApp Web.

<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.
</Note>

## Como conectar

<Steps>
  <Step title="Adicione a integração de WhatsApp">
    Em **Adicionar integração**, escolha a categoria **Mensagens** e selecione **WhatsApp**.
  </Step>

  <Step title="Leia o QR Code">
    No celular, abra **WhatsApp → Aparelhos conectados → Conectar um aparelho** e aponte para o QR Code exibido na tela. Enquanto não for lido, o status fica em **Aguardando leitura de QR Code**.
  </Step>

  <Step title="Conexão concluída">
    Após o pareamento, o status muda para **Conectado** e o Metrito passa a escutar os eventos do número.
  </Step>
</Steps>

## 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 os eventos estão sendo escutados. |
| **Desconectado**                  | O pareamento caiu. Reconecte lendo o QR Code novamente.     |

## Atribuição entre canais

Conectar o número é só uma parte. Para que uma conversa de WhatsApp se conecte à jornada do cliente na web (e o anúncio receba o crédito pela venda), há um mecanismo próprio de atribuição entre canais.

<Card title="Rastreamento via WhatsApp" icon="comment-dots" href="/tracking/whatsapp">
  Entenda como conversas do WhatsApp se conectam às sessões web via `wa_session` para atribuição completa.
</Card>

## Próximos passos

<CardGroup>
  <Card title="Tela de Leads" icon="user-group" href="/analise/leads">
    Veja os contatos identificados, inclusive pelo WhatsApp.
  </Card>

  <Card title="Adicionar uma integração" icon="circle-plus" href="/integracoes/adicionar-integracao">
    Conecte outras fontes de dados ao projeto.
  </Card>
</CardGroup>


# 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

<Steps>
  <Step title="Crie um Contêiner de Rastreamento">
    Um **contêiner** é 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 contêiner possui um identificador único no formato `MTC-XXXXXXX`.

    1. Acesse a [Plataforma Metrito](https://app.metrito.com)
    2. Vá em **Configurações** > **Contêiner de Rastreamento**
    3. Crie um novo contêiner para o seu domínio
    4. Copie o **ID do Contêiner** (ex: `MTC-5X35GWQ`)

    <Tip>Cada contêiner é completamente isolado — eventos, leads e dados de atribuição de um contêiner nunca se misturam com os de outro.</Tip>
  </Step>

  <Step title="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 projeto

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

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

  <Step title="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).
  </Step>
</Steps>

## 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

<CardGroup>
  <Card title="Visão Geral do Rastreamento" icon="chart-mixed" href="/tracking/overview">
    Entenda como contêineres, eventos, sessões e jornadas funcionam juntos.
  </Card>

  <Card title="API de Eventos" icon="terminal" href="/tracking/events-api">
    Envie eventos pelo servidor a partir do Shopify, WooCommerce ou qualquer backend.
  </Card>

  <Card title="Rastreamento via WhatsApp" icon="comment-dots" href="/tracking/whatsapp">
    Conecte conversas do WhatsApp às sessões web.
  </Card>

  <Card title="Testes e Diagnóstico" icon="bug" href="/tracking/testing">
    Verifique sua instalação e resolva problemas.
  </Card>
</CardGroup>


# 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

<CardGroup>
  <Card title="Players de vídeo (VTurb, Panda)" icon="video">
    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.
  </Card>

  <Card title="Checkout Hotmart" icon="cart-shopping">
    A **Hotmart** trabalha com `src` / `xcod`. Para a atribuição casar, **alinhe o parâmetro** ao que a Hotmart envia (`src` ou `xcod`).
  </Card>
</CardGroup>

<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".
</Warning>

<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.
</Tip>

## 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.

<Steps>
  <Step title="Cadastre a URL de destino">
    Informe a URL do webhook (do n8n, Make, Zapier ou do seu sistema) que vai receber os eventos.
  </Step>

  <Step title="Receba o payload">
    A cada evento, o Metrito faz um `POST` com o mesmo payload que processa internamente.
  </Step>

  <Step title="Use como quiser">
    Trate o payload no seu fluxo — notificar um CRM, enviar um e-mail, atualizar uma planilha, etc.
  </Step>
</Steps>

<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.
</Warning>

## Próximos passos

<CardGroup>
  <Card title="Sessões e leads" icon="list" href="/tracking/sessoes">
    Veja o payload exato que é capturado e encaminhado.
  </Card>

  <Card title="API de Eventos" icon="terminal" href="/tracking/events-api">
    Envie eventos pelo servidor, direto para o container.
  </Card>
</CardGroup>


# 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.

<Steps>
  <Step title="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).
  </Step>

  <Step title="Ative o rastreamento">
    Ligue o interruptor da conexão. A partir daí, cada compra aprovada vira um evento `Purchase`.
  </Step>
</Steps>

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

## 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**.
</Warning>

## 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.
</Tip>

## 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

<CardGroup>
  <Card title="Pixels" icon="square-code" href="/tracking/pixels">
    Garanta que há um pixel cadastrado para receber o `Purchase`.
  </Card>

  <Card title="Vendas" icon="dollar-sign" href="/analise/vendas">
    Acompanhe as compras aprovadas e a receita atribuída.
  </Card>
</CardGroup>


# 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`
</Tip>

## 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.
</Warning>

## 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",
  "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).
* **`config.facebook`**: Informa ao Metrito como esse evento deve ser encaminhado para a API de Conversões da Meta.
* **`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.

<Card title="API de eventos (visão geral)" icon="terminal" href="/tracking/events-api">
  Conheça melhor os conceitos de `container_id`, `config.name` e `config.facebook.name`.
</Card>

**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**.
</Note>

## 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**.
</Note>

## Adicionar e verificar um domínio

<Steps>
  <Step title="Adicione o domínio">
    Clique em **Adicionar Domínio** e informe o **domínio principal (TLD)** — ex.: `seudominio.com`, **sem** subdomínios.
  </Step>

  <Step title="Crie o registro CNAME">
    No seu provedor de DNS, adicione o registro abaixo.

    | Tipo    | Host/Nome | Valor             | TTL     |
    | ------- | --------- | ----------------- | ------- |
    | `CNAME` | `sst`     | `sst.metrito.com` | `14400` |
  </Step>

  <Step title="Verifique o DNS">
    De volta ao Metrito, clique em **Verificar DNS** no domínio adicionado. A propagação pode levar **até 24 horas**.
  </Step>
</Steps>

<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`.
</Tip>

## 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.
</Warning>

## Próximos passos

<CardGroup>
  <Card title="Instalação no site" icon="code" href="/tracking/web-setup">
    Volte para instalar (ou reinstalar) o script já com o bypass.
  </Card>

  <Card title="Parâmetros e UTMs" icon="ampersand" href="/tracking/utm-configuration">
    Configure os UTMs dos anúncios para a atribuição completa.
  </Card>
</CardGroup>


# 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:

<CardGroup>
  <Card title="Visualização de Página (PageView)" icon="eye">
    Criado automaticamente quando o container é criado. Dispara a cada página carregada. Pode ser removido, se quiser.
  </Card>

  <Card title="Compra aprovada (Purchase)" icon="cart-shopping">
    Criado automaticamente quando você conecta um [checkout](/tracking/checkouts). Dispara `Purchase` para a Meta a cada compra aprovada em qualquer checkout conectado e ativo.
  </Card>
</CardGroup>

<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).
</Note>

## Criar um evento

Clique em **Novo evento**. O assistente tem três passos: **Evento**, **Acionador** e **Ajustes**.

<Steps>
  <Step title="Evento">
    Dê um nome ao evento e, se quiser enviá-lo à Meta, associe-o a um evento padrão (ex.: `Lead`, `Contact`, `Purchase`).
  </Step>

  <Step title="Acionador">
    Escolha **o que** dispara o evento (veja a lista de acionadores abaixo).
  </Step>

  <Step title="Ajustes">
    Refine **onde** e **quando** o acionador vale — páginas incluídas/excluídas, elemento-alvo, termos, etc.
  </Step>
</Steps>

## Os acionadores

O acionador é o gatilho do evento. Eles cobrem ações no **site**, **WhatsApp**, **checkout** e **links rastreáveis**:

| 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                                |

## 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.
</Tip>

### 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.
</Warning>

### 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

<CardGroup>
  <Card title="Checkouts" icon="cart-shopping" href="/tracking/checkouts">
    Conecte seu checkout para o `Purchase` disparar sozinho.
  </Card>

  <Card title="Sessões e leads" icon="list" href="/tracking/sessoes">
    Veja os eventos disparando em ordem e audite cada um.
  </Card>
</CardGroup>


# 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.               |

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

<Info>
  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.
</Info>

## 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.
</Warning>

## Próximos Passos

<CardGroup>
  <Card
    title="Integração com o CRM DataCrazy
"
    icon="plug"
    href="/tracking/datacrazy-crm"
  >
    Veja um tutorial prático de envio de eventos (incluindo Click to WhatsApp) a partir do CRM DataCrazy.
  </Card>

  <Card title="Testar a Integração" icon="bug" href="/tracking/testing">
    Verifique se os eventos estão sendo recebidos e processados corretamente.
  </Card>
</CardGroup>


# 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

<CardGroup>
  <Card title="Smart Web" icon="globe">
    Para redirecionar usuários para **múltiplos sites**. Use em testes A/B de landing pages ou para dividir tráfego entre páginas.
  </Card>

  <Card title="Smart WhatsApp" icon="whatsapp">
    Para distribuir leads entre **múltiplos números** de WhatsApp, com uma mensagem padrão que carrega o rastreamento.
  </Card>
</CardGroup>

## Criar um link

Clique em **Novo Link de Redirecionamento**. No modal **Criar novo link rastreável**:

<Steps>
  <Step title="Nomeie o link">
    Em **Nome do Link**, use algo descritivo (ex.: "Campanha Black Friday 2025").
  </Step>

  <Step title="Escolha o tipo">
    Selecione **Smart Web** ou **Smart WhatsApp**.
  </Step>

  <Step title="(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`).
  </Step>

  <Step title="Defina a estratégia de roteamento">
    Escolha como os cliques são distribuídos entre os destinos (veja abaixo).
  </Step>

  <Step title="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`).
  </Step>

  <Step title="Crie o link">
    Clique em **Criar Link de Redirecionamento**. O link gerado é único e pode ser compartilhado em campanhas, redes sociais, bio, etc.
  </Step>
</Steps>

## 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:**

<CardGroup>
  <Card title="O link for clicado" icon="arrow-pointer">
    Roda assim que o usuário clica. Mais simples e **não requer** conexão de WhatsApp.
  </Card>

  <Card title="Uma mensagem for recebida" icon="message">
    Roda só quando o lead realmente **envia uma mensagem**. **Requer** números conectados na plataforma.
  </Card>
</CardGroup>

<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.
</Tip>

## 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).
</Warning>

## 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

<CardGroup>
  <Card title="WhatsApp" icon="whatsapp" href="/tracking/whatsapp">
    Conecte os números que vão receber os leads distribuídos.
  </Card>

  <Card title="Campanhas" icon="rectangle-ad" href="/analise/campanhas">
    Veja a atribuição dos cliques e conversas às campanhas.
  </Card>
</CardGroup>


# 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.
</Note>

## Conceitos que você vai encontrar

<CardGroup>
  <Card title="Evento" icon="bolt">
    Uma ação individual: uma visualização de página, um envio de formulário, um clique ou uma compra.
  </Card>

  <Card title="Sessão" icon="clock">
    Um período de atividade de um visitante no seu site, com origem, UTMs, dispositivo e localização.
  </Card>

  <Card title="Lead" icon="user">
    O contato identificado por trás das sessões — nome, e-mail, telefone e todo o histórico unificado.
  </Card>

  <Card title="Jornada" icon="route">
    O caminho completo da pessoa pelo seu funil, juntando várias sessões e canais ao longo do tempo.
  </Card>
</CardGroup>

### 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.
</Tip>

## As seções do tracking

O menu lateral do tracking espelha as etapas da configuração. Você vai passar por elas nesta documentação:

<CardGroup>
  <Card title="Instalação no site" icon="code" href="/tracking/web-setup">
    Cole o script no seu site e comece a capturar visitantes.
  </Card>

  <Card title="Domínios" icon="globe" href="/tracking/dominios">
    Rode o tracking no seu próprio domínio e fuja de bloqueios.
  </Card>

  <Card title="Parâmetros/UTM" icon="ampersand" href="/tracking/utm-configuration">
    Configure os UTMs dos anúncios para atribuição completa.
  </Card>

  <Card title="Pixels" icon="square-code" href="/tracking/pixels">
    Conecte seus pixels da Meta para receber as conversões (CAPI).
  </Card>

  <Card title="Eventos" icon="arrow-pointer" href="/tracking/eventos">
    Crie e configure os eventos e seus acionadores.
  </Card>

  <Card title="Sessões e leads" icon="list" href="/tracking/sessoes">
    Audite cada sessão e dispare eventos manualmente.
  </Card>

  <Card title="WhatsApp" icon="whatsapp" href="/tracking/whatsapp">
    Rastreie conversas e atribua vendas do WhatsApp.
  </Card>

  <Card title="Links de redirect" icon="link" href="/tracking/links-de-redirect">
    Distribua tráfego e leads com links inteligentes.
  </Card>
</CardGroup>


# 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

Na seção **Pixels**, clique em **Cadastrar novo Pixel**. No modal **Configurações do Pixel**, preencha:

| Campo                      | O que é                                                     |
| -------------------------- | ----------------------------------------------------------- |
| **ID do Pixel**            | O ID do pixel no Gerenciador de Eventos da Meta             |
| **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 de CAPI gerado no Gerenciador de Eventos            |

Depois de preencher, use **Validar Pixel** para confirmar que o ID e o token estão corretos antes de salvar.

<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.
</Tip>

## Web ou WhatsApp Business: qual escolher

Essa é a parte mais importante — e a que mais gera confusão.

<CardGroup>
  <Card title="Web (Website)" icon="globe">
    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).
  </Card>

  <Card title="WhatsApp Business" icon="whatsapp">
    Um pixel de **mensagem**, usado **apenas** quando suas campanhas são **100% nativas** de mensagem (direto para o WhatsApp, sem link de redirect).
  </Card>
</CardGroup>

<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**.
</Warning>

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.
</Warning>

Fluxo recomendado:

<Steps>
  <Step title="Pegue o código de teste na Meta">
    No Gerenciador de Eventos, abra o pixel → aba **Testar eventos** e copie o código exibido.
  </Step>

  <Step title="Ative o Modo de Teste no Metrito">
    Cole o código em **Código de Teste** e ligue o **Modo de Teste**.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="Desligue o Modo de Teste">
    Terminou? Desligue para voltar a enviar eventos de produção.
  </Step>
</Steps>

## Próximos passos

<CardGroup>
  <Card title="Eventos" icon="arrow-pointer" href="/tracking/eventos">
    Defina quais ações são enviadas como conversão para os pixels.
  </Card>

  <Card title="Sessões e leads" icon="list" href="/tracking/sessoes">
    Audite o payload exato enviado à Meta e a resposta da CAPI.
  </Card>
</CardGroup>


# 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.
</Tip>

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**:

<Steps>
  <Step title="Preencha os dados do lead">
    Em **Dados do lead**, complete o que faltar: **Nome**, **Email** e **Telefone**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Dispare">
    Clique em **Disparar evento**. Em até 1 minuto o evento é processado e enviado à Meta.
  </Step>
</Steps>

<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.
</Note>

<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.
</Tip>

## 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

<CardGroup>
  <Card title="Eventos" icon="arrow-pointer" href="/tracking/eventos">
    Crie os eventos que aparecem aqui e no disparo manual.
  </Card>

  <Card title="Testes e diagnóstico" icon="bug" href="/tracking/testing">
    Confirme que tudo está chegando e resolva problemas comuns.
  </Card>
</CardGroup>


# 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

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="É 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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

### Conflito de parâmetro (VTurb, Panda, Hotmart)

<Accordion title="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`).
</Accordion>

### UTMs não aparecem

<AccordionGroup>
  <Accordion title="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).
  </Accordion>

  <Accordion title="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**.
  </Accordion>
</AccordionGroup>

### Eventos não chegam à Meta

<AccordionGroup>
  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

### WhatsApp sem atribuição

<AccordionGroup>
  <Accordion title="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).
  </Accordion>

  <Accordion title="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**).
  </Accordion>
</AccordionGroup>

## Lista de verificação

<Steps>
  <Step title="Script instalado">Selo **Verificado** verde na tela de instalação, ou `window.metrito` retorna `"function"` no console.</Step>
  <Step title="Recebendo dados">A Visão Geral mostra **Recebendo dados** nas últimas 24h para o canal Web (e WhatsApp, se usar).</Step>
  <Step title="UTMs capturados">Acesse o site com UTMs de teste e confira a atribuição numa sessão.</Step>
  <Step title="Leads identificados">Envie um formulário com e-mail/telefone e veja o lead na tela de Sessões.</Step>
  <Step title="Pixel recebendo">Eventos com pixel cadastrado aparecem no Gerenciador de Eventos da Meta (pode levar alguns minutos).</Step>
  <Step title="Checkout ativo">O interruptor do checkout está ligado e o `Purchase` dispara nas compras.</Step>
</Steps>

## Próximos passos

<CardGroup>
  <Card title="Sessões e leads" icon="list" href="/tracking/sessoes">
    Audite o payload e a resposta da Meta evento por evento.
  </Card>

  <Card title="API de Eventos" icon="terminal" href="/tracking/events-api">
    Envie eventos pelo servidor a partir de qualquer sistema.
  </Card>
</CardGroup>


# 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

<Steps>
  <Step title="Copie o template no Metrito">
    Na seção **Parâmetros/UTM**, clique em **Copiar template** no card do Meta Ads.
  </Step>

  <Step title="Abra o Gerenciador de Anúncios">
    Acesse o [Gerenciador de Anúncios](https://adsmanager.facebook.com), selecione a campanha e clique em **Editar**.
  </Step>

  <Step title="Cole nos Parâmetros de URL">
    Role até a seção **Rastreamento** e cole o template no campo **Parâmetros de URL**.
  </Step>

  <Step title="Publique">
    Clique em **Publicar**. Todos os anúncios passam a incluir os parâmetros automaticamente.
  </Step>
</Steps>

<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.
</Tip>

### 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.

<AccordionGroup>
  <Accordion title="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}
    ```
  </Accordion>

  <Accordion title="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}}
    ```
  </Accordion>
</AccordionGroup>

## 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

<CardGroup>
  <Card title="Pixels" icon="square-code" href="/tracking/pixels">
    Conecte seus pixels da Meta para receber as conversões.
  </Card>

  <Card title="Campanhas" icon="rectangle-ad" href="/analise/campanhas">
    Veja o desempenho dos anúncios cruzado com os resultados.
  </Card>
</CardGroup>


# 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:

<CardGroup>
  <Card title="Copiar script" icon="copy">
    Copia o código pronto para colar manualmente no `<head>`.
  </Card>

  <Card title="Copiar prompt" icon="robot">
    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ê.
  </Card>
</CardGroup>

<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.
</Warning>

<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.
</Note>

## 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

<CardGroup>
  <Card title="Domínios e bypass" icon="globe" href="/tracking/dominios">
    Rode o tracking no seu domínio e fuja dos bloqueios.
  </Card>

  <Card title="Parâmetros e UTMs" icon="ampersand" href="/tracking/utm-configuration">
    Configure os UTMs dos anúncios para atribuir as campanhas.
  </Card>
</CardGroup>


# 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.
</Note>

## Conecte seu WhatsApp

Na seção **WhatsApp** do tracking você encontra o card **Conectar WhatsApp**:

> *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) já conectada. Para vincular uma ao container, ligue o botão ao lado dela. Para conectar um número novo:

<Steps>
  <Step title="Clique em Nova conexão WhatsApp">
    O botão **Nova conexão WhatsApp** abre o fluxo de conexão.
  </Step>

  <Step title="Dê um nome à conexão">
    Use um nome que identifique o número (ex.: "Vendas SP").
  </Step>

  <Step title="Leia o QR Code">
    Escaneie o QR Code com o WhatsApp do aparelho, como faria no WhatsApp Web. Pronto — o número está conectado.
  </Step>
</Steps>

<Note>
  Use a busca **Buscar por 'nome' ou 'número'** para achar uma instância. Se não houver nenhuma, a tela mostra **"Nenhuma conexão WhatsApp no momento."** A conexão também pode ser feita pela tela de [integrações de WhatsApp](/integracoes/whatsapp).
</Note>

## 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.
</Warning>

### 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.
</Warning>

**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.

<Card title="Criar um link Smart WhatsApp" icon="link" href="/tracking/links-de-redirect">
  Veja como criar o link, escolher a estratégia de roteamento e distribuir entre vários números.
</Card>

## 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.
</Warning>

## 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

<CardGroup>
  <Card title="Links de redirect" icon="link" href="/tracking/links-de-redirect">
    Distribua leads entre números e garanta a atribuição.
  </Card>

  <Card title="Pixels" icon="square-code" href="/tracking/pixels">
    Entenda quando usar pixel Web e quando usar pixel de mensagem.
  </Card>
</CardGroup>