Códigos de verificación

El endpoint de códigos de verificación permite enviar códigos de verificación de un solo uso (OTP) a números de teléfono a través de múltiples canales de entrega. Soporta una estrategia de enrutamiento de varios pasos con fallback automático — si un canal falla o expira, se intenta automáticamente el siguiente canal.

• Crear una solicitud de código de verificación con una estrategia de enrutamiento flexible
• Soporte para canales de entrega Telegram, Voz (texto a voz) y SMS
• Fallback automático entre canales en caso de fallo o tiempo de espera agotado
• Consultar el estado del código de verificación, el historial de entrega y la información de costos
• Eliminar códigos de verificación del almacenamiento después de la entrega por seguridad

Cómo funciona

Al crear una solicitud de código de verificación, define una estrategia de enrutamiento — una lista ordenada de canales de entrega a intentar. El sistema procesa cada canal en orden:

1. Envía el código de verificación a través del primer canal (ej. Telegram).
2. Telegram: espera una confirmación de entrega de la API de Telegram dentro de timeout_sec. Voz: realiza un intento de llamada; el éxito se produce si el destinatario contesta. SMS: se considera exitoso una vez que el mensaje es aceptado por la red móvil.
3. Si el canal falla o expira, se recurre automáticamente al siguiente canal.
4. Repite hasta que un canal tenga éxito o se hayan agotado todos los canales.

Estrategia de enrutamiento

Cada paso en la estrategia de enrutamiento especifica un channel y parámetros opcionales. Todos los parámetros excepto channel son opcionales — se utilizan valores predeterminados razonables cuando se omiten.

Canal	Parámetros	Criterio de éxito	Notas
telegram	timeout_sec	Confirmación de entrega recibida de Telegram dentro de timeout_sec	timeout_sec: mín 30, máx 3600, predeterminado 30.
voice	sender_id, template	El destinatario contestó la llamada	Llamada de texto a voz. Solo se realiza un intento de llamada. La plantilla se envuelve automáticamente en etiquetas SSML <speak>.
sms	sender_id, template	El SMS fue aceptado para su entrega por la red	Entrega estándar por SMS. Solo puede ser el último paso en la estrategia de enrutamiento.

Reglas:

• Al menos un canal es obligatorio.
• No se permiten canales duplicados.
• El canal sms solo puede ser el último paso (sin fallback después de SMS).
• El parámetro timeout_sec solo es aplicable para el canal telegram.

Optimización de costes

El coste total de una solicitud de código de verificación es la suma de todos los mensajes enviados por todos los canales que se intentaron, incluso si algunos canales fallaron. Cada intento de canal genera un coste por mensaje.

Recomendación: Ordene su estrategia de enrutamiento del canal más económico al más caro. Por ejemplo, coloque telegram primero (coste más bajo), luego voice y sms en último lugar. De este modo, si el canal más económico tiene éxito, se evita pagar por los más costosos.

Bloqueo y filtrado

Antes de intentar la entrega, el sistema verifica el número de teléfono del destinatario contra las restricciones de su cuenta:

• Números de teléfono bloqueados: Si el número del destinatario está en su lista de números bloqueados, el mensaje no será enviado.
• Filtros SMS: Si el número del destinatario coincide con alguno de sus filtros SMS, el mensaje no será enviado.

Cuando un mensaje es bloqueado por un filtro o número bloqueado, el paso del canal y la tarea general reciben el estado 20 (Fallido). No se intenta el fallback al siguiente canal en este caso.

Código de verificación

El código de verificación es una cadena numérica (4–8 dígitos) enviada al destinatario:

• Código personalizado: Proporcione su propio código a través de la propiedad code (4–8 caracteres).
• Generado automáticamente: Si no se proporciona code, se genera un código numérico aleatorio. Controle la longitud con code_length (predeterminado: 4, rango: 4–8).

Use la propiedad template por canal para personalizar el texto del mensaje. El marcador de posición {{code}} se reemplaza con el código de verificación real. Si no se proporciona una plantilla, se utiliza un mensaje traducido predeterminado basado en el campo lang.

Seguridad: Eliminar código después del envío

Establezca is_code_deleted en true para eliminar automáticamente el código de verificación del almacenamiento de LOX24 después de haber sido enviado al destinatario. Esto asegura que el código no se conserve en la base de datos después de la entrega.

IMPORTANTE: Cuando is_code_deleted está activo, el campo code estará ausente en las respuestas GET posteriores después de que la tarea se haya completado.

Códigos de estado

Tanto la tarea general como cada canal individual utilizan los mismos valores de estado, pero la semántica difiere:

Estado de la tarea (status de nivel superior):

Estado	Significado
0	Nuevo — solicitud creada, aún no procesada
5	En progreso — entrega en curso
10	Éxito — código entregado exitosamente a través de al menos un canal
20	Fallido — la entrega falló en todos los canales
100	Error — error del sistema

Estado del canal (history[].status):

Estado	Significado
0	Nuevo — paso del canal creado, aún no procesado
5	En progreso — enviando a través de este canal
10	Éxito — entrega confirmada en este canal
20	Fallido — la entrega falló en este canal
100	Error — error del sistema en este canal

Notificaciones Webhook

Los eventos de códigos de verificación pueden enviarse a su endpoint de webhook. Los siguientes eventos están disponibles:

• verify_code.success — el código fue entregado exitosamente
• verify_code.failed — la entrega falló en todos los canales
• verify_code.channel.sent — código enviado a través de un canal específico
• verify_code.channel.success — el canal confirmó la entrega exitosa
• verify_code.channel.failed — el canal no pudo realizar la entrega
• verify_code.channel.updated — estado del canal actualizado

Consulte la sección Notificaciones Webhook para más detalles sobre la configuración de endpoints de webhook.