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

# Comece aqui

> Tudo o que você precisa para integrar o ConsentFly

Bem-vindo à documentação oficial do **ConsentFly** — infraestrutura de consentimento e privacidade para times que precisam atender LGPD/GDPR sem fricção.

## Em 5 minutos

1. **Crie sua conta** em [consentfly.com.br](https://www.consentfly.com.br) e cadastre seu site.
2. **Gere uma API Key** em `/dashboard/api-keys`.
3. **Faça sua primeira chamada** — registre um consentimento via `POST /api/v1/consents` (exemplo abaixo).

## O que o ConsentFly entrega

* Banner de cookies pronto para colar em qualquer site, em **uma linha** de script.
* Registro auditável de cada consentimento (`consent_id`, `subject_id`, IP, user-agent, `policy_version`, preferências).
* API REST para consultar e gerenciar consentimentos via dashboard ou via API Key (server-to-server).
* **Batch ingestion** (até 1000 linhas) e **exports CSV** com fallback automático para jobs assíncronos em volumes grandes.
* **Recibos DSAR** versionados e direito ao esquecimento por `subject_id`.
* **Webhooks assinados** (HMAC-SHA256) para receber eventos de consentimento em tempo real.
* Geração de política de privacidade e gestão de planos com cobrança recorrente (AbacatePay).

## 1. Crie sua conta e um site

1. Crie sua conta em [www.consentfly.com.br](https://www.consentfly.com.br).
2. No painel, abra **Sites → Novo site** e cadastre o domínio.
3. Copie o `site_id` (UUID) e o snippet de integração.

## 2. Cole o script no seu site

Adicione o snippet abaixo antes de `</body>`. Substitua `SITE_ID` pelo `site_id` retornado no passo 1.

```html theme={null}
<script async
  src="https://www.consentfly.com.br/api/v1/script.js?siteId=SITE_ID">
</script>
```

O script:

* baixa as configurações do site via `GET /api/v1/public/site/{siteId}`,
* exibe o banner com o texto cadastrado e a versão atual da política,
* envia o consentimento para `POST /api/v1/public/consent` quando o usuário clica em aceitar/recusar.

Cada site tem um **token de script** próprio (`script_token`) que o snippet anexa automaticamente ao header `X-Site-Token`. Esse token impede que terceiros enviem consentimentos falsos para o seu site. Você pode rotacioná-lo no painel a qualquer momento.

## 3. Verifique no dashboard

Em **Dashboard → Sites → `{seu site}` → Ver consentimentos** você consegue:

* filtrar por aceito/recusado, `subject_id`, intervalo de datas,
* paginar via cursor,
* exportar todos os registros em CSV.

Os mesmos dados estão disponíveis programaticamente em `GET /api/v1/consents?site_id=...` (veja [API Key](./api-key) e [API de consentimentos](./consents-api)).

## 4. Use a API server-to-server

Guias completos:

* [API de consentimentos](./consents-api) — CRUD, batch, recibo, DSAR
* [Exportar consentimentos](./exports-api) — CSV streaming + jobs assíncronos
* [Webhooks](./webhooks) — eventos assinados em tempo real (verificação no seu backend)

Para registrar um consentimento de dentro do seu backend (por exemplo, em um fluxo de cadastro):

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://www.consentfly.com.br/api/v1/consents \
    -H "Authorization: Bearer $CONSENTFLY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "site_id": "6b8b4567-327a-4d10-92a5-9e8c4f5a7d12",
      "subject_id": "user_sha256_a1b2c3d4e5f6",
      "accepted": true,
      "preferences": { "analytics": true, "marketing": false, "functional": true },
      "policy_version": 3
    }'
  ```

  ```javascript Node theme={null}
  const res = await fetch("https://www.consentfly.com.br/api/v1/consents", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CONSENTFLY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      site_id: "6b8b4567-327a-4d10-92a5-9e8c4f5a7d12",
      subject_id: "user_sha256_a1b2c3d4e5f6",
      accepted: true,
      preferences: { analytics: true, marketing: false, functional: true },
      policy_version: 3,
    }),
  });
  const consent = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.post(
      "https://www.consentfly.com.br/api/v1/consents",
      headers={
          "Authorization": f"Bearer {os.environ['CONSENTFLY_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "site_id": "6b8b4567-327a-4d10-92a5-9e8c4f5a7d12",
          "subject_id": "user_sha256_a1b2c3d4e5f6",
          "accepted": True,
          "preferences": {"analytics": True, "marketing": False, "functional": True},
          "policy_version": 3,
      },
  )
  consent = res.json()
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "net/http"
      "os"
  )

  func main() {
      body, _ := json.Marshal(map[string]any{
          "site_id":        "6b8b4567-327a-4d10-92a5-9e8c4f5a7d12",
          "subject_id":     "user_sha256_a1b2c3d4e5f6",
          "accepted":       true,
          "preferences":    map[string]bool{"analytics": true, "marketing": false, "functional": true},
          "policy_version": 3,
      })
      req, _ := http.NewRequest("POST", "https://www.consentfly.com.br/api/v1/consents", bytes.NewReader(body))
      req.Header.Set("Authorization", "Bearer "+os.Getenv("CONSENTFLY_API_KEY"))
      req.Header.Set("Content-Type", "application/json")
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

A resposta é o `ConsentDTO` completo, incluindo `id`, `created_at`, `updated_at` e `policy_version`. Cada alteração em um consentimento é registrada na trilha de auditoria, acessível em `GET /api/v1/consents/{id}/history`.

## 5. Erros mais comuns

* `unauthorized` — API Key inválida, revogada ou conta inativa.
* `email_not_verified` — usuário precisa confirmar o e-mail antes de gerar API Keys.
* `plan_required` — assinatura cancelada/expirada; renove na página `/dashboard/billing`.
* `plan_limit_exceeded` — você atingiu o limite de sites/recurso do plano.
* `quota_exceeded` — bateu na cota mensal de requisições.
* `too_many_requests` — endpoints sensíveis têm limite por IP.

## 6. Suporte

Dúvidas técnicas, integração ou compliance: [suporte@consentfly.com.br](mailto:suporte@consentfly.com.br).