# Findie — referência de integração para agentes de IA

> Público: agentes de IA de código (Claude Code, Cursor, Codex, Copilot…) instalando o Findie no projeto de um maker. Base desta instância: https://findie-maker.com. Todos os caminhos abaixo são relativos a ela.

Este documento descreve SOMENTE o que está implementado. Se algo não estiver aqui, não existe — não invente endpoints nem parâmetros.

## Sumário

1. Conceitos
2. Tráfego · px.js
3. Eventos pelo navegador (coletor público)
4. Eventos pelo servidor (API autenticada)
5. Leitura dos agregados (5b links · 5c métricas de negócio · 5d webhooks · 5e diagnóstico)
6. Erros, limites e cotas
7. Privacidade e exclusão
8. Receitas por framework
9. Checklist do agente
10. Solução de problemas

---

## 1. Conceitos

- **Projeto**: o produto do maker no Findie. Tem um id (UUID).
- **Ambiente**: todo projeto tem exatamente dois, `test` e `production`, cada um com id próprio (UUID). Chaves, coletores, eventos e cotas são separados por ambiente. Use TEST em desenvolvimento/staging e PRODUCTION no build de produção.
- **Coletor** (`col_test_…` / `col_prod_…`): identificador PÚBLICO e só-escrita de um ambiente. Pode ficar no código do navegador. Não lê dados nem autentica a API administrativa.
- **Chave secreta** (`fnd_test_…` / `fnd_prod_…`): credencial do servidor, mostrada uma única vez ao ser criada no painel. Tem escopos, expira (30, 90, 365 dias; padrão 90) e pode ser revogada. Máximo 10 chaves ativas por ambiente. Uma chave só vale para o seu projeto/ambiente.
- **Escopos**: `events:write` (enviar eventos pela API), `analytics:read` (ler agregados), `links:read`/`links:write` (links curtos, seção 5b). `metrics:read`/`metrics:write` (métricas de negócio, seção 5c). `webhooks:read`/`webhooks:write` (webhooks assinados, seção 5d). `diagnostics:write` (erros, logs e traces do servidor, seção 5e).
- **Dois níveis**:
  - Nível 1 · Tráfego — `px.js` envia `page_view` automaticamente (acessos, visitantes únicos, top páginas, top referrers).
  - Nível 2 · Eventos — tipos customizados (`signup`, `checkout_completed`…) contados por tipo/dia.
- **Processamento**: síncrono. Quando a resposta é 202 (não duplicado), o evento já foi gravado E contado nos agregados — aparece imediatamente no painel e nas leituras. Se a contagem falhar, nada é gravado e a resposta é 503 (pode repetir com o mesmo eventId).
- Onde o maker pega os ids: painel do projeto → Integrações (coletor e chaves) e Configuração (ids dos ambientes). Peça a ele se não estiverem no prompt.

---

## 2. Tráfego · px.js

Uma tag, em todas as páginas, idealmente no `<head>` do layout raiz:

```html
<script src="https://findie-maker.com/px.js" data-collector="col_prod_SEU_COLETOR" defer></script>
```

Comportamento:
- Envia um `page_view` no carregamento e a cada troca de rota em SPA (intercepta `history.pushState`, `history.replaceState` e `popstate`). `replaceState` para o mesmo pathname não reenvia.
- Envia só o **pathname** (sem querystring nem hash) e, no primeiro carregamento, o **referrer**. O servidor reduz o referrer ao domínio e ignora navegação interna.
- Sem cookies e sem storage. Usa `navigator.sendBeacon` (`text/plain`, sem preflight) com fallback para `fetch` com `keepalive`.
- Respeita Do-Not-Track e Global Privacy Control por padrão (não envia nada).

Atributos da tag:

| Atributo | Padrão | Efeito |
|---|---|---|
| `data-collector` | obrigatório | id do coletor (`col_…`) |
| `data-visitor-id` | — | visitante identificado já no 1º pageview |
| `data-auto` | `true` | `"false"` desliga pageviews automáticos (use `findie.pageview()`) |
| `data-respect-dnt` | `true` | `"false"` envia mesmo com DNT/GPC — não mude sem pedido explícito do maker |
| `data-api` | origem do script | outra origem para a API |
| `data-consent` | — | `"required"`: nada é enviado até `findie.consent(true)` (o script não grava nada no navegador) |

API global `window.findie`:

```js
findie.identify("user_123")          // visitante identificado (null/"" limpa)
findie.pageview({ url: "/checkout", visitorId: "user_123" }) // manual
findie.track("signup", { plan: "free" })   // evento de negócio pelo navegador (props planas, até 20)
findie.consent(true)                      // com data-consent="required": libera a coleta (false desliga)
```

Visitantes únicos:
- **Anônimo** (padrão): o servidor deriva um hash diário de IP + user-agent + domínio com salt rotativo; não guarda IP; não correlaciona entre dias.
- **Identificado** (opt-in): com `visitorId`, guarda `hash(visitorId + salt do projeto)` — conta o mesmo usuário entre dias e dispositivos. O id cru nunca é persistido. Use o id interno do usuário, nunca e-mail, e só se o projeto já expõe esse id no cliente.

CSP: libere `https://findie-maker.com` em `script-src` e `connect-src`.

---

## 3. Eventos pelo navegador (coletor público)

```
POST https://findie-maker.com/api/v1/collect/{collectorId}
Content-Type: application/json   (text/plain também é aceito)
```

Sem autenticação. Opcionalmente o maker restringe as **origens permitidas** do coletor (Integrações) — mitigação contra uso do id em outros sites, não autenticação; fora da lista → 403 `origin_not_allowed`. CORS liberado para qualquer origem (`Access-Control-Allow-Origin: *`, sem credenciais). Limite de 60 requisições/minuto por IP e projeto.

Envelope:

```json
{
  "eventId": "8f1c…",
  "type": "signup",
  "occurredAt": "2026-11-10T12:00:00.000Z",
  "properties": { "plan": "free" }
}
```

| Campo | Regra |
|---|---|
| `eventId` | obrigatório, string ≤ 200; chave de idempotência (reenviar o mesmo id não conta 2×) |
| `type` | obrigatório, string ≤ 200; use snake_case estável; `page_view` é reservado |
| `occurredAt` | opcional, ISO-8601 ou epoch ms; entre 7 dias atrás e 5 min no futuro; padrão = agora |
| `properties` | opcional, objeto plano; até 20 chaves; strings ≤ 1024 chars; sem objetos/arrays aninhados |
| `schemaVersion` | opcional, string; padrão "1" |
| corpo | ≤ 16 KiB |

Helper recomendado:

```ts
const FINDIE_COLLECT = "https://findie-maker.com/api/v1/collect/col_prod_SEU_COLETOR"

export function track(type: string, properties?: Record<string, string | number | boolean | null>) {
  try {
    fetch(FINDIE_COLLECT, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      keepalive: true,
      body: JSON.stringify({ eventId: crypto.randomUUID(), type, occurredAt: new Date().toISOString(), properties }),
    }).catch(() => {})
  } catch {}
}
```

---

## 4. Eventos pelo servidor (API autenticada)

```
POST https://findie-maker.com/api/v1/projects/{projectId}/environments/{environmentId}/events
Authorization: Bearer $FINDIE_SECRET_KEY
Content-Type: application/json
```

- Mesmo envelope da seção 3.
- Escopo `events:write`. A chave precisa ser do MESMO projeto e ambiente do caminho (senão 404).
- Leia a chave de `FINDIE_SECRET_KEY` (ou equivalente da stack). Adicione a variável ao `.env.example` sem valor.
- Idempotência: para eventos ligados a uma entidade, use `eventId` determinístico (ex.: `order_paid:{orderId}`); assim retries e webhooks repetidos contam uma vez.
- Retry com backoff só em 503 e erros de rede (até 3 tentativas). Não repita em 4xx.

Node (fetch nativo):

```ts
// server-only
const URL = `https://findie-maker.com/api/v1/projects/${process.env.FINDIE_PROJECT_ID}/environments/${process.env.FINDIE_ENVIRONMENT_ID}/events`

export async function trackServer(type: string, properties?: Record<string, unknown>, eventId = crypto.randomUUID()) {
  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      const res = await fetch(URL, {
        method: "POST",
        headers: { Authorization: `Bearer ${process.env.FINDIE_SECRET_KEY}`, "Content-Type": "application/json" },
        body: JSON.stringify({ eventId, type, occurredAt: new Date().toISOString(), properties }),
      })
      if (res.status !== 503) return res.status
    } catch {}
    await new Promise((r) => setTimeout(r, 500 * 2 ** attempt))
  }
}
```

Python:

```python
import os, uuid, datetime, requests

def track_server(type_, properties=None, event_id=None):
    url = f"https://findie-maker.com/api/v1/projects/{os.environ['FINDIE_PROJECT_ID']}/environments/{os.environ['FINDIE_ENVIRONMENT_ID']}/events"
    body = {"eventId": event_id or str(uuid.uuid4()), "type": type_,
            "occurredAt": datetime.datetime.now(datetime.timezone.utc).isoformat(), "properties": properties or {}}
    return requests.post(url, json=body, timeout=5,
                         headers={"Authorization": f"Bearer {os.environ['FINDIE_SECRET_KEY']}"}).status_code
```

cURL:

```bash
curl -X POST "https://findie-maker.com/api/v1/projects/$FINDIE_PROJECT_ID/environments/$FINDIE_ENVIRONMENT_ID/events" \
  -H "Authorization: Bearer $FINDIE_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{"eventId":"order_paid:123","type":"checkout_completed","properties":{"plan":"pro"}}'
```

---

## 5. Leitura dos agregados

Ambas exigem `Authorization: Bearer` com escopo `analytics:read` da mesma chave projeto/ambiente.

Eventos por tipo (Nível 2):

```
GET https://findie-maker.com/api/v1/projects/{projectId}/environments/{environmentId}/analytics
→ 200 { "data": { "totalEvents": 1774, "byType": { "signup": 104, … } }, "watermark": "<ISO>" }
```

Tráfego (Nível 1):

```
GET https://findie-maker.com/api/v1/projects/{projectId}/environments/{environmentId}/traffic?days=30
```

- `days`: inteiro 1–90, padrão 30 (dias UTC terminando hoje). Fora disso → 400.

```json
{
  "data": {
    "from": "2026-10-12", "to": "2026-11-10",
    "pageviews": 1200, "uniques": 340,
    "series": [{ "day": "2026-11-10", "pageviews": 40, "uniques": 12 }],
    "topPages": [{ "value": "/pricing", "count": 210 }, { "value": "$other", "count": 9 }],
    "topReferrers": [{ "value": "google.com", "count": 80 }, { "value": "$direct", "count": 300 }]
  },
  "watermark": "<ISO>"
}
```

- `$direct`: acessos sem referrer. `$other`: cauda longa além do top-100 diário.
- `uniques` no intervalo: identificados contam 1× no período; anônimos, 1× por dia.

---

### Funis (painel)

O maker define funis no painel (aba FUNIS): passos ordenados por tipo de evento (`page_view` = visita) e janela em horas. A sequência só liga eventos com o **mesmo identificador pseudônimo** do projeto:
- envie `visitorId` (servidor) ou chame `findie.identify(id)` (navegador) com o id interno do usuário para que visita → cadastro → compra sejam ligados, inclusive entre dias;
- visitantes anônimos têm identificador **diário** (só ligam no mesmo dia UTC);
- eventos sem identificador (ex.: servidor sem `visitorId`) contam nos totais, mas nunca entram na sequência.

---

## 5b. Links curtos rastreáveis

Escopos `links:read` / `links:write` (mesma chave secreta do projeto/ambiente).

```
POST  https://findie-maker.com/api/v1/projects/{projectId}/environments/{environmentId}/links
GET   https://findie-maker.com/api/v1/projects/{projectId}/environments/{environmentId}/links?limit=50&cursor=…
GET   https://findie-maker.com/api/v1/projects/{projectId}/environments/{environmentId}/links/{linkId}?days=30
PATCH https://findie-maker.com/api/v1/projects/{projectId}/environments/{environmentId}/links/{linkId}
```

- Corpo: `{ "destination": "https://…", "label"?, "expiresAt"?, "utmSource"?, "utmMedium"?, "utmCampaign"?, "utmTerm"?, "utmContent"?, "status"?: "active"|"paused" }`.
- Destino só http/https, sem usuário/senha na URL, ≤ 2048 chars. O `code` é imutável; trocar o destino cria nova versão (o histórico mantém a anterior).
- `Idempotency-Key` no POST: mesmo corpo → mesmo link (200); corpo diferente → 409.
- Lista com cursor opaco (`nextCursor`), limite 1–100 (padrão 50). Máximo de 100 links ativos por projeto.
- Link público: `https://findie-maker.com/r/{code}` → 302 para o destino com as UTMs anexadas (sem sobrescrever as do destino). Pausado, expirado ou projeto arquivado → página de indisponibilidade (410), sem redirect.
- Relatório (`GET …/links/{id}`): `requests` (todas), `bots` (previews/crawlers), `clicks` (estimativa de pessoas distintas/dia) e `gaps` (redirects feitos sem coleta), por versão de destino e por dia.

### Atribuição de conversões a links (aba CAMPANHAS)

- Clique humano em `/r/{code}` cujo destino é uma **origem do produto** (site do projeto ou origem permitida de um coletor do mesmo ambiente) recebe `?fnd_click=fc_…` — token opaco; o servidor guarda só o hash. Destino externo ou bot → sem token.
- O px.js lê o token, remove-o da barra de endereço e o envia como `clickToken` nos eventos da página. Para conversões enviadas pelo **servidor**, leia `findie.clickToken()` no navegador, repasse ao backend e envie `"clickToken": "fc_…"` no corpo do evento.
- Regra v1: último clique elegível em até 7 dias (configurável 1–30 no painel). Cada conversão (evento ≠ page_view, deduplicado por `eventId`) recebe no máximo uma origem: o token do próprio evento ou, sem ele, o clique mais recente ligado ao mesmo identificador.
- Token de outro projeto/ambiente, desconhecido, malformado ou com mais de 30 dias é **recusado**: a conversão fica "não atribuída" (sem cair para outro clique). Sem fingerprint — nada de IP/UA para ligar pessoas.

### 5c. Métricas de negócio (receita e indicadores)

Escopos `metrics:write` (registrar) / `metrics:read` (ler). O dono cria cada indicador no painel (aba NEGÓCIO) com **key**, unidade (`money` | `count` | `number`) e agregação (`latest` = snapshot como MRR, nunca somado · `sum` = transações · `count` = nº de medidas).

```
GET  https://findie-maker.com/api/v1/projects/{projectId}/environments/{environmentId}/metric-definitions
POST https://findie-maker.com/api/v1/projects/{projectId}/environments/{environmentId}/measurements
GET  https://findie-maker.com/api/v1/projects/{projectId}/environments/{environmentId}/measurements?metric=mrr&from=2026-09-01&to=2026-12-01
```

```json
{ "metric": "mrr", "measurementId": "mrr:2026-11", "value": 129900, "currency": "BRL",
  "periodStart": "2026-11-01T00:00:00Z", "periodEnd": "2026-12-01T00:00:00Z" }
```

- **Dinheiro em unidades menores** (centavos), inteiro, com `currency` ISO 4217 obrigatória. Moedas diferentes nunca são somadas: o resumo vem com um grupo por moeda.
- Período `[periodStart, periodEnd)` em UTC, até 366 dias por medida. Leitura: intervalo ≤ 90 dias (from inclusivo, to exclusivo), cursor opaco, limit 1–100.
- `measurementId` é a idempotência: mesmo corpo → 200 `duplicate`; corpo diferente → 409 `measurement_conflict`. Para **corrigir**, reenvie com `"correction": { "reason": "…" }` → nova versão (200 `corrected`); o histórico fica numa trilha privada do dono.
- **Procedência**: medidas pela API ficam como "enviado pelo servidor do maker" e `verified: false`. Não envie `source`: `"provider"` → 422 `reconciliation_required` (validação por provedor de faturamento ainda não existe). Indicador inexistente → 404 `metric_not_found`.

### 5d. Webhooks assinados (o Findie avisa o seu servidor)

Escopos `webhooks:write` (criar/editar/pausar/excluir) / `webhooks:read` (listar e ver entregas). Também no painel, aba WEBHOOKS. Destinos de um ambiente recebem só eventos desse ambiente.

```
GET    https://findie-maker.com/api/v1/projects/{projectId}/environments/{environmentId}/webhooks
POST   https://findie-maker.com/api/v1/projects/{projectId}/environments/{environmentId}/webhooks      { "url", "events": [...], "description"? }
PATCH  https://findie-maker.com/api/v1/projects/{projectId}/environments/{environmentId}/webhooks/{id} { "url"?, "events"?, "description"?, "status"?: "active" | "paused" }
DELETE https://findie-maker.com/api/v1/projects/{projectId}/environments/{environmentId}/webhooks/{id}
GET    https://findie-maker.com/api/v1/projects/{projectId}/environments/{environmentId}/webhooks/{id}/deliveries?limit=50
```

- **Eventos**: `feedback.created`, `form.submitted` (sem e-mail nem campos), `release.published` → ambiente **production**; `monitor.incident` → ambiente do monitor. Payload: `{ id: "evt_…", type, created_at, environment, project: { id }, data }`.
- **Destino**: só `https://` público (portas 443/8443). Rede privada/reservada é recusada no cadastro e de novo antes de cada envio; redirects nunca são seguidos.
- **O segredo** `whsec_…` volta UMA vez no POST (no painel o dono pode revelar e rotacionar; o anterior assina junto por 24 h).
- **Verificação**: cabeçalhos `Findie-Webhook-Id` (`whd_…`, estável em retries e reenvios — deduplique por ele), `Findie-Webhook-Timestamp` (segundos) e `Findie-Webhook-Signature: v1=<hex>` (duas, separadas por espaço, durante uma rotação). Assinatura = HMAC-SHA256(segredo, `id.timestamp.corpo`) sobre os BYTES EXATOS do corpo; compare em tempo constante e recuse timestamp com mais de 5 min.
- **Entrega**: responda 2xx em até 10 s (processe depois). Falha → retries em 1 min, 5 min, 30 min, 2 h, 12 h, 24 h; depois fica como falhada e só volta por reenvio manual. Destino pausado não recebe nada.

### 5e. Diagnóstico técnico (erros, Web Vitals, logs e traces)

Privado do time (aba DIAGNÓSTICO), nunca em página pública. Erros e vitals vêm ligados; **logs e traces são opt-in** (o dono liga cada classe, com amostragem e retenção de 1–30 dias).

**Navegador** — erros e Web Vitals (LCP, INP, CLS, FCP, TTFB) com o mesmo coletor público do px.js:

```html
<script src="https://findie-maker.com/fd.js" data-collector="col_prod_…" data-release="v1.2.3" defer></script>
```

`findieDiagnostics.captureError(err, { component: "Checkout" })` para erros tratados. `data-errors="false"` / `data-vitals="false"` desligam no cliente. Buffer de 30 itens, sem retentativa, respeita DNT/GPC e `data-consent="required"`.

**Servidor** — escopo `diagnostics:write`:

```
POST https://findie-maker.com/api/v1/projects/{projectId}/environments/{environmentId}/diagnostics
{ "release": "v1.2.3",
  "errors": [{ "type": "TypeError", "message": "…", "stack": "…", "traceId": "32 hex", "attributes": { "component": "checkout" } }],
  "logs":   [{ "level": "debug|info|warn|error", "message": "…", "traceId": "…", "at": "ISO" }],
  "spans":  [{ "traceId": "32 hex", "spanId": "16 hex", "parentSpanId": "16 hex|null", "name": "POST /checkout", "startAt": "ISO", "durationMs": 120, "status": "ok|error|unset" }],
  "vitals": [{ "metric": "LCP", "value": 2100, "path": "/pricing" }] }
```

- **Redaction antes de gravar**: atributos só da lista permitida (`component`, `route`, `feature`, `operation`, `http.method`, `http.route`, `http.status_code`, `db.system`, `db.operation`, `error.kind`, `browser`, `os`, `device`, `locale`, `runtime`, `region`, `queue`, `job`, `env`); texto sem e-mail, tokens, `chave=valor` sensível, cartões, CPF, IPs; URLs sem querystring. Nunca envie corpo de requisição, cookies ou cabeçalhos de autenticação.
- **Resposta 202 sempre** com `accepted`, `dropped` por classe (`quota`, `sampling`, `disabled`, `invalid`) e `redacted` — cota estourada **não** é erro. Cotas/dia (production): 5 000 erros, 20 000 vitals, 10 000 logs, 20 000 spans (test: 1/10). Lote ≤ 64 KB (navegador 32 KB); 413 acima disso.
- `trace_id`/`span_id` seguem o formato W3C/OpenTelemetry, mas **não há endpoint OTLP**: envie neste formato JSON.

---

## 6. Erros, limites e cotas

Formato de erro: `{ "error": { "code": "…", "message": "…", "requestId": "…" } }`

| Status | code | Quando | O que o cliente faz |
|---|---|---|---|
| 202 | — | aceito; `{ accepted, eventId, duplicate }` | nada (duplicate=true é sucesso) |
| 400 | `invalid_event` / `invalid_json` / `invalid_params` | envelope inválido | corrigir; não repetir |
| 401 | `unauthorized` | chave ausente, inválida, expirada ou revogada | não repetir; avisar o maker |
| 403 | `insufficient_scope` | chave sem o escopo | criar chave com o escopo |
| 404 | `not_found` | coletor revogado/inexistente ou chave de outro projeto/ambiente | conferir ids |
| 409 | `project_archived` | o projeto foi arquivado pelo maker; coleta suspensa | parar de enviar até o maker reativar |
| 410 | `gone` | dados do ambiente foram excluídos | parar de enviar |
| 413 | `too_large` | corpo > 16 KiB | reduzir properties |
| 429 | `rate_limited` / `quota_exceeded` | 60/min por IP no coletor, ou cota mensal | descartar; não fazer loop |
| 503 | `unavailable` | indisponível temporariamente | retry com backoff |

Cotas mensais (UTC) por ambiente, **separadas**:
- eventos customizados: PRODUCTION 10.000, TEST 1.000;
- pageviews (`page_view`, px.js): PRODUCTION 100.000, TEST 10.000.

Esgotar uma não afeta a outra. Duplicatas (mesmo `eventId`) não consomem cota e recebem 202 mesmo com a cota cheia.

---

## 7. Privacidade e exclusão

- Não envie dados pessoais em `properties` (e-mail, nome, telefone, documento, endereço, tokens).
- O px.js não usa cookies; não é motivo para adicionar banner de cookies.
- O Findie não guarda IP cru nem `visitorId` cru (nem nas chaves de limitação de taxa, que usam HMAC).
- Hashes de visitante por dia ficam no máximo 90 dias; os totais diários de únicos permanecem.
- O maker pode excluir os dados de um ambiente no painel; depois disso a ingestão daquele ambiente responde 410 para sempre.

---

## 8. Receitas por framework

**Next.js (App Router)** — `app/layout.tsx`:

```tsx
import Script from "next/script"
// dentro de <body>:
<Script src="https://findie-maker.com/px.js" data-collector={process.env.NEXT_PUBLIC_FINDIE_COLLECTOR} strategy="afterInteractive" />
```

**Next.js (Pages Router)** — `pages/_app.tsx` com o mesmo `<Script>`.

**Vite / React / Vue SPA** — `index.html`, no `<head>`:

```html
<script src="https://findie-maker.com/px.js" data-collector="%VITE_FINDIE_COLLECTOR%" defer></script>
```

**Nuxt 3** — `nuxt.config.ts`: `app.head.script: [{ src: "https://findie-maker.com/px.js", defer: true, "data-collector": "col_…" }]`.

**SvelteKit** — `src/app.html`, no `<head>`. **Astro** — layout base, `<script is:inline src=… data-collector=… defer>`.

**Rails / Laravel / Django / PHP / WordPress** — layout/tema base, antes de `</head>`.

Variáveis sugeridas: `*_FINDIE_COLLECTOR` (pública), `FINDIE_PROJECT_ID`, `FINDIE_ENVIRONMENT_ID`, `FINDIE_SECRET_KEY` (secreta, só servidor).

---

## 9. Checklist do agente

1. Identifique a stack e o layout raiz antes de editar.
2. Tráfego: uma única tag `px.js` no layout raiz; nada duplicado por página.
3. Eventos do navegador: um helper `track()`; chamadas nas ações de negócio; nada de `page_view`.
4. Eventos do servidor: módulo server-only; chave em `FINDIE_SECRET_KEY`; `eventId` determinístico para entidades; retry só em 503.
5. TEST em dev/staging, PRODUCTION em produção (ids diferentes).
6. Falhas de analytics nunca quebram a UI nem a resposta ao usuário.
7. Nenhum dado pessoal em `properties`; nenhum segredo no cliente ou no repositório.
8. Entregue: arquivos alterados, variáveis de ambiente a configurar e como testar (ex.: abrir o site e conferir a aba Tráfego/Eventos do painel).

---

## 10. Solução de problemas

- **Nada aparece no painel**: confira se o coletor é do ambiente certo (TEST × PRODUCTION) e se a resposta foi 202 com duplicate=false (202 já significa contado); confira também o período/ambiente selecionado no painel.
- **404 no coletor**: o coletor foi revogado — o maker cria outro em Integrações.
- **px.js não envia**: o navegador pode estar com DNT/GPC ligado (comportamento esperado); veja `window.findie.disabled`.
- **Bloqueado por CSP**: libere `https://findie-maker.com` em `script-src` e `connect-src`.
- **401 na API**: chave expirada/revogada ou de outro ambiente; crie uma nova no painel.
