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

# API de políticas

> Criar, versionar e publicar políticas de privacidade via API Key

Esta página descreve os endpoints **`/api/v1/policies`** para gerir políticas de privacidade **server-to-server** com **API Key** — o mesmo que o dashboard faz, agora automatizável a partir do seu CI ou scripts.

Para obter e usar uma API Key, consulte [API Key](./api-key).

## Autenticação

Inclua o header em toda chamada:

```http theme={null}
Authorization: Bearer sk-...
```

Cada requisição bem-sucedida consome **1** unidade da cota mensal do plano (`api_access`).

## Versionamento

Toda política começa na **versão 1**. Cada `PUT` publica uma **nova versão** — o número é incrementado no servidor e devolvido em `version`. Os banners registram qual versão estava ativa no momento do consentimento, então nunca sobrescrevemos histórico de versão silenciosamente.

## Endpoints

| Método   | Caminho                       | Descrição                                             |
| -------- | ----------------------------- | ----------------------------------------------------- |
| `POST`   | `/api/v1/policies`            | Cria uma política (inicia na versão 1).               |
| `GET`    | `/api/v1/policies`            | Lista as políticas do titular da chave.               |
| `GET`    | `/api/v1/policies/{policyId}` | Detalhe de uma política.                              |
| `PUT`    | `/api/v1/policies/{policyId}` | Atualiza nome/conteúdo — publica uma nova versão.     |
| `DELETE` | `/api/v1/policies/{policyId}` | Remove a política; sites vinculados perdem o vínculo. |

Especificação OpenAPI completa, com schemas e exemplos por endpoint, está disponível na aba **API Reference**.

## Criar política

Campos obrigatórios: `name` (2–120 caracteres) e `content` (20–200000 caracteres). Resposta `201` com o `PolicyResponse` completo.

```bash theme={null}
curl -X POST https://www.consentfly.com.br/api/v1/policies \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Política de Privacidade — Acme",
    "content": "Esta política descreve como a Acme trata dados pessoais..."
  }'
```

```json theme={null}
{
  "id": "6b8b4567-327a-4d10-92a5-9e8c4f5a7d12",
  "user_id": "9e8c4f5a-7d12-4d10-92a5-6b8b4567327a",
  "name": "Política de Privacidade — Acme",
  "content": "Esta política descreve como a Acme trata dados pessoais...",
  "version": 1,
  "created_at": "2026-01-15T12:34:56Z",
  "updated_at": "2026-01-15T12:34:56Z"
}
```

## Publicar uma nova versão

Um `PUT` com o conteúdo revisado devolve o mesmo `id` com `version` incrementado:

```bash theme={null}
curl -X PUT https://www.consentfly.com.br/api/v1/policies/6b8b4567-327a-4d10-92a5-9e8c4f5a7d12 \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Política de Privacidade — Acme", "content": "Versão revisada..." }'
```

## Erros

Respostas de erro seguem o envelope padrão (`code` + `message`). Casos comuns:

| Status | Quando                                                                   |
| ------ | ------------------------------------------------------------------------ |
| `400`  | Corpo inválido (nome/conteúdo fora dos limites).                         |
| `401`  | API Key ausente, inválida ou expirada.                                   |
| `402`  | Plano inativo (pagamento pendente).                                      |
| `403`  | Recurso não habilitado para o plano.                                     |
| `404`  | Política inexistente ou de outro titular (acesso cross-tenant vira 404). |
| `429`  | Cota mensal de requisições excedida.                                     |

## Vincular a um site

Uma política ganha vida quando vinculada a um site — o banner passa a referenciar sua versão ativa. O vínculo é feito no dashboard ou pela API de sites; consulte [Introdução](./intro).