Como o CarrierLookup consulta a operadora de um número

Conclua uma verificação

Esta seção aborda as verificações em tempo real: o painel SaaS e os endpoints REST síncronos compartilham um único serviço de verificação e o mesmo significado de resposta. Listas muito grandes contam com uma opção em massa assíncrona, abordada no final desta página.

1. 1

   Envie um número

   Envie um número completo, conforme descrito na documentação da API.

2. 2

   Use service_type=carrier

   O produto carrier retorna a rede à qual o número foi originalmente alocado, com o tipo de linha e a região de alocação.

3. 3

   Leia o resultado

   Leia os campos da operadora na mesma resposta. Eles descrevem a alocação original, não a operadora que atende o número hoje.

Qual formato de número enviar

O CarrierLookup aceita um número por consulta, escrito no formato E.164: um sinal de mais, o código do país e, em seguida, o número do assinante, sem espaços ou separadores.

• Envie o número completo, incluindo o código do país. Um número nacional sem ele não pode ser consultado.
• Formatos nacionais com zeros iniciais, espaços, hifens ou parênteses não são aceitos — envie apenas o + e os dígitos.
• Números no formato incorreto são rejeitados antes de qualquer cobrança; um formato rejeitado não é uma resposta “sem resultado”.

O que significam os campos da operadora?

Os campos da operadora são a resposta de uma consulta de operadora: carrier, underlying_carrier, number_type, country_code, region e city, no nível superior de uma resposta bem-sucedida. Eles trazem a operadora e o tipo de linha originalmente alocados, o país e a região e a cidade de alocação quando o provedor os fornece. Não há flag registered — uma resposta bem-sucedida é o resultado. Qualquer outro desfecho — tempo esgotado, resultado indeterminado, número inválido — volta como um código de erro, e essa consulta é reembolsada automaticamente. Um valor vazio nunca significa “sem operadora”; significa que o provedor não forneceu aquele campo.

• carrier é a rede à qual o número foi alocado quando foi emitido.
• number_type, region e city podem ficar vazios quando o provedor não os fornece; as chaves estão sempre presentes.
• Trate os demais desfechos de acordo com o código de resposta da API; não deduza a alocação por conta própria.

Use o resultado dentro do seu escopo

Um resultado de operadora descreve a rede à qual o número foi originalmente alocado. Não é uma verificação de alcançabilidade, nem verificação de identidade, nem permissão para contatar alguém.

• Não confirma quem é o titular do número e não acompanha a portabilidade numérica — um número portado continua informando a operadora à qual sua faixa foi originalmente alocada.
• Um resultado de operadora não estabelece consentimento para contatar o número.
• Não trate o resultado como a operadora atual: consultar o número novamente retorna a mesma alocação original, não a rede para a qual ele possa ter sido portado.

Listas muito grandes: a opção assíncrona

A verificação múltipla do painel e o endpoint múltiplo da API atendem à maioria das listas. Só quando uma lista excede muito esses limites faz sentido enviar o arquivo inteiro como uma única tarefa em massa assíncrona.

• Envie um .txt ou .csv com um número por linha, pela página de verificação em massa ou pela API.
• Escolha o país ao qual os números pertencem ao enviar; ainda assim, cada linha deve estar no formato E.164.
• O saldo é reservado para as linhas válidas no envio, você é cobrado apenas pelos números que retornam resultado e a diferença é reembolsada.
• A tarefa é executada em segundo plano; baixe o arquivo de resultado quando terminar. Uma tarefa com falha é reembolsada integralmente.