Saltar al contenido principal

Verificar código SMS

Endpoint: POST /auth/phone/verify

Permite verificar el código SMS recibido después de registrar un número telefónico, completando el proceso de verificación telefónica.

🔐 Requiere autenticación JWT​

Debes enviar un token JWT válido en el header:

Authorization: Bearer <accessToken>

📝 Cuerpo de la solicitud​

{
  "sessionId": "phone-session-uuid",
  "code": "123456"
}

Parámetros:

  • sessionId: ID de sesión recibido de /auth/phone/register
  • code: Código de 6 dígitos recibido por SMS

📋 Respuestas​

✅ 200 OK​

  • Verificación exitosa

    {
      "code": 1001,
      "message": "Phone verified successfully",
      "data": {
        "phoneVerified": true,
        "verifiedAt": "2025-01-20T14:45:00.000Z",
        "phoneNumber": "543513391269"
      }
    }

❌ 400 Bad Request​

  • Código SMS incorrecto

    {
      "code": 4005,
      "message": "Invalid verification code",
      "details": {
        "attemptsRemaining": 2,
        "maxAttempts": 3
      }
    }

  • SessionId inválido o expirado

    {
      "code": 4006,
      "message": "Invalid or expired session ID"
    }

  • Código expirado

    {
      "code": 4007,
      "message": "Verification code has expired"
    }

  • Faltan campos requeridos

    {
      "message": "Session ID is required"
    }
    {
      "message": "Verification code is required"
    }

❌ 429 Too Many Requests​

  • Demasiados intentos fallidos

    {
      "code": 4030,
      "message": "Too many failed attempts. Request a new code.",
      "details": {
        "cooldownMinutes": 5
      }
    }

❌ 401 Unauthorized​

  • Sin token válido

    {
      "statusCode": 401,
      "message": "Unauthorized"
    }

🔒 Sistema de intentos​

Límites de verificación​

  • Máximo de intentos: 3 intentos por código SMS
  • Cooldown: 5 minutos después de agotar los intentos
  • Expiración: Los códigos expiran en 10 minutos

Comportamiento de intentos​

  1. Primer intento fallido: Se permite continuar
  2. Segundo intento fallido: Se advierte al usuario
  3. Tercer intento fallido: Se bloquea temporalmente
  4. Después del cooldown: Se debe solicitar un nuevo código

📱 Efectos de la verificación exitosa​

Actualización del perfil​

  • Se marca el número como verificado en el perfil del usuario
  • Se actualiza la fecha de verificación telefónica
  • Se habilitan funciones que requieren teléfono verificado

Funcionalidades desbloqueadas​

  • Recuperación por SMS: Opciones adicionales de recuperación de cuenta
  • Notificaciones SMS: Alertas de seguridad por mensaje de texto
  • Verificación en dos pasos: SMS como método 2FA alternativo
  • Operaciones sensibles: Confirmación adicional por SMS

🔄 Flujo completo de verificación​

  1. Solicitar verificación: POST /auth/phone/register con número
  2. Recibir SMS: Código de 6 dígitos enviado al teléfono
  3. Verificar código: Usar este endpoint con sessionId y código
  4. Confirmación: Número queda verificado en el perfil del usuario

📝 Notas​

  • El sessionId debe ser exactamente el recibido de /auth/phone/register
  • Los códigos son case-insensitive pero deben ser exactos
  • Una verificación exitosa es permanente hasta que se cambie el número
  • Si se agotan los intentos, se debe solicitar un nuevo código

🛡️ Características de seguridad​

Protección contra ataques​

  • Rate limiting: Límites estrictos de intentos por sesión
  • Expiración automática: Códigos y sesiones con tiempo limitado
  • Cooldown periods: Prevención de ataques de fuerza bruta
  • Auditoría completa: Logs de todos los intentos de verificación

Validaciones​

  • Formato de código: Solo 6 dígitos numéricos
  • Unicidad de sesión: Una sesión por solicitud de verificación
  • Timeouts: Expiración automática de códigos y sesiones

🔗 Endpoints relacionados​

⚡ Consejos de implementación​

Interfaz de usuario​

  • Mostrar intentos restantes en la UI
  • Proporcionar opción para solicitar nuevo código
  • Implementar timer visual para expiración
  • Autocompletar código desde SMS si es posible

Manejo de errores​

if (response.code === 4005) {
  // Código incorrecto, mostrar intentos restantes
  showError(`Código incorrecto. ${response.details.attemptsRemaining} intentos restantes.`);
} else if (response.code === 4030) {
  // Demasiados intentos, mostrar cooldown
  showError(`Demasiados intentos. Intenta de nuevo en ${response.details.cooldownMinutes} minutos.`);
}

Requisito previo: Debes haber obtenido un sessionId válido de /auth/phone/register antes de usar este endpoint.