Ativação Automática por E-mail - Documentação do Evolution Foundation

Quando usar

O fluxo padrão de ativação exige que o operador abra o navegador, faça login (Magic Link ou OAuth) e aguarde o registro completar. Para o primeiro registro de um e-mail, isso é necessário. Para toda instalação subsequente do mesmo operador (mesmo e-mail), você pode pular o navegador inteiro e ativar a licença em uma única chamada HTTP. Ideal para:

Deploy automatizado (CI/CD, Terraform, Ansible)
Múltiplas instâncias do mesmo produto em servidores diferentes
Containers efêmeros que sobem e morrem com frequência
Provisionamento programático (multi-tenant, multi-região)

A primeira ativação ainda precisa ser feita pelo fluxo manual (navegador + Magic Link/OAuth). Só depois disso o e-mail fica “conhecido” pelo servidor de licenciamento e a ativação automática passa 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	Obrigatório	Descrição
`email`	string	sim	E-mail de um customer já registrado anteriormente
`tier`	string	sim	Slug do produto (`community`, `beta`, etc.)
`version`	string	sim	Versão do produto sendo ativado
`instance_id`	UUID v4	sim	UUID gerado localmente, mesmo padrão do `/v1/register/init`
`country`	string	não	Override de país (padrão: GeoIP do servidor)
`city`	string	não	Override de cidade (padrão: GeoIP do servidor)

Resposta de sucesso (200):

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

A api_key retornada está pronta para uso imediato — não é necessário chamar /v1/activate em seguida. A instância já entra como active no servidor. Se a chamada for repetida com o mesmo (email, instance_id), a resposta inclui "reused": true e devolve a mesma api_key da chamada anterior. Isso torna a chamada idempotente — seguro para retry em scripts de boot.

Modelo de confiança

O servidor de licenciamento aceita a chamada usando apenas o e-mail como prova de identidade. Não há segundo fator, não há captcha, não há rate limit. Por quê:

O e-mail já foi verificado uma vez (no registro manual inicial, via Magic Link ou OAuth)
Emitir uma licença para um customer não é uma ação destrutiva — todas as instâncias ficam visíveis no portal do customer
O customer pode revogar api_keys a qualquer momento se detectar uso não autorizado
O customer pode desabilitar a ativação automática (auto_activation_enabled = false) no portal caso suspeite que o e-mail vazou

Implicação: quem souber o e-mail de um customer pode emitir licenças nesse nome. Se isso for um problema para seu cenário (multi-tenant comercial, e-mail compartilhado, suspeita de vazamento), desabilite a ativação automática no portal e force todos os deploys a usarem o fluxo manual.

Códigos de erro

HTTP	Code	Quando	Como tratar
400	`INVALID_BODY`	JSON malformado	Verificar corpo da request
400	`MISSING_FIELD`	Campo `email` ausente	Incluir o campo
400	`INVALID_EMAIL`	E-mail malformado	Validar antes de enviar
400	`INVALID_TIER`	`tier` não corresponde a nenhum produto	Verificar o slug
400	`INVALID_INSTANCE_ID`	`instance_id` não é UUID	Gerar UUID v4
404	`CUSTOMER_NOT_FOUND`	E-mail não tem registro prévio	Caia para o fluxo manual `/v1/register/init`
403	`CUSTOMER_BLOCKED`	Customer bloqueado ou key suspensa	Contatar suporte
403	`AUTO_ACTIVATION_DISABLED`	Customer desabilitou auto-ativação	Usar fluxo manual
403	`INSTANCE_LIMIT`	Limite de instâncias do customer atingido	Solicitar aumento de cap
409	`INSTANCE_EXISTS`	`instance_id` já existe sob outro customer	Gerar novo UUID

A resposta CUSTOMER_NOT_FOUND é o sinal canônico para o cliente cair para o fluxo manual. Sempre implemente esse fallback — primeiro deploy de um e-mail novo precisa passar pelo manual.

Fluxo recomendado no client

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. Tente ativação automática se temos o e-mail
    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  # cai para o fluxo manual abaixo
        elif resp.status_code in (403, 409):
            raise RuntimeError(f"Auto-activation rejected: {resp.json()}")

    # 2. Fallback: fluxo manual com 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 no navegador: {init_resp['register_url']}")
    api_key = poll_until_completed(init_resp["token"])
    save_api_key(api_key)
    return api_key

Variável de ambiente padrão

Os produtos Evolution leem o e-mail do operador da variável EVOLUTION_OPERATOR_EMAIL:

# .env
EVOLUTION_OPERATOR_EMAIL=[email protected]

Se a variável não estiver definida, o produto cai diretamente no fluxo manual (sem tentar auto-ativação).

Idempotência detalhada

A chamada é idempotente em (email, instance_id):

Cenário	Comportamento
Primeira chamada	Cria APIKey nova + Instance, retorna `api_key`
Mesma `(email, instance_id)` de novo	Retorna a mesma `api_key`, `"reused": true`
Mesmo `instance_id`, e-mail diferente	Erro `409 INSTANCE_EXISTS`
Mesma `(email)`, `instance_id` diferente	Cria nova APIKey + Instance (deploy de instância nova)

Isso é o que torna seguro chamar a rota no startup do container — se o container já registrou antes, recebe a mesma key; se é nova, recebe key nova.

Containers que sempre geram UUID novo a cada boot acumulam APIKeys (uma por boot) sob o mesmo customer. Se quiser comportamento idempotente real, persista o instance_id em volume montado (/data/instance-id) entre reinicializações.

Como desabilitar para meu customer

No portal do customer (https://license.evolutionfoundation.com.br/portal), há um toggle “Ativação Automática por E-mail”. Quando desabilitado:

Todas as chamadas a /v1/register/auto com seu e-mail retornam 403 AUTO_ACTIVATION_DISABLED
Novos deploys obrigatoriamente passam pelo fluxo manual (navegador + Magic Link/OAuth)
Suas api_keys existentes continuam funcionando normalmente

Recomendado para customers que:

Operam em ambiente regulado e querem trilha de auditoria em cada ativação
Têm o e-mail conhecido publicamente e querem reduzir superfície de ataque
Suspeitam de uso indevido do e-mail

Auditoria

Cada chamada a /v1/register/auto gera uma linha em activation_logs com alert_type = 'auto_activation'. O portal do customer mostra:

Data/hora de cada auto-ativação
IP do servidor que solicitou
Localização aproximada (país/cidade via GeoIP)
Resultado (created ou reused)

Se você ver auto-ativações que não reconhece, suspenda a key correspondente no portal imediatamente — isso revoga acesso da instância sem afetar as outras.

Próximos passos

Fluxo manual

Fluxo completo do /v1/register/init — necessário no primeiro registro

Telemetria

O que é enviado em cada chamada de licença

FAQ

Perguntas frequentes

Visão Geral

Resumo do sistema de licenciamento

​Quando usar

​Endpoint

​Modelo de confiança

​Códigos de erro

​Fluxo recomendado no client

​Variável de ambiente padrão

​Idempotência detalhada

​Como desabilitar para meu customer

​Auditoria

​Próximos passos

Fluxo manual

Telemetria

FAQ

Visão Geral

Quando usar

Endpoint

Modelo de confiança

Códigos de erro

Fluxo recomendado no client

Variável de ambiente padrão

Idempotência detalhada

Como desabilitar para meu customer

Auditoria

Próximos passos