Activación Automática por Email - Documentação do Evolution Foundation

Cuándo usar

El flujo estándar de activación exige que el operador abra el navegador, haga login (Magic Link u OAuth) y espere a que el registro se complete. Para el primer registro de un email, eso es necesario. Para toda instalación posterior del mismo operador (mismo email), puede saltarse el navegador por completo y activar la licencia en una única llamada HTTP. Ideal para:

Despliegue automatizado (CI/CD, Terraform, Ansible)
Múltiples instancias del mismo producto en distintos servidores
Contenedores efímeros que se levantan y mueren con frecuencia
Aprovisionamiento programático (multi-tenant, multi-región)

La primera activación todavía requiere el flujo manual (navegador + Magic Link/OAuth). Solo después el email queda “conocido” por el servidor de licenciamiento, y la activación automática pasa a funcionar.

Endpoint

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

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

Campos:

Campo	Tipo	Obligatorio	Descripción
`email`	string	sí	Email de un customer ya registrado previamente
`tier`	string	sí	Slug del producto (`community`, `beta`, etc.)
`version`	string	sí	Versión del producto que se está activando
`instance_id`	UUID v4	sí	UUID generado localmente, mismo patrón que `/v1/register/init`
`country`	string	no	Override de país (predeterminado: GeoIP del servidor)
`city`	string	no	Override de ciudad (predeterminado: GeoIP del servidor)

Respuesta de éxito (200):

{
  "status": "active",
  "api_key": "64chars_hex_key...",
  "customer_id": 8,
  "tier": "community",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000"
}

La api_key devuelta está lista para usar inmediatamente — no es necesario llamar a /v1/activate después. La instancia ya queda como active en el servidor. Si la llamada se repite con el mismo (email, instance_id), la respuesta incluye "reused": true y devuelve la misma api_key de la llamada anterior. Esto hace la llamada idempotente — segura para retry en scripts de arranque.

Modelo de confianza

El servidor de licenciamiento acepta la llamada usando solo el email como prueba de identidad. Sin segundo factor, sin captcha, sin rate limit. Por qué:

El email ya fue verificado una vez (en el registro manual inicial, vía Magic Link u OAuth)
Emitir una licencia para un customer no es una acción destructiva — todas las instancias quedan visibles en el portal del customer
El customer puede revocar api_keys en cualquier momento si detecta uso no autorizado
El customer puede desactivar la activación automática (auto_activation_enabled = false) en el portal si sospecha que el email se filtró

Implicación: quien sepa el email de un customer puede emitir licencias en ese nombre. Si eso es un problema para su escenario (multi-tenant comercial, email compartido, sospecha de filtración), desactive la activación automática en el portal y fuerce a todos los despliegues a usar el flujo manual.

Códigos de error

HTTP	Code	Cuándo	Cómo tratar
400	`INVALID_BODY`	JSON malformado	Verificar cuerpo de la request
400	`MISSING_FIELD`	Campo `email` ausente	Incluir el campo
400	`INVALID_EMAIL`	Email malformado	Validar antes de enviar
400	`INVALID_TIER`	`tier` no corresponde a ningún producto	Verificar el slug
400	`INVALID_INSTANCE_ID`	`instance_id` no es UUID	Generar UUID v4
404	`CUSTOMER_NOT_FOUND`	Email no tiene registro previo	Caiga al flujo manual `/v1/register/init`
403	`CUSTOMER_BLOCKED`	Customer bloqueado o key suspendida	Contactar soporte
403	`AUTO_ACTIVATION_DISABLED`	Customer desactivó auto-activación	Usar flujo manual
403	`INSTANCE_LIMIT`	Límite de instancias del customer alcanzado	Solicitar aumento de cap
409	`INSTANCE_EXISTS`	`instance_id` ya existe bajo otro customer	Generar nuevo UUID

La respuesta CUSTOMER_NOT_FOUND es la señal canónica para que el cliente caiga al flujo manual. Siempre implemente ese fallback — primer despliegue de un email nuevo necesita pasar por el manual.

Flujo recomendado en el cliente

import os, uuid, requests

LICENSE_URL = "https://license.evolutionfoundation.com.br"

def ensure_api_key():
    if local_api_key_exists():
        return load_api_key()

    instance_id = read_or_create_instance_uuid()
    email = os.environ.get("EVOLUTION_OPERATOR_EMAIL")

    # 1. Pruebe activación automática si tenemos el email
    if email:
        resp = requests.post(f"{LICENSE_URL}/v1/register/auto", json={
            "email": email,
            "tier": "community",
            "version": PRODUCT_VERSION,
            "instance_id": instance_id,
        })
        if resp.status_code == 200:
            data = resp.json()
            save_api_key(data["api_key"])
            return data["api_key"]

        if resp.json().get("code") == "CUSTOMER_NOT_FOUND":
            pass  # cae al flujo manual abajo
        elif resp.status_code in (403, 409):
            raise RuntimeError(f"Auto-activation rejected: {resp.json()}")

    # 2. Fallback: flujo manual con navegador
    init_resp = requests.post(f"{LICENSE_URL}/v1/register/init", json={
        "tier": "community",
        "version": PRODUCT_VERSION,
        "instance_id": instance_id,
    }).json()
    print(f"Abra en su navegador: {init_resp['register_url']}")
    api_key = poll_until_completed(init_resp["token"])
    save_api_key(api_key)
    return api_key

Variable de entorno estándar

Los productos Evolution leen el email del operador de la variable EVOLUTION_OPERATOR_EMAIL:

# .env
EVOLUTION_OPERATOR_EMAIL=[email protected]

Si la variable no está definida, el producto cae directamente al flujo manual (sin intentar auto-activación).

Idempotencia detallada

La llamada es idempotente en (email, instance_id):

Escenario	Comportamiento
Primera llamada	Crea APIKey nueva + Instance, devuelve `api_key`
Mismo `(email, instance_id)` de nuevo	Devuelve la misma `api_key`, `"reused": true`
Mismo `instance_id`, email diferente	Error `409 INSTANCE_EXISTS`
Mismo `email`, `instance_id` diferente	Crea nueva APIKey + Instance (despliegue de instancia nueva)

Esto es lo que hace seguro llamar la ruta en el startup del contenedor — si el contenedor ya se registró antes, recibe la misma key; si es nuevo, recibe key nueva.

Los contenedores que siempre generan UUID nuevo en cada boot acumulan APIKeys (una por boot) bajo el mismo customer. Si quiere comportamiento idempotente real, persista el instance_id en un volumen montado (/data/instance-id) entre reinicios.

Cómo desactivar para mi customer

En el portal del customer (https://license.evolutionfoundation.com.br/portal) hay un toggle “Activación Automática por Email”. Cuando desactivado:

Todas las llamadas a /v1/register/auto con su email devuelven 403 AUTO_ACTIVATION_DISABLED
Nuevos despliegues obligatoriamente pasan por el flujo manual (navegador + Magic Link/OAuth)
Sus api_keys existentes siguen funcionando normalmente

Recomendado para customers que:

Operan en ambiente regulado y quieren auditoría en cada activación
Tienen el email conocido públicamente y quieren reducir superficie de ataque
Sospechan de uso indebido del email

Auditoría

Cada llamada a /v1/register/auto genera una fila en activation_logs con alert_type = 'auto_activation'. El portal del customer muestra:

Fecha/hora de cada auto-activación
IP del servidor que solicitó
Localización aproximada (país/ciudad vía GeoIP)
Resultado (created o reused)

Si ve auto-activaciones que no reconoce, suspenda la key correspondiente en el portal inmediatamente — eso revoca el acceso de esa instancia sin afectar las demás.

Próximos pasos

Flujo manual

Flujo completo de /v1/register/init — necesario en el primer registro

Telemetría

Qué se envía en cada llamada de licencia

FAQ

Preguntas frecuentes

Resumen

Resumen del sistema de licenciamiento

​Cuándo usar

​Endpoint

​Modelo de confianza

​Códigos de error

​Flujo recomendado en el cliente

​Variable de entorno estándar

​Idempotencia detallada

​Cómo desactivar para mi customer

​Auditoría

​Próximos pasos

Flujo manual

Telemetría

FAQ

Resumen

Cuándo usar

Endpoint

Modelo de confianza

Códigos de error

Flujo recomendado en el cliente

Variable de entorno estándar

Idempotencia detallada

Cómo desactivar para mi customer

Auditoría

Próximos pasos