Consulta de números de telefone em lote: solicitações múltiplas síncronas vs. tarefas de arquivo em massa

Uma comparação das duas rotas de lote do CarrierLookup, a solicitação múltipla síncrona e a tarefa de arquivo em massa assíncrona, com um guia de decisão por tamanho de lista e fluxo de trabalho.

A consulta de números de telefone em lote com o CarrierLookup pode ser feita por meio de duas rotas diferentes. Uma solicitação múltipla síncrona processa até 100 números via API, ou até 500 no painel, e retorna resultados ordenados na mesma resposta. Uma tarefa de arquivo em massa processa um arquivo TXT ou CSV para um país selecionado, é executada de forma assíncrona e termina com um CSV para download. Escolha a solicitação múltipla para grupos pequenos e fluxos de trabalho em tempo real, e a tarefa de arquivo para listas grandes e completas. Ambas retornam a operadora original e o contexto de alocação do número, não a operadora atual após a portabilidade e nem um sinal de alcançabilidade.

Duas rotas de lote, dois trabalhos diferentes

As equipes que buscam uma consulta de números de telefone em lote geralmente presumem que todas as ferramentas de lote funcionam da mesma maneira. O CarrierLookup oferece deliberadamente dois formatos, e confundi-los é o erro de planejamento mais comum.

A solicitação múltipla síncrona é uma chamada interativa. Você envia um grupo de números no formato E.164, aguarda e recebe uma resposta ordenada. Os números no grupo podem ser de diferentes países, e não é necessária uma seleção de país separada.

A tarefa de arquivo em massa é um trabalho. Você prepara um arquivo TXT ou CSV de uma coluna, seleciona um país, envia e retorna mais tarde para obter o resultado. O trabalho ocorre em segundo plano e a saída é um arquivo, em vez de um corpo de resposta.

Limites por produto se aplicam a ambas as rotas, portanto, verifique a documentação da API atual antes de dimensionar um trabalho.

Como se comporta uma solicitação múltipla síncrona

Use POST /api/v1/batch-check a partir de um servidor confiável, com a chave de API enviada no cabeçalho X-API-Key. O painel oferece a mesma funcionalidade no navegador para grupos maiores, de até 500 números.

Cada número deve ser escrito no formato E.164: um sinal de mais inicial, o código do país e o número do assinante, sem espaços ou separadores. Um número mal formatado é rejeitado devido ao seu formato. Isso é um problema de formatação a ser corrigido, não uma conclusão de que o número não possui operadora.

A resposta informa quantos números foram enviados, quantos tiveram sucesso e quantos falharam, seguidos pelos resultados na mesma ordem em que você enviou os números. A ordem é importante porque permite mapear cada resposta de volta a uma linha em sua própria tabela sem uma chave de junção.

Dois comportamentos merecem atenção:

• Um resultado marcado como não existente significa que nenhum resultado normal foi retornado para aquele número. Não é uma afirmação de que o número é inválido ou desconectado.
• Se a solicitação inteira exceder o tempo limite, ela falhará como uma unidade. Nenhum resultado parcial é retornado e o valor total é devolvido ao seu saldo.

Como a chamada é síncrona, mantenha-a fora de qualquer caminho onde um usuário esteja aguardando o carregamento de uma página, a menos que você tenha tratado o tempo limite.

Como se comporta uma tarefa de arquivo em massa

Use POST /api/v1/bulk-tasks com um corpo multipart. Coloque o campo de país antes do campo de arquivo, pois a ordem é importante no envio multipart. Em seguida, verifique o progresso com GET /api/v1/bulk-tasks/{id}.

Uma tarefa está em um dos três estados: processando, sucesso ou falha. Consulte o status não mais do que uma vez a cada 30 segundos. Um loop mais frequente adiciona carga sem fazer com que a tarefa termine mais cedo, e nenhum tempo de conclusão é documentado, portanto, planeje com base no status em vez de um relógio.

Antes da execução principal, o arquivo é pré-processado. Linhas inválidas, duplicatas, números sem código de país e números fora do país selecionado são excluídos, e as linhas excluídas não são cobradas. Uma tarefa também pode falhar durante a preparação se o arquivo não atender às condições de aceitação, caso em que o valor reservado retorna integralmente à sua carteira.

Em caso de sucesso, você baixa um CSV, não um ZIP. Suas colunas são o identificador, operadora, operadora subjacente, tipo de número, código do país, região e cidade. No CSV, o identificador são dígitos simples com o código do país e sem o sinal de mais, portanto, normalize suas próprias chaves antes de unir o arquivo a um banco de dados. Células vazias significam que o valor está indisponível.

Escolhendo por tamanho de lista, mistura de países e fluxo de trabalho

Comece pelo formato dos seus dados em vez da contagem bruta.

1. Um grupo de países mistos que precisa de uma resposta agora. Use uma solicitação múltipla síncrona. Uma tarefa de arquivo único forçaria você a dividir a lista por país primeiro.
2. Uma lista grande que é essencialmente de um único país. Use uma tarefa de arquivo. Selecione o país, envie o arquivo e deixe o pré-processamento remover duplicatas e números perdidos.
3. Uma lista grande de países mistos. Divida-a pelo código do país e envie uma tarefa de arquivo por país. Qualquer coisa que não se encaixe em um arquivo de país pode passar por solicitações múltiplas em blocos de até 100 números.
4. Uma verificação registro por registro durante o cadastro ou entrada no CRM. Use a verificação de número único, POST /api/v1/check. Números da China continental, Hong Kong e Macau são suportados apenas por meio de verificações de número único em tempo real em pequenos volumes, portanto, direcione-os para lá em vez de uma solicitação múltipla ou arquivo.

O trabalho em massa também se adapta a tarefas de lote que são executadas durante a noite ou entre campanhas, pois você envia, consulta e coleta. As solicitações múltiplas se adaptam a loops que já processam dados em pequenos blocos e podem gravar resultados diretamente em um banco de dados ou CRM.

Verificações de faturamento e saldo para ambas as rotas

Ambas as rotas utilizam um saldo compartilhado, e cada número concluído é cobrado na mesma taxa publicada. Consultas falhas ou indeterminadas não geram cobrança. Uma consulta concluída cujos campos de operadora estão todos vazios ainda é uma consulta concluída e pode ser cobrada, portanto, não interprete uma linha vazia como gratuita ou como prova de que nenhuma operadora existe.

Uma tarefa de arquivo reserva um valor estimado no envio e, em seguida, cobra apenas os números que retornaram resultados. A parte não utilizada da reserva, ou a reserva total de uma tarefa com falha, retorna à mesma carteira. Isso é uma reconciliação dentro do seu saldo, não um reembolso de compra.

Antes de qualquer envio grande, verifique o saldo com GET /api/v1/balance. A chamada não cobra nada e informa se a reserva será suficiente. Adicione a mesma verificação a um trabalho agendado para que um saldo baixo interrompa a execução antes que ela comece, em vez de falhar no meio de um pipeline.

Lendo os resultados corretamente

Independentemente da rota escolhida, os dados significam a mesma coisa. A operadora é aquela à qual a faixa numérica foi originalmente alocada. Não é a rede que atende o número hoje, pois a portabilidade pode mover um número sem alterar a alocação original. A operadora subjacente e o tipo de número adicionam contexto, e a região e a cidade descrevem a geografia de alocação, e não onde uma pessoa ou dispositivo está.

Isso torna a saída útil para agrupamento, testes de roteamento e filas de revisão. Não é uma evidência de que um número pode receber chamadas ou mensagens, que está ativo ou quem o possui.

Armazene cada campo como um atributo de alocação original, mantenha valores vazios rotulados como indisponíveis e evite substituir qualquer campo que seus próprios sistemas tenham confirmado por outros meios. As equipes que tratam esses campos como contexto de alocação evitam a maioria das disputas posteriores sobre o que os dados prometiam.

Perguntas frequentes

Como as equipes podem decidir entre uma solicitação múltipla e uma tarefa de arquivo?

Observe primeiro o formato da lista. Um grupo de números de países mistos que precisa de uma resposta ordenada imediata se adapta a uma solicitação múltipla. Uma lista grande que é essencialmente de um único país se adapta a uma tarefa de arquivo, que é executada em segundo plano e termina em um CSV. Limites por produto se aplicam, portanto, confirme a documentação da API atual antes de dimensionar qualquer uma das rotas.

Como as equipes podem lidar com a ordem dos resultados em uma solicitação múltipla?

Os resultados retornam na mesma ordem em que os números foram enviados, portanto, mantenha sua própria lista em uma ordem estável e faça a correspondência por posição. Trate um resultado não existente como nenhum resultado normal, não como um número inválido, e tente novamente apenas as linhas necessárias após corrigir quaisquer problemas de formato.

Como as equipes podem evitar consultas desperdiçadas em uma tarefa em massa?

Consulte o status da tarefa não mais do que uma vez a cada 30 segundos e pare quando o estado for sucesso ou falha. Nenhum tempo de conclusão é documentado, portanto, estruture o trabalho em torno do status. Em caso de sucesso, baixe o CSV único e normalize o identificador antes de uni-lo aos registros existentes.

Saiba mais

Escolha as informações do produto que se adaptam ao próximo passo em seu fluxo de trabalho.

• Ver a documentação do produto →
• Falar com a equipe →