Reciclaje de Numbers [Versión preliminar para desarrolladores]

Los números de teléfono no están vinculados de forma permanente a una persona. Cuando un abonado rescinde un contrato de telefonía móvil asociado a un número de teléfono concreto sin transferirlo a otro operador, la compañía de telefonía móvil recuperará finalmente el número y lo volverá a poner a disposición del público. Este proceso se conoce como reciclaje de números.

El reciclaje de números tiene dos motivos principales:

• Desactivación: El número se retira de su abonado actual y ya no se asigna a nadie. Tras la desactivación, el número pasa a «cuarentena».
• Reasignación: Un número desactivado se asigna a un abonado completamente distinto.

Una vez que se desactiva un número, los operadores no lo reasignan de inmediato. Lo mantienen en un periodo de «cuarentena» temporal antes de que pueda volver a utilizarse. Esto ayuda a evitar que un nuevo abonado reciba accidentalmente llamadas o mensajes destinados al titular anterior.

La duración de este periodo varía. Puede estar determinada por la normativa local o por las propias políticas del operador. En Estados Unidos, por ejemplo, la Comisión Federal de Comunicaciones (FCC) exige a los operadores que esperen al menos 45 días antes de reasignar un número desactivado.

La API de reciclaje de números te permite comprobar si un número de teléfono ha cambiado de titular desde una fecha que tú indiques. Debes proporcionar:

• A número de teléfono para comprobarlo.
• A fecha de referencia — normalmente, la fecha en la que confirmaste por última vez que este número pertenecía a tu usuario (por ejemplo, la fecha de registro de su Account).

La API responde con un is_number_recycled campo como true cuando el número de teléfono ha sido desactivado (ya no está asignado a ningún abonado) o reasignado a otro abonado después de la fecha indicada. Devolverá false cuando no se haya detectado ningún cambio de titularidad tras la fecha indicada.

Esto también incluye el periodo de cuarentena: si el número se desactivó pero aún no se había reasignado durante el periodo que has consultado, la respuesta sigue siendo true, ya que el número ya no pertenece al antiguo abonado.

Estos son algunos de los casos de uso más habituales en los que la reutilización de Numbers puede resultar beneficiosa:

Reforzar la verificación de la identidad y el proceso de alta: Cuando un nuevo cliente intenta registrarse con un número reutilizado, el sistema puede consultar la API para verificar si se ha producido un cambio de titularidad desde la creación de la cuenta; si se confirma, se activa automáticamente un flujo de trabajo de «borrado total» que desvincula el MSISDN del perfil obsoleto del titular anterior. Esto elimina los tickets de asistencia manuales, evita la superposición de identidades y garantiza que el nuevo usuario pueda registrarse sin problemas ni rechazos.

Medidas preventivas contra la apropiación de cuentas: El uso de la API de reciclaje de números sirve como paso de preautenticación para acciones de alto riesgo, como el restablecimiento de contraseñas o la alta en la autenticación de dos factores (2FA). Al validar la continuidad de la titularidad desde una fecha de referencia concreta (por ejemplo, el último inicio de sesión correcto), la plataforma puede bloquear de forma programada los intentos de recuperación mediante SMS si el número ha sido reciclado, cerrando así la brecha de seguridad que permite a los delincuentes aprovechar las tarjetas SIM reemitidas para apropiarse de cuentas inactivas, pasando así de una detección reactiva del fraude a una prevención proactiva.

Privacidad en las comunicaciones y cumplimiento normativo: La integración del reciclaje de números en los sistemas de notificación automatizados garantiza que las comunicaciones confidenciales o reguladas —como las alertas bancarias o los recordatorios médicos— nunca se envíen al nuevo titular de un número reciclado. Al realizar una comprobación en tiempo real de la titularidad antes del envío, el producto garantiza un mejor cumplimiento de las leyes de privacidad, como el RGPD y la TCPA, y reduce significativamente el riesgo de fugas accidentales de datos.

Requisitos previos

Para utilizar Identity Insights, debe asegurarse de que su Account está configurado correctamente; consulte la sección Primeros pasos para obtener más información:

• Crear tu Account,
• Creación de una aplicación de Vonage para su uso con la API Identity Insights,
• Los distintos entornos disponibles y cómo configurar tu Account para utilizarlos,
• Y cómo utilizar la interfaz de usuario «Primeros pasos» del panel de control para utilizar la API sin tener que escribir código.

En esta guía se explica cómo utilizar el programa «Number Recycling Insight» mediante comandos, utilizando cURL.

Realizar una llamada a la API

La autenticación para la API Identity Insights se realiza mediante JWT, un token JSON compacto y autocontenido. Para generar un JWT, puede utilizar nuestra herramienta generador en línea, o bien utiliza el CLI de Vonage. Necesitará su ID de aplicación y su clave privada para generar el JWT. Una vez que tenga su JWT, puede enviar una solicitud a la API.

Este ejemplo muestra una solicitud cURL para la función «Number recycling insight», con el fin de comprobar si un suscriptor asociado al número de teléfono indicado es mayor de 18 años; esto viene definido por el age_threshold parámetro, que se puede ajustar en cualquier valor comprendido entre 0 y 120 años:

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
        "phone_number": "14040000000",
        "purpose": "FraudPreventionAndDetection",
        "insights": {
            "number_recycling": {
            "date": "2025-10-31"
            },
        }
    }'

A continuación, la API recuperará la información sobre el reciclaje de números asociada a ese número de teléfono móvil concreto y comprobará si la última fecha de cambio de titularidad se produjo dentro del periodo solicitado en la consulta:

{
    "request_id": "f41087de-b9fc-4081-ab85-9d6475a19706",
    "insights": {
        "number_recycling": {
            "is_number_recycled": true,
            "status": {
                "code": "OK",
                "message": "Success"
                }
        }
    }
}

Aquí, el status indica el estado de la información devuelta para el número de teléfono especificado:

Si status.code en la respuesta se indica que OK, también es posible que aparezcan los campos descritos en la tabla siguiente. Si un campo aparece marcado como «Sí» en la columna «Obligatorio», siempre se mostrará cuando el estado sea «OK». Si un campo aparece marcado como «No», puede que se muestre o puede que no.

Lecturas complementarias

• Para obtener más información sobre la API de Identity Insights, consulta la Referencia API.
• Si tiene alguna pregunta, puede ponerse en contacto con nosotros en el Comunidad de Vonage Slack.