Flujo de Activación - Documentação do Evolution Foundation

Para despliegues posteriores al primer registro del mismo email, puede saltarse el navegador y usar la activación automática por email — una sola llamada de API. El flujo de abajo sigue siendo necesario en el primer registro de un email.

Visión general del flujo

Diagrama del flujo de activación manual: la instancia llama a register/init, muestra la URL, el operador se autentica en el navegador, la instancia hace polling, recibe la api_key, activa con HMAC y continúa con los heartbeats.

La URL base se define en la variable LICENSE_BASE_URL del .env del producto (predeterminado: https://license.evolutionfoundation.com.br).

Paso 1 — Iniciar el registro

Cuando la instancia detecta que no hay api_key guardada localmente, llama:

POST /v1/register/init
Content-Type: application/json

{
  "tier": "community",
  "version": "2.4.0",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000"
}

Campos:

Campo	Tipo	Descripción
`tier`	string	`community` o `beta`
`version`	string	Versión del producto Evolution (ej.: `2.4.0`)
`instance_id`	UUID v4	Identificador local de la instancia — generado una vez y persistido

Respuesta (200):

{
  "register_url": "https://license.evolutionfoundation.com.br/register?token=abc123def456...",
  "token": "abc123def456..."
}

El token expira en 30 minutos. Hay rate limit de 10 inits por hora por IP. Si el operador no completa la activación a tiempo, basta repetir el paso 1.

Errores posibles:

HTTP	Code	Significado
400	`INVALID_TIER`	tier no es `community` ni `beta`
400	`INVALID_BODY`	JSON mal formado
429	`RATE_LIMIT`	excedió 10 inits/hora

Paso 2 — Mostrar la URL al operador

La instancia muestra register_url al operador. Patrones aceptados:

Web UI / Manager — botón “Activar Licencia” abre el link en el navegador
Terminal / CLI — imprime la URL y queda esperando
QR Code — en despliegues headless, genera un QR para escanear

Ejemplo de salida en CLI:

─────────────────────────────────────────────────────────────────
  Activación de licencia Evolution API
─────────────────────────────────────────────────────────────────

  Para activar, abra en su navegador:

  https://license.evolutionfoundation.com.br/register?token=abc123def...

  Esperando confirmación... (expira en 30 minutos)
─────────────────────────────────────────────────────────────────

Paso 3 — Qué ocurre en el navegador

El servidor de licencia renderiza la página de registro con la identidad visual de Evolution. El operador elige entre:

Magic Link — informa nombre + email, recibe link de confirmación por email
Google OAuth — login con cuenta Google
GitHub OAuth — login con cuenta GitHub

Tras autenticar, el servidor crea (o recupera) el customer y genera un authorization_code interno. Este flujo es transparente para la instancia — solo necesita hacer polling.

Paso 4 — Polling del estado

Mientras el operador resuelve el login, la instancia hace polling:

GET /v1/register/status?token=abc123def456...

Mientras está pendiente:

{ "status": "pending" }

Al completarse:

{
  "status": "completed",
  "api_key": "64chars_hex_key...",
  "customer_id": 8,
  "tier": "community"
}

Tras expirar:

{ "status": "expired" }

Recomendaciones de implementación:

Intervalo de polling entre 3 y 5 segundos (no más rápido)
Timeout total de 30 minutos
Al recibir completed, persistir api_key en ubicación segura (config cifrada, secret manager, etc.)

Paso 5 — Activar la instancia

Con la api_key en mano, la instancia llama al endpoint de activación:

POST /v1/activate
Content-Type: application/json
X-API-Key: 64chars_hex_key...
X-Signature: <HMAC-SHA256 del body usando la api_key>

{
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "version": "2.4.0"
}

Respuesta:

{
  "status": "active",
  "tier": "community",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000"
}

La geolocalización (operator_country, operator_city) es detectada automáticamente desde la IP de la request. La instancia no envía esa información.

Paso 6 — Heartbeat periódico

Tras la activación, la instancia envía heartbeats cada 5 minutos:

POST /v1/heartbeat
Content-Type: application/json
X-API-Key: 64chars_hex_key...
X-Signature: <HMAC-SHA256 del body>

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

El campo telemetry_bundle es JSON libre. Los campos extraídos automáticamente por el servidor están detallados en Telemetría.

Paso 7 — Desactivación (opcional)

En apagado controlado (uninstall, container stop intencional), se recomienda:

POST /v1/deactivate
Content-Type: application/json
X-API-Key: 64chars_hex_key...
X-Signature: <HMAC-SHA256 del body>

{
  "instance_id": "550e8400-e29b-41d4-a716-446655440000"
}

Esto libera el conteo de la instancia en el licenciamiento. No es obligatorio — el servidor expira instancias inactivas automáticamente tras 7 días sin heartbeat.

Autenticación HMAC

Todas las llamadas a /v1/activate, /v1/heartbeat y /v1/deactivate requieren el header X-Signature con HMAC-SHA256 del body. Algoritmo:

Serializar el body como JSON
Calcular HMAC-SHA256(body, api_key)
Convertir a hexadecimal
Enviar en el header X-Signature

El body usado en el HMAC debe ser idéntico byte a byte al enviado. No reformatee el JSON entre la firma y el envío.

Ejemplo Python

import hmac, hashlib, json, requests

api_key = "64chars_hex..."
payload = {
    "instance_id": "550e8400-e29b-41d4-a716-446655440000",
    "version": "2.4.0",
}
body = json.dumps(payload, separators=(",", ":"))
sig = hmac.new(api_key.encode(), body.encode(), hashlib.sha256).hexdigest()

requests.post(
    "https://license.evolutionfoundation.com.br/v1/activate",
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-API-Key": api_key,
        "X-Signature": sig,
    },
)

Ejemplo Node.js

const crypto = require('crypto');

const apiKey = '64chars_hex...';
const payload = {
  instance_id: '550e8400-e29b-41d4-a716-446655440000',
  version: '2.4.0',
};
const body = JSON.stringify(payload);
const sig = crypto.createHmac('sha256', apiKey).update(body).digest('hex');

await fetch('https://license.evolutionfoundation.com.br/v1/activate', {
  method: 'POST',
  body,
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey,
    'X-Signature': sig,
  },
});

Ejemplo Go

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

func sign(body []byte, apiKey string) string {
    mac := hmac.New(sha256.New, []byte(apiKey))
    mac.Write(body)
    return hex.EncodeToString(mac.Sum(nil))
}

Códigos de error

HTTP	Code	Causa	Acción recomendada
401	`HMAC_INVALID`	Firma incorrecta	Verificar serialización del body
401	`INVALID_API_KEY`	Key mal formada	Confirmar uso de la hex de 64 chars
403	`KEY_SUSPENDED`	Key suspendida por abuso	Contactar soporte
403	`INSTANCE_LIMIT`	Límite de instancias alcanzado	Solicitar aumento
404	`INSTANCE_NOT_FOUND`	Heartbeat sin activación previa	Ejecutar `/v1/activate` primero
410	`TOKEN_EXPIRED`	Token de 30min expirado	Repetir `/v1/register/init`
429	`RATE_LIMIT`	Rate limit excedido	Backoff exponencial

Checklist de integración

Para quien implementa la activación en un fork o producto derivado:

Modo offline y degradación

Si el servidor de licencia es inaccesible:

La instancia sigue funcionando normalmente
Los heartbeats fallan silenciosamente (sin romper la aplicación)
Tras reconectarse, el siguiente heartbeat retoma el ciclo

La activación inicial (pasos 1–5) es la única etapa que exige conectividad. Después de eso, la instancia tolera períodos offline. Vea FAQ — modo offline para más detalles.

​Visión general del flujo

​Paso 1 — Iniciar el registro

​Paso 2 — Mostrar la URL al operador

​Paso 3 — Qué ocurre en el navegador

​Paso 4 — Polling del estado

​Paso 5 — Activar la instancia

​Paso 6 — Heartbeat periódico

​Paso 7 — Desactivación (opcional)

​Autenticación HMAC

​Ejemplo Python

​Ejemplo Node.js

​Ejemplo Go

​Códigos de error

​Checklist de integración

​Modo offline y degradación

Visión general del flujo

Paso 1 — Iniciar el registro

Paso 2 — Mostrar la URL al operador

Paso 3 — Qué ocurre en el navegador

Paso 4 — Polling del estado

Paso 5 — Activar la instancia

Paso 6 — Heartbeat periódico

Paso 7 — Desactivación (opcional)

Autenticación HMAC

Ejemplo Python

Ejemplo Node.js

Ejemplo Go

Códigos de error

Checklist de integración

Modo offline y degradación