Fluxo de Ativação - Documentação do Evolution Foundation

Para deploys após o primeiro registro do mesmo e-mail, você pode pular o navegador e usar a ativação automática por e-mail — uma única chamada de API. O fluxo abaixo continua sendo necessário no primeiro registro de um e-mail.

Visão geral do fluxo

Diagrama do fluxo de ativação manual: instância chama register/init, exibe URL, operador autentica no navegador, instância faz polling, recebe api_key, ativa via HMAC e segue com heartbeats.

A URL base do servidor é definida na variável LICENSE_BASE_URL do .env do produto (padrão: https://license.evolutionfoundation.com.br).

Passo 1 — Iniciar registro

Quando a instância detecta que não há api_key salva localmente, ela chama:

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

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

Campos:

Campo	Tipo	Descrição
`tier`	string	`community` ou `beta`
`version`	string	Versão do produto Evolution (ex.: `2.4.0`)
`instance_id`	UUID v4	Identificador local da instância — gerado uma vez e persistido

Resposta (200):

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

O token expira em 30 minutos. Há rate limit de 10 inits por hora por IP. Se o operador não concluir a ativação no prazo, basta repetir o passo 1.

Erros possíveis:

HTTP	Code	Significado
400	`INVALID_TIER`	tier não é `community` nem `beta`
400	`INVALID_BODY`	JSON malformado
429	`RATE_LIMIT`	excedeu 10 inits/hora

Passo 2 — Exibir a URL ao operador

A instância exibe o register_url ao operador. Padrões aceitos:

Web UI / Manager — botão “Ativar Licença” abre o link no navegador
Terminal / CLI — imprime a URL e fica aguardando
QR Code — em deployments headless, gera um QR para escanear

Exemplo de output em CLI:

─────────────────────────────────────────────────────────────────
  Ativação de licença Evolution API
─────────────────────────────────────────────────────────────────

  Para ativar, abra no navegador:

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

  Aguardando confirmação... (expira em 30 minutos)
─────────────────────────────────────────────────────────────────

Passo 3 — O que acontece no navegador

O servidor de licença renderiza a página de registro com a identidade visual da Evolution. O operador escolhe entre:

Magic Link — informa nome e e-mail, recebe link de confirmação por e-mail
Google OAuth — login com conta Google
GitHub OAuth — login com conta GitHub

Após autenticar, o servidor cria (ou recupera) o customer e gera um authorization_code interno. Esse fluxo é transparente para a instância — ela só precisa fazer polling.

Passo 4 — Polling do status

Enquanto o operador resolve o login, a instância faz polling:

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

Resposta enquanto pendente:

{ "status": "pending" }

Resposta quando concluído:

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

Resposta após expiração:

{ "status": "expired" }

Recomendações de implementação:

Intervalo de polling entre 3 e 5 segundos (não mais rápido)
Timeout total de 30 minutos
Quando receber completed, persistir api_key em local seguro (config criptografada, secret manager, etc.)

Passo 5 — Ativar a instância

Com a api_key em mãos, a instância chama o endpoint de ativação:

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

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

Resposta:

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

A geolocalização (operator_country, operator_city) é detectada automaticamente pelo IP da request. A instância não precisa enviar essa informação.

Passo 6 — Heartbeat periódico

Após ativação, a instância envia heartbeats a cada 5 minutos:

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

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

O campo telemetry_bundle é JSON livre. Os campos extraídos automaticamente pelo servidor são detalhados em Telemetria.

Passo 7 — Desativação (opcional)

Em shutdown gracioso (uninstall, container stop intencional), recomenda-se:

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

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

Isso libera a contagem da instância no licenciamento. Não é obrigatório — o servidor expira instâncias inativas automaticamente após 7 dias sem heartbeat.

Autenticação HMAC

Todas as chamadas para /v1/activate, /v1/heartbeat e /v1/deactivate exigem o header X-Signature com HMAC-SHA256 do body. Algoritmo:

Serializar o body em JSON
Calcular HMAC-SHA256(body, api_key)
Converter para hexadecimal
Enviar no header X-Signature

O body usado no HMAC deve ser byte-a-byte idêntico ao enviado. Não reformate o JSON entre o cálculo da assinatura e o envio.

Exemplo 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,
    },
)

Exemplo 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,
  },
});

Exemplo 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 erro

HTTP	Code	Causa	Ação recomendada
401	`HMAC_INVALID`	Assinatura incorreta	Verificar serialização do body
401	`INVALID_API_KEY`	Key mal formatada	Confirmar uso da hex de 64 chars
403	`KEY_SUSPENDED`	Key suspensa por abuso	Contatar suporte
403	`INSTANCE_LIMIT`	Limite de instâncias atingido	Solicitar aumento
404	`INSTANCE_NOT_FOUND`	Heartbeat sem ativação prévia	Rodar `/v1/activate` primeiro
410	`TOKEN_EXPIRED`	Token de 30min expirou	Repetir `/v1/register/init`
429	`RATE_LIMIT`	Excedeu rate limit	Backoff exponencial

Checklist de integração

Para quem está implementando a ativação em um fork ou produto derivado:

Modo offline e degradação

Se o servidor de licença estiver inacessível:

A instância continua funcionando normalmente
Heartbeats falham silenciosamente (sem quebrar a aplicação)
Após reconexão, o próximo heartbeat retoma o ciclo

A ativação inicial (passo 1–5) é a única etapa que exige conectividade. Depois disso, a instância tolera períodos offline. Veja FAQ — modo offline para mais detalhes.

​Visão geral do fluxo

​Passo 1 — Iniciar registro

​Passo 2 — Exibir a URL ao operador

​Passo 3 — O que acontece no navegador

​Passo 4 — Polling do status

​Passo 5 — Ativar a instância

​Passo 6 — Heartbeat periódico

​Passo 7 — Desativação (opcional)

​Autenticação HMAC

​Exemplo Python

​Exemplo Node.js

​Exemplo Go

​Códigos de erro

​Checklist de integração

​Modo offline e degradação

Visão geral do fluxo

Passo 1 — Iniciar registro

Passo 2 — Exibir a URL ao operador

Passo 3 — O que acontece no navegador

Passo 4 — Polling do status

Passo 5 — Ativar a instância

Passo 6 — Heartbeat periódico

Passo 7 — Desativação (opcional)

Autenticação HMAC

Exemplo Python

Exemplo Node.js

Exemplo Go

Códigos de erro

Checklist de integração

Modo offline e degradação