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: Se receber mensagem de código inválido, verifique se digitou corretamente o código e o email. O código expira em 30 minutos.

Detalhes do Endpoint

VERBO

POST

URL BASE

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

ENDPOINT

/auth/email/confirm

ou

Detalhes do Endpoint

VERBO

GET

URL BASE

http://api.provista.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 (Código inválido ou expirado)

{
  "success": false,
  "message": "Código inválido ou expirado"
}

Códigos de Resposta

CódigoDescriçãoMétodo
200E-mail verificado com sucessoPOST
302Redirect para login automáticoGET
400Código inválido ou expiradoPOST/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