> ## 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.
# Ativação Automática por E-mail
> Ative novas instâncias da Evolution sem abrir navegador — uma única chamada de API com o e-mail já cadastrado.
## Quando usar
O fluxo padrão de [ativação](/licensing/activation) 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
```http theme={null}
POST /v1/register/auto
Content-Type: application/json
{
"email": "operator@example.com",
"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):**
```json theme={null}
{
"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_key`s 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
```python theme={null}
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`**:
```bash theme={null}
# .env
EVOLUTION_OPERATOR_EMAIL=operator@example.com
```
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_key`s 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 completo do `/v1/register/init` — necessário no primeiro registro
O que é enviado em cada chamada de licença
Perguntas frequentes
Resumo do sistema de licenciamento
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.