Telemetría del Licenciamiento - Documentação do Evolution Foundation

Qué cubre esta página

Esta página describe la telemetría del sistema de licenciamiento (activación + heartbeat) — lo que alimenta el conteo de instancias de la Evolution Foundation.

Payload exacto — activación

Enviado una vez, en POST /v1/activate:

{
  "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 del body>

Campos extraídos automáticamente por el servidor (sin envío explícito):

Campo	Origen	Uso
`operator_country`	GeoIP de la IP de la request	Métricas agregadas por país
`operator_city`	GeoIP de la IP de la request	Métricas agregadas por región
`server_ip`	`X-Forwarded-For` o `RemoteAddr`	Detección de activaciones duplicadas
`activated_at`	Timestamp del servidor	Log inmutable

Payload exacto — heartbeat

Enviado cada 5 minutos, en POST /v1/heartbeat:

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

Campos del `telemetry_bundle`

El telemetry_bundle es un objeto JSON libre. El servidor extrae automáticamente:

Campo	Tipo	Significado
`messages_sent`	number	Total de mensajes enviados desde el último heartbeat. El servidor suma al acumulado global.
`features`	string[]	Lista de features activas en la instancia. Ej.: `["chatbot", "broadcast", "webhook", "api-rest"]`

Cualquier campo adicional incluido en el bundle es almacenado en la tabla telemetry_bundles para consulta futura, pero no hay procesamiento por defecto sobre él.

Qué puede contener `features`

Valores comunes observados en producción:

chatbot — integración con Chatwoot, Typebot, Dify, n8n, etc.
broadcast — envío masivo
webhook — webhooks configurados
api-rest — uso de la REST API
s3 / minio — almacenamiento de multimedia en object storage
rabbitmq / sqs / websocket — eventos
cloudapi — Cloud API oficial de WhatsApp
crm — integración con Evo CRM

La lista exacta depende de la versión del producto.

Qué NO está en el payload

Estos campos nunca se envían, en ninguna versión:

Contenido de mensajes
Identificadores de conversaciones
Números de WhatsApp de los contactos
Multimedia (imágenes, audios, videos)
Tokens de webhook o API keys de terceros
Variables de entorno de la instancia
Configuraciones de chatbots
Credenciales de base de datos
Logs de la aplicación
Stack traces o errores internos

La presencia de esos datos en cualquier payload sería una violación grave de la política de telemetría y se trataría como bug crítico.

Cómo auditar localmente

Puede interceptar el tráfico para confirmar qué se envía.

Con `mitmproxy`

# En una ventana
mitmproxy -p 8888

# En otra, redirigir la instancia
export HTTPS_PROXY=http://localhost:8888
export LICENSE_BASE_URL=https://license.evolutionfoundation.com.br
# reiniciar la instancia

Cada POST /v1/heartbeat aparece en mitmproxy con el body completo, listo para inspección.

Con tcpdump + jq

# Capturar tráfico al licensing server
sudo tcpdump -i any -A -s 0 'host license.evolutionfoundation.com.br and port 443'

(TLS cifra el contenido — para inspeccionar JSON, use mitmproxy con CA local instalado.)

Inspeccionando localmente en código

Evolution API expone un endpoint de debug que devuelve el último heartbeat enviado:

GET /telemetry/last-heartbeat
Authorization: Bearer <admin_token>

Respuesta:

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

El endpoint exacto puede variar por versión. Vea el changelog del producto para detalles.

Frecuencia y costo

Operación	Frecuencia	Payload típico
`POST /v1/register/init`	1x en la vida de la instancia	~150 bytes
`GET /v1/register/status`	polling de ~3–5s durante el registro	~50 bytes
`POST /v1/activate`	1x por inicio del servicio	~150 bytes
`POST /v1/heartbeat`	cada 5 min (≈ 288/día)	~250 bytes
`POST /v1/deactivate`	apagado controlado (opcional)	~80 bytes

Costo total mensual estimado en tráfico: < 3 MB por instancia.

Retención de los datos

Tipo de dato	Retención
Tokens `register/init`	30 minutos (expira automáticamente)
`instance_id` + `api_key`	Indefinida mientras la instancia esté activa
Heartbeats	Últimos 90 días en tabla caliente, agregados retenidos indefinidamente
Logs de activación	12 meses
Métricas agregadas (sin identificación)	Indefinida

Conformidad

LGPD (Brasil)

Email y teléfono recopilados se tratan bajo base legal de interés legítimo para la operación del proyecto open source
Los operadores pueden solicitar exclusión de datos vía [email protected]
No hay perfilamiento de persona física
El instance_id es un UUID aleatorio, no derivado de PII

La recopilación es proporcional y necesaria al funcionamiento del registro
Derecho de supresión preservado
DPO vía [email protected]

Cambios futuros

Cualquier cambio en telemetría será:

Anunciado en el changelog del producto
Documentado en esta página
Disponible en release candidate antes de la versión estable

Si se añade recopilación de un nuevo campo, aparecerá explícitamente en la sección “Payload exacto” arriba.

Reportar inconsistencias

Si observa cualquier campo siendo enviado fuera de lo documentado en esta página, repórtelo como bug de seguridad:

Email: [email protected]
GitHub Security Advisory: evolution-api/security/advisories

Issues de telemetría no documentada se tratan como prioridad alta.

​Qué cubre esta página

​Payload exacto — activación

​Payload exacto — heartbeat

​Campos del telemetry_bundle

​Qué puede contener features

​Qué NO está en el payload

​Cómo auditar localmente

​Con mitmproxy

​Con tcpdump + jq

​Inspeccionando localmente en código

​Frecuencia y costo

​Retención de los datos

​Conformidad

​LGPD (Brasil)

​GDPR (Europa)

​Cambios futuros

​Reportar inconsistencias

Qué cubre esta página

Payload exacto — activación

Payload exacto — heartbeat

Campos del `telemetry_bundle`

Qué puede contener `features`

Qué NO está en el payload

Cómo auditar localmente

Con `mitmproxy`

Con tcpdump + jq

Inspeccionando localmente en código

Frecuencia y costo

Retención de los datos

Conformidad

LGPD (Brasil)

GDPR (Europa)

Cambios futuros

Reportar inconsistencias