Nunciatura Provista

API Documentation V1

Confirmar E-mail

Confirma o e-mail do usuário com código de verificação

Este endpoint é do tipo: Public

Descrição

Valida um código de verificação enviado por e-mail para confirmar o endereço de e-mail do usuário. Este endpoint possui dois modos de uso:

  • POST (API): Valida email e código enviados no corpo da requisição
  • GET (Links em emails): Valida email e código, gera token JWT e redireciona para login automático
  • Valida formato do e-mail
  • Confirma o e-mail com código OTP válido e não expirado
  • O código é de uso único
  • Login automático: Via GET, gera token JWT e redireciona para frontend já autenticado

Importante: Em caso de falha, a API e a página HTML (GET) retornam mensagens específicas conforme o motivo: código já utilizado, expirado, ou inválido/substituído. O código expira em 30 minutos.

Detalhes do Endpoint

VERBO

POST

URL BASE

http://api.provisao.dev.nabrasil.org.br/v1

ENDPOINT

/auth/email/confirm

ou

Detalhes do Endpoint

VERBO

GET

URL BASE

http://api.provisao.dev.nabrasil.org.br/v1

ENDPOINT

/users/activate-email

Cabeçalhos

ParâmetroValor
Content-Typeapplication/json

Parâmetros Query String (GET)

Parâmetro Obrigatório Descrição
email Sim Email do usuário
code Sim Código OTP de 6 dígitos

Exemplos de Requisição

POST - API

POST /auth/email/confirm
Content-Type: application/json

{
  "email": "usuario@exemplo.com",
  "code": "123456"
}

GET - Link de Email (Login Automático)

GET /users/activate-email?email=usuario@exemplo.com&code=123456

Este método redireciona automaticamente para o frontend com o token JWT para login automático.

Corpo da Requisição

{
  "email": "usuario@exemplo.com",
  "code": "123456"
}

Respostas

Sucesso - 200 (POST)

{
  "success": true,
  "message": "Email verificado com sucesso! Você já pode fazer login.",
  "data": {
    "email_verified": true,
    "user": {
      "id": "9fd6b694-602a-461f-a052-c473f59bbcc6",
      "first_name": "João",
      "last_name": "Silva",
      "email": "usuario@exemplo.com",
      "email_verified_at": "2024-10-17T10:30:00.000000Z"
    }
  }
}

Comportamento: Retorna resposta JSON com informações do usuário e status de verificação.

Sucesso - Redirect (GET)

HTTP 302 Redirect
Location: https://frontend.com/auth/callback?token=JWT_TOKEN&email_verified=true&redirect_to=/admin/dashboard

Comportamento: Quando chamado via GET, gera token JWT e redireciona automaticamente para o frontend para login automático. A rota de destino varia conforme a role do usuário:

  • Admin: /admin/dashboard
  • Informador: /protocol/cover
  • Outros: /dashboard

Erro - 422 (Dados inválidos)

{
  "success": false,
  "message": "Dados de validação inválidos",
  "errors": {
    "email": ["O campo email é obrigatório."],
    "code": ["O código deve ter 6 dígitos."]
  }
}

Erro - 400 (Falha na verificação)

O campo message varia conforme o caso. Os campos reason e help_items (lista de orientações, alinhada à página HTML do GET) identificam o motivo e o que fazer (POST).

{
  "success": false,
  "message": "Este link já foi utilizado",
  "reason": "already_used",
  "help_items": ["..."]
}

Valores possíveis de reason: already_used (link/código já usado), expired (prazo expirado), not_found (código inválido ou substituído por reenvio).

GET (link no navegador): em vez de JSON, é exibida uma página HTML com o mesmo tipo de mensagem e orientações.

Conta já ativa (email já confirmado): se o usuário já possui email_verified_at preenchido, o POST retorna 200 com already_verified: true; o GET redireciona para o login com email_verified=true (mesmo comportamento de sucesso), sem tela de erro.

Códigos de Resposta

CódigoDescriçãoMétodo
200E-mail verificado com sucessoPOST
302Redirect para login automáticoGET
400Falha na verificação (mensagem e reason no POST; HTML no GET)POST/GET
422Dados de validação inválidosPOST/GET
500Erro interno do servidorPOST/GET

ℹ️ Informações Importantes

  • Login Automático (GET): Links em emails geram token JWT e redirecionam para login automático
  • Roteamento Inteligente: Admin vai para /admin/dashboard, Informador vai para /protocol/cover
  • Frontend Callback: Frontend deve implementar rota /auth/callback para receber o token e usar o parâmetro redirect_to
  • Segurança: Endpoint não revela se o email existe ou não no sistema
  • Validade: Códigos expiram em 30 minutos após geração
  • Uso POST: Ideal para confirmação manual via interface do sistema
  • Uso GET: Ideal para links em emails com login automático