Consultar o nome de quem liga
Obtenha um resultado disponível do nome de quem liga para um número de telefone. Esta consulta é realizada em produção e pode gerar uma cobrança na sua conta, inclusive quando o resultado vem do cache do serviço. Ela não altera o nome exibido nas chamadas de saída de um número que pertence a você.
Um nome retornado não comprova identidade, titularidade nem permissão para ligar. Os nomes podem estar ausentes, desatualizados ou abreviados, ser rótulos geográficos ou ser substituídos por um número de telefone como valor alternativo.
Solicitação
Use sua conta de API habilitada a partir do endereço IP de origem permitido. Mantenha as credenciais em um armazenamento de segredos no servidor. O exemplo usa variáveis de ambiente e um número fictício da América do Norte; não coloque credenciais em URLs nem em código público executado no navegador.
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
https://api.multitel.net/v3/cnam/12025550123Forneça o número completo em dígitos, incluindo o código do país; por exemplo, onze dígitos começando com 1 para a América do Norte. Não dependa do processador da solicitação para normalizar a pontuação ou o sinal de mais. Não é necessário um corpo de solicitação nem um seletor de região. Confirme com a MultiTEL a cobertura compatível com o uso pretendido.
Resposta
Os valores são apenas ilustrativos; o custo não constitui uma cotação de preço.
{
"status": {
"code": 200,
"msg": ""
},
"response": {
"number": "12025550123",
"name": "EXAMPLE NAME",
"cost": 0.0037,
"balance": 9.9963
}
}| Campo | Significado |
|---|---|
| number | O número solicitado. |
| name | O nome disponível ou o texto alternativo. Não constitui verificação de identidade. |
| cost | O preço de consulta configurado para a conta ou o serviço, informado por este caminho. Use a tarifa atual da conta, não o valor ilustrativo. |
| balance | O saldo calculado para a resposta. Não é uma nova consulta transacional do saldo da conta. |
Cobranças e conciliação
Os resultados que incluem um nome são cobrados pelo preço de CNAM configurado na conta. Uma consulta repetida ou atendida pelo cache pode gerar outra cobrança; nenhuma chave de idempotência é disponibilizada. Verifique a tarifa atual da conta antes de habilitar consultas automatizadas.
Existe uma limitação conhecida na resposta quando o nome armazenado em cache está vazio: o processador da solicitação pode retornar o código 200 da API com um nome vazio, um custo diferente de zero e um saldo calculado reduzido, embora esse ramo não debite a conta. Não considere essa resposta isoladamente como prova de uma cobrança. Faça a conciliação com os registros de faturamento da conta e uma nova consulta de saldo, e entre em contato com o suporte se os resultados forem ambíguos.
A verificação de pré-pagamento atualmente exige um saldo de pelo menos 0.004 antes da consulta, independentemente do preço configurado por consulta. Uma conta com compras desabilitadas também é rejeitada. Essas verificações não tornam este ponto de acesso uma API de cotação de preços ou de limitação de gastos.
Erros e novas tentativas
Verifique tanto o status HTTP quanto os campos status.code/status.msg do JSON. O código 403 da API pode indicar crédito pré-pago insuficiente, compras proibidas, um problema de autorização da conta ou que nenhum nome de quem liga foi encontrado. O caminho sem nome pode retornar o código como uma cadeia de caracteres. Examine a mensagem em vez de interpretar todo código 403 como credenciais incorretas. Conflitos de configuração podem retornar o código 500 da API.
O tempo de espera pode se esgotar após uma consulta sujeita a cobrança. Use um número limitado de novas tentativas com intervalos progressivos apenas quando isso for adequado à sua aplicação e faça primeiro a conciliação das tentativas com resultado incerto. Não repita continuamente as consultas de um número rejeitado nem as que falharem por permissões ou saldo da conta. Um cache de respostas na sua própria aplicação pode reduzir solicitações repetidas, desde que sejam respeitados seu contrato e os requisitos de precisão.
Outras operações com números
Esta operação de leitura é independente de uma atualização do nome nas chamadas de saída ou de LIDB, de uma inclusão em lista telefônica ou de um cadastro de quem liga. Essas operações têm seus próprios campos obrigatórios, requisitos de autorização e tarifas. Use cobertura de alocação para verificar a tabela de prefixos ou busca de números para consultar o estoque disponível para pedidos. Nenhuma dessas operações comprova que quem liga é quem afirma ser.