API de Consulta de Operadora: Uma Requisição, um Resultado de Operadora Original
Envie um número E.164 para a API de consulta de operadora, leia a operadora original e o tipo de número, e gerencie resultados vazios, indeterminados e timeouts.
Um guia para desenvolvedores sobre como realizar uma chamada de API de consulta de operadora para um único número: requisição, leitura de resultados, tratamento de erros e quando migrar para requisições múltiplas.
Uma API de consulta de operadora recebe um número de telefone do seu servidor e retorna a operadora à qual aquela faixa numérica foi originalmente alocada, além de contextos relacionados. Com o CarrierLookup, um backend confiável envia um número E.164 para POST /api/v1/check com um cabeçalho X-API-Key e recebe um resultado síncrono: operadora original, operadora subjacente, tipo de número, código do país e a região e cidade de alocação. A operadora refere-se à alocação original, não à rede após a portabilidade. Um resultado concluído com campos vazios ainda é uma consulta concluída, enquanto uma verificação Indeterminado retorna um código de negócio diferente de zero. Para até 100 números em uma única chamada, utilize POST /api/v1/batch-check.
O que uma API de consulta de operadora retorna
Muitas páginas de consulta de operadora confundem duas questões diferentes: para quem aquela faixa numérica foi atribuída e quem atende o número hoje. O CarrierLookup responde à primeira. O resultado da operadora indica o operador ao qual o bloco de números foi originalmente alocado sob o plano nacional de numeração. Em países com portabilidade numérica, um assinante pode manter o número ao mudar de provedor, conforme explicado pelo guia de portabilidade da FCC, portanto, a operadora original e o provedor atual podem ser diferentes.
Um resultado único concluído, descrito em termos simples, contém:
- Operadora original: o operador ao qual a faixa foi alocada.
- Operadora subjacente: a rede por trás daquela operadora, quando um valor está disponível.
- Tipo de número: o tipo da faixa, como móvel ou linha fixa.
- Código do país, região e cidade: onde a faixa foi alocada, não onde uma pessoa ou dispositivo está.
Trate esses dados como contexto de alocação para agrupamento, testes de roteamento e revisão. Um resultado de operadora não indica que um número está em serviço, que pode receber chamadas ou SMS, ou que pertence a uma pessoa específica.
Enviando um número para a API de consulta de operadora
A rota de número único é uma requisição curta e síncrona. Uma integração típica segue cinco passos:
- Mantenha a chave em um servidor confiável. A API REST autentica-se com um cabeçalho X-API-Key. Chame-a a partir do seu backend ou de um executor de tarefas, nunca a partir de código de navegador ou aplicativo móvel, onde a chave poderia ser copiada.
- Normalize a entrada para E.164. O plano ITU-T E.164 define o formato internacional. O CarrierLookup espera um sinal de mais inicial, o código do país e o número do assinante, sem espaços, traços ou parênteses. Um número do Reino Unido escrito como 020 7946 0000 torna-se +442079460000. Bibliotecas como libphonenumber podem analisar formatos locais quando o país do registro é conhecido.
- Envie para POST /api/v1/check. Um número por requisição. Nenhuma seleção de país separada é necessária, pois o código do país já faz parte do número.
- Aguarde a resposta síncrona. O resultado retorna na mesma resposta; não há nada para consultar (polling).
- Armazene o resultado com uma data de consulta. Dados de alocação são estáveis para uma faixa, mas registrar quando cada consulta foi realizada mantém as auditorias simples.
Se a entrada for rejeitada pelo formato, corrija o número e envie novamente. Uma rejeição de formato não diz nada sobre a operadora.
Lendo resultados concluídos, vazios e Indeterminado
O erro de integração mais comum é tratar três resultados diferentes como um só. Verifique primeiro o código de negócio e, em seguida, os valores.
| Resultado | O que a resposta mostra | Como lidar com isso |
|---|---|---|
| Concluído com valores | Código de sucesso e valores preenchidos de operadora, tipo e alocação | Grave os valores no seu registro |
| Concluído, mas vazio | Código de sucesso, alguns ou todos os valores de operadora em branco | Armazene como "indisponível"; ainda é uma consulta concluída e tarifada |
| Indeterminado | Código de negócio diferente de zero e uma mensagem | Não armazene campos em branco como resultado; tente novamente mais tarde ou encaminhe para revisão |
| Formato rejeitado | Erro sobre a entrada | Corrija o número; esta não é uma resposta de "sem operadora" |
Duas regras decorrem da tabela. Segundo, uma verificação Indeterminado não é um resultado vazio bem-sucedido, portanto, nunca grave campos vazios dela em seu CRM. Consultas falhas ou Indeterminado não geram cobrança, enquanto consultas concluídas sim, mesmo quando seus campos estão vazios.
Campos opcionais como operadora subjacente, região ou cidade podem estar em branco em resultados caso contrário completos. Projete seu esquema para que cada campo possa ser nulo independentemente.
Lidando com timeouts, concorrência e saldo
A API pública documenta um pequeno conjunto de controles de uso em vez de uma cota por minuto. Uma conta possui cinco slots simultâneos compartilhados para requisições síncronas, e apenas uma requisição múltipla pode ser executada por vez. Requisições únicas possuem um limite de timeout documentado de 60 segundos, portanto, defina o timeout do seu cliente HTTP ligeiramente acima disso, em vez de apenas alguns segundos.
Manuseio prático:
- Coloque em fila em vez de sobrecarregar. Se o seu processo de cadastro ou importação gera picos, mantenha um pequeno pool de workers para que não haja mais do que cinco consultas em trânsito.
- Tente novamente resultados Indeterminado com espaçamento. Use um atraso e um limite de tentativas; tentativas imediatas repetidas raramente ajudam.
- Registre o código de negócio e a mensagem. Eles explicam falhas muito melhor do que apenas um status HTTP.
- Leia o saldo sem gastá-lo. GET /api/v1/balance retorna o saldo restante sem custo, o que é adequado para uma verificação prévia antes de um trabalho grande.
Para os limites atuais da sua conta, verifique a documentação da API em vez de assumir valores fixos; a API não publica um limite diário fixo de requisições.
Quando migrar para POST /api/v1/batch-check ou uma tarefa de arquivo
A rota de número único atende a trabalhos orientados a eventos: um envio de formulário, um novo registro no CRM, um agente de suporte verificando um contato. Quando um trabalho lida regularmente com vários números de uma vez, uma chamada por número adiciona sobrecarga.
- POST /api/v1/batch-check aceita de 1 a 100 números E.164 em uma única requisição síncrona, e os números podem vir de diferentes países. Os resultados retornam na mesma ordem da entrada, permitindo mapear cada linha pela posição. Cada linha carrega uma flag exists; false significa que não há resultado normal para aquela linha, não que o número seja inválido ou desconectado. Se uma requisição múltipla exceder o tempo limite, a requisição inteira falha sem resultados parciais e o valor reservado retorna integralmente, portanto, mantenha os lotes moderados e tente novamente o lote.
- O painel aceita até 500 números para uma consulta múltipla síncrona sem código.
- Tarefas de arquivo em lote atendem a listas completas: um upload assíncrono de um arquivo TXT ou CSV para um país selecionado, consultado até que um único CSV esteja pronto. Limites por produto se aplicam; consulte a documentação da API.
As mesmas consultas também estão disponíveis para assistentes de IA através do endpoint oficial MCP, que cobre verificações únicas e múltiplas, mas não tarefas de arquivo.
FAQ
Como as equipes podem distinguir um resultado de operadora vazio de uma consulta falha?
Verifique o código de negócio antes de ler quaisquer valores. Um código de sucesso com campos de operadora em branco é uma consulta concluída e deve ser armazenada como indisponível. Um código diferente de zero significa que a verificação foi Indeterminado ou falhou; nada deve ser gravado como resultado, e o registro pode ser tentado novamente mais tarde ou enviado para revisão. Manter esses dois caminhos separados evita marcar registros bons como dados ausentes.
A API de consulta de operadora mostra a rede que um número usa hoje?
Não. O valor da operadora é o operador ao qual a faixa numérica foi originalmente alocada. Após um assinante portar o número, esse operador original permanece o mesmo no resultado, mesmo que o serviço tenha mudado para outro lugar. Equipes que precisam de contexto de alocação para agrupamento, testes de roteamento ou revisão podem usá-lo diretamente; ele não deve ser tratado como a rede de atendimento atual ou como prova de contato.
Um frontend deve chamar a API de consulta de operadora diretamente?
Não deve. O cabeçalho X-API-Key concede acesso ao saldo da conta, portanto, as chamadas pertencem a um servidor confiável. Um padrão comum é o frontend enviar o número de telefone para o seu próprio backend, que o normaliza para E.164, chama POST /api/v1/check, armazena o resultado e retorna apenas o que a interface precisa exibir.
Saiba mais
Escolha as informações do produto que se ajustam ao próximo passo no seu fluxo de trabalho.