Consultar el nombre de quien llama

Consultar el nombre de quien llama

Obtenga un resultado disponible del nombre de quien llama para un número de teléfono. Esta consulta se realiza en producción y puede generar un cargo en su cuenta, incluso cuando el resultado procede de la caché del servicio. No cambia el nombre que se muestra en las llamadas salientes de un número que le pertenece.

El nombre devuelto no acredita la identidad, la titularidad ni el permiso para llamar. Los nombres pueden faltar, estar desactualizados o abreviados, ser etiquetas geográficas o sustituirse por un número de teléfono como valor alternativo.

Solicitud

Utilice su cuenta de API habilitada desde la dirección IP de origen permitida. Guarde las credenciales en un almacén de secretos del lado del servidor. El ejemplo utiliza variables de entorno y un número ficticio de América del Norte; no incluya credenciales en las URL ni en código público ejecutado en el navegador.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  https://api.multitel.net/v3/cnam/12025550123

Proporcione el número completo en dígitos, incluido el código de país; por ejemplo, once dígitos que comiencen por 1 para América del Norte. No dependa del controlador para normalizar los signos de puntuación ni el signo más. No se requiere un cuerpo de solicitud ni un selector de región. Confirme con MultiTEL la cobertura admitida para el uso previsto.

Respuesta

Los valores son meramente ilustrativos; el coste no constituye una cotización.

{
  "status": {
    "code": 200,
    "msg": ""
  },
  "response": {
    "number": "12025550123",
    "name": "EXAMPLE NAME",
    "cost": 0.0037,
    "balance": 9.9963
  }
}

Cargos y conciliación

Los resultados que incluyen un nombre se cobran al precio de CNAM configurado en la cuenta. Una consulta repetida o atendida desde la caché puede generar otro cargo; no se ofrece ninguna clave de idempotencia. Consulte la tarifa vigente de la cuenta antes de habilitar consultas automatizadas.

Existe una limitación conocida en la respuesta cuando el nombre almacenado en caché está vacío: el controlador puede devolver el código 200 de la API con un nombre vacío, un coste distinto de cero y un saldo calculado reducido, aunque esa rama no realiza ningún débito en la cuenta. No considere esa respuesta por sí sola como prueba de un cargo. Concilie los datos con los registros de facturación de la cuenta y con una nueva consulta de saldo, y póngase en contacto con el servicio de asistencia si los resultados son ambiguos.

La comprobación de prepago exige actualmente un saldo mínimo de 0.004 antes de la consulta, independientemente del precio configurado por consulta. También se rechazan las cuentas con las compras deshabilitadas. Estas comprobaciones no convierten este punto de acceso en una API de cotización de precios ni de limitación del gasto.

Errores y reintentos

Compruebe tanto el estado HTTP como los campos status.code/status.msg de JSON. El código 403 de la API puede indicar crédito de prepago insuficiente, compras prohibidas, un problema de autorización de la cuenta o que no se ha encontrado el nombre de quien llama. La ruta sin nombre puede devolver el código como una cadena de texto. Examine el mensaje en lugar de interpretar todos los códigos 403 como credenciales incorrectas. Los conflictos de configuración pueden devolver el código 500 de la API.

Puede agotarse el tiempo de espera después de una consulta facturable. Utilice un número limitado de reintentos con esperas progresivas solo cuando resulte adecuado para su aplicación y concilie primero los intentos cuyo resultado sea incierto. No reintente repetidamente las consultas de un número rechazado ni las que fallen por permisos o por el saldo de la cuenta. Una caché de respuestas en su propia aplicación puede reducir las solicitudes repetidas, siempre que se respeten su acuerdo y los requisitos de exactitud.

Otras operaciones con números

Esta operación de lectura es independiente de la actualización del nombre de las llamadas salientes o de LIDB, de la inclusión en un directorio y del registro de quien llama. Esas operaciones tienen sus propios campos obligatorios, requisitos de autorización y tarifas. Utilice cobertura de asignación para comprobar la tabla de prefijos o búsqueda de números para consultar el inventario disponible para pedidos. Ninguna de estas operaciones acredita que quien llama sea quien dice ser.