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

# Telemetria de Licenciamento

> Payloads exatos enviados pela ativação e pelo heartbeat — o que sai da sua instância, o que fica do lado do servidor, e como inspecionar.

## O que esta página cobre

Esta página descreve a telemetria do sistema de licenciamento (ativação + heartbeat) — o que sustenta a contagem de instâncias da Evolution Foundation.

***

## Payload exato — ativação

Enviado uma vez, no `POST /v1/activate`:

```json theme={null}
{
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "version": "2.4.0"
}
```

Headers:

```
Content-Type: application/json
X-API-Key: <api_key de 64 chars hex>
X-Signature: <HMAC-SHA256 do body>
```

**Campos extraídos automaticamente pelo servidor (sem envio explícito):**

| Campo | Origem | Uso |
| - | - | - |
| `operator_country` | GeoIP do IP da request | Métricas agregadas por país |
| `operator_city` | GeoIP do IP da request | Métricas agregadas por região |
| `server_ip` | `X-Forwarded-For` ou `RemoteAddr` | Detecção de ativações duplicadas |
| `activated_at` | Timestamp do servidor | Log imutável |

***

## Payload exato — heartbeat

Enviado a cada 5 minutos, no `POST /v1/heartbeat`:

```json theme={null}
{
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "telemetry_bundle": {
    "messages_sent": 1500,
    "features": ["chatbot", "broadcast", "webhook"]
  }
}
```

### Campos do `telemetry_bundle`

O `telemetry_bundle` é um objeto JSON livre. O servidor extrai automaticamente:

| Campo | Tipo | Significado |
| - | - | - |
| `messages_sent` | number | Total de mensagens enviadas **desde o último heartbeat**. O servidor soma ao acumulado global. |
| `features` | string\[] | Lista de features ativas na instância. Ex.: `["chatbot", "broadcast", "webhook", "api-rest"]` |

Qualquer campo adicional incluído no bundle é **armazenado** na tabela `telemetry_bundles` para consulta futura, mas não há processamento padrão sobre ele.

### O que `features` pode conter

Valores comuns observados em produção:

* `chatbot` — integração com Chatwoot, Typebot, Dify, n8n, etc.
* `broadcast` — envio em massa
* `webhook` — webhooks configurados
* `api-rest` — uso da REST API
* `s3` / `minio` — armazenamento de mídia em object storage
* `rabbitmq` / `sqs` / `websocket` — eventos
* `cloudapi` — Cloud API oficial do WhatsApp
* `crm` — integração com Evo CRM

A lista exata depende da versão do produto.

***

## O que NÃO está no payload

Estes campos **nunca** são enviados, em nenhuma versão:

* Conteúdo de mensagens
* Identificadores de conversas
* Números de WhatsApp dos contatos
* Mídia (imagens, áudios, vídeos)
* Tokens de webhook ou API keys de terceiros
* Variáveis de ambiente da instância
* Configurações de chatbots
* Credenciais de banco de dados
* Logs da aplicação
* Stack traces ou erros internos

A presença desses dados em qualquer payload seria uma **violação grave** da política de telemetria e seria tratada como bug crítico.

***

## Como auditar localmente

Você pode interceptar o tráfego para confirmar o que está sendo enviado.

### Com `mitmproxy`

```bash theme={null}
# Em uma janela
mitmproxy -p 8888

# Em outra, redirecionar a instância
export HTTPS_PROXY=http://localhost:8888
export LICENSE_BASE_URL=https://license.evolutionfoundation.com.br
# reiniciar a instância
```

Cada `POST /v1/heartbeat` aparece no mitmproxy com body completo, pronto para inspeção.

### Com tcpdump + jq

```bash theme={null}
# Capturar tráfego para o licensing server
sudo tcpdump -i any -A -s 0 'host license.evolutionfoundation.com.br and port 443'
```

(TLS encripta o conteúdo — para inspecionar o JSON, use mitmproxy com CA local instalado.)

### Inspecionando localmente no código

A Evolution API expõe um endpoint de debug que retorna o último heartbeat enviado:

```http theme={null}
GET /telemetry/last-heartbeat
Authorization: Bearer <admin_token>
```

Resposta:

```json theme={null}
{
  "sent_at": "2026-05-12T10:34:00Z",
  "body": {
    "instance_id": "...",
    "telemetry_bundle": {
      "messages_sent": 42,
      "features": ["chatbot"]
    }
  },
  "signature": "abc123..."
}
```

<Note>
  O endpoint exato pode variar por versão. Veja o changelog do produto para detalhes.
</Note>

***

## Frequência e custo

| Operação | Frequência | Payload típico |
| - | - | - |
| `POST /v1/register/init` | 1x na vida da instância | \~150 bytes |
| `GET /v1/register/status` | polling de \~3–5s durante registro | \~50 bytes |
| `POST /v1/activate` | 1x por inicialização do serviço | \~150 bytes |
| `POST /v1/heartbeat` | a cada 5 min (≈ 288/dia) | \~250 bytes |
| `POST /v1/deactivate` | shutdown gracioso (opcional) | \~80 bytes |

Custo total mensal estimado em tráfego: **\< 3 MB por instância**.

***

## Retenção dos dados

| Tipo de dado | Retenção |
| - | - |
| `register/init` tokens | 30 minutos (expira automaticamente) |
| `instance_id` + `api_key` | Indefinida enquanto a instância estiver ativa |
| Heartbeats | Últimos 90 dias em tabela quente, agregados retidos indefinidamente |
| Logs de ativação | 12 meses |
| Métricas agregadas (sem identificação) | Indefinidamente |

***

## Conformidade

### LGPD (Brasil)

* E-mail e telefone coletados são tratados sob base legal de **legítimo interesse** para operação do projeto open source
* Operadores podem solicitar exclusão de dados via `suporte@evofoundation.com.br`
* Não há perfilhamento de pessoa física
* A `instance_id` é um UUID aleatório, não derivada de PII

### GDPR (Europa)

* A coleta é proporcional e necessária ao funcionamento do registro
* Direito de exclusão preservado
* DPO via `suporte@evofoundation.com.br`

***

## Mudanças futuras

Qualquer mudança em telemetria será:

1. Anunciada no [changelog do produto](https://github.com/evolution-foundation/evolution-api/releases)
2. Documentada nesta página
3. Disponibilizada em release candidate antes da release estável

Se for adicionada coleta de novo campo, ele aparecerá explicitamente na seção "Payload exato" acima.

***

## Reportar inconsistência

Se você observar **qualquer campo** sendo enviado fora do documentado nesta página, reporte como bug de segurança:

* E-mail: `suporte@evofoundation.com.br`
* GitHub Security Advisory: [evolution-api/security/advisories](https://github.com/evolution-foundation/evolution-api/security/advisories)

Issues de telemetria não documentada são tratadas como **prioridade alta**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.