Saltar al contenido principal

Registrar número telefónico

Endpoint: POST /auth/phone/register

Permite registrar y verificar un número telefónico para el usuario autenticado mediante el envío de un código SMS usando el servicio Infobip.

🔐 Requiere autenticación JWT​

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

Authorization: Bearer <accessToken>

📝 Cuerpo de la solicitud​

{
  "phone": "543513391269"
}
  • phone: Número telefónico en formato internacional (sin el símbolo +)

✅ Formato de número telefónico​

  • Formato requerido: Número internacional sin el símbolo +
  • Ejemplos válidos:
    • 543513391269 (Argentina)
    • 12125551234 (Estados Unidos)
    • 447911123456 (Reino Unido)
  • Sin espacios, guiones o paréntesis

📋 Respuestas​

✅ 200 OK​

  • SMS enviado correctamente

    {
      "code": 1010,
      "message": "SMS sent successfully",
      "sessionId": "phone-session-uuid"
    }

❌ 400 Bad Request​

  • Formato de teléfono inválido

    {
      "message": "Invalid phone number format"
    }

  • Número ya registrado

    {
      "message": "Phone number already registered"
    }

  • Faltan datos

    {
      "message": "Phone number is required"
    }

❌ 429 Too Many Requests​

  • Límite de SMS excedido

    {
      "message": "SMS rate limit exceeded. Try again later."
    }

❌ 401 Unauthorized​

  • Sin token válido

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

📱 Integración con Infobip​

Características del SMS​

  • Código de verificación: 6 dígitos numéricos aleatorios
  • Duración: El código expira en 10 minutos
  • Plantilla: Mensaje personalizable con el código
  • Cobertura: Envío global a través de la red de Infobip

Configuración de envío​

  • Remitente: Configurable en variables de entorno
  • Formato del mensaje: Incluye código y nombre de la aplicación
  • Reintentos: Sistema automático de reintentos en caso de fallo

🔄 Flujo de verificación telefónica​

  1. Registro: Llamar a este endpoint con el número de teléfono
  2. Recibir SMS: El usuario recibe un código de 6 dígitos
  3. Verificación: Usar /auth/phone/verify con el código y sessionId

🛡️ Rate Limiting​

Límites específicos para SMS​

  • Por usuario: 5 SMS por hora
  • Por número: 3 SMS por número por día
  • Global: Límites configurables para prevenir abuso

Reintentos​

  • Código expirado: Permite solicitar nuevo código después de 10 minutos
  • Código incorrecto: No afecta la capacidad de solicitar nuevos códigos

📝 Notas​

  • El sessionId es requerido para la verificación posterior
  • Cada solicitud genera un nuevo código, invalidando el anterior
  • El número debe ser válido y capaz de recibir SMS
  • Compatible con números internacionales de la mayoría de países

🌍 Soporte internacional​

Países soportados​

  • América: Argentina, Brasil, México, Estados Unidos, Canadá, etc.
  • Europa: España, Francia, Reino Unido, Alemania, Italia, etc.
  • Asia: India, China, Japón, Singapur, etc.
  • Otros: Cobertura global según disponibilidad de Infobip

Códigos de país comunes​

  • Argentina: +54 → 54
  • España: +34 → 34
  • México: +52 → 52
  • Estados Unidos: +1 → 1

🔗 Endpoints relacionados​

⚡ Consejos de implementación​

Validación frontend​

function validatePhoneNumber(phone) {
  // Ejemplo básico: solo dígitos, longitud razonable
  return /^\d{10,15}$/.test(phone);
}

Manejo de errores​

  • Informar al usuario sobre formato correcto
  • Mostrar ejemplos de números válidos para su país
  • Implementar selección de código de país si es necesario

Siguiente paso: Usar el sessionId recibido junto con el código SMS en /auth/phone/verify para completar la verificación telefónica.