API de Consulta da operadora original em lote: Enviando uma tarefa de arquivo e consultando o CSV

Um guia para desenvolvedores sobre a tarefa de arquivo em lote do CarrierLookup: envio de um arquivo TXT ou CSV com um país, consulta de status e leitura do resultado em CSV único.

A API de consulta da operadora em lote do CarrierLookup é uma tarefa de arquivo assíncrona. Envie uma solicitação multipart para POST /api/v1/bulk-tasks com o campo country posicionado antes do arquivo e, em seguida, leia o status em GET /api/v1/bulk-tasks/{id} com um intervalo de, no mínimo, 30 segundos até que o estado seja success ou failed. Uma tarefa bem-sucedida retorna um CSV para download com a operadora original, operadora subjacente, tipo de número e campos de alocação. A rota é adequada para listas grandes de um único país. Limites por produto se aplicam; portanto, confirme-os primeiro na documentação da API.

Prepare o arquivo antes de chamar a API

Um arquivo limpo economiza mais tempo do que qualquer lógica de repetição. A rota em lote aceita um arquivo TXT ou CSV de uma coluna com um número codificado por país por linha. Arquivos XLSX não são aceitos; portanto, exporte planilhas para texto simples ou CSV primeiro.

Escreva cada linha como dígitos com o código do país. Mantenha a lista essencialmente de um país, pois um único país é selecionado para a tarefa e números fora dele são excluídos.

Uma rotina de preparação rápida:

1. Exporte uma coluna e remova cabeçalhos ou notas.
2. Normalize cada linha para o formato de dígitos com código de país.
3. Divida a lista principal por país e crie um arquivo por país.
4. Verifique o arquivo em relação aos limites atuais na documentação da API. O limite padrão de tamanho de arquivo documentado lá pode ser substituído por um limite retornado pelo serviço ativo; portanto, o valor ativo prevalece.

O pré-processamento excluirá linhas inválidas, duplicatas, números sem código de país e números fora do país selecionado, e nenhum deles é cobrado. Removê-los você mesmo primeiro oferece uma visão mais clara de quantas linhas você realmente enviou. Mantenha uma cópia do arquivo exato que você enviar, com sua contagem de linhas, para que você possa reconciliar o CSV final com sua lista de origem posteriormente e ver quais linhas foram descartadas.

Envie a tarefa com uma solicitação multipart

Envie com POST /api/v1/bulk-tasks a partir de um servidor confiável. Autentique-se com o cabeçalho X-API-Key e nunca exponha a chave no código do navegador.

O corpo é um formulário multipart com duas partes: o país selecionado e o arquivo. A ordem é importante, portanto, coloque a parte do país antes da parte do arquivo. Muitos clientes HTTP constroem o corpo a partir de um dicionário, e a ordem pode seguir a ordem de inserção; verifique como seu cliente a serializa.

Um esboço da chamada com curl:

curl -X POST https://carrierlookup.online/api/v1/bulk-tasks \
  -H "X-API-Key: $CARRIERLOOKUP_API_KEY" \
  -F "country=GB" \
  -F "file=@uk_numbers.csv"

Use o código de país ISO que corresponde à lista. A resposta fornece uma maneira de referenciar a tarefa para consulta; portanto, armazene essa referência com seu próprio registro de trabalho. Não invente campos extras, um array JSON de números, webhooks ou chamadas de cancelamento. Apenas o envio de arquivos e a leitura de status estão documentados.

Consulte a tarefa sem sobrecarregar a API

Leia o status com GET /api/v1/bulk-tasks/{id}. Uma tarefa está em um dos três estados: processing, success ou failed.

Consulte o status com um intervalo de, no mínimo, 30 segundos. Um loop mais curto não acelera o trabalho. Nenhum tempo normal de conclusão é documentado e não há progresso por número; portanto, construa o loop em torno do estado em vez de uma estimativa de duração.

import time, requests

def wait_for_task(task_ref, headers):
    while True:
        r = requests.get(f"https://carrierlookup.online/api/v1/bulk-tasks/{task_ref}", headers=headers, timeout=30)
        state = r.json()["data"]["status"]
        if state in ("success", "failed"):
            return state
        time.sleep(30)

Trate os nomes dos campos neste esboço como espaços reservados e obtenha o formato exato da resposta na documentação da API. Em produção, adicione um tempo máximo de espera que corresponda ao seu cronograma de trabalho, armazene o último estado observado e permita que um alerta de operador seja disparado se uma tarefa permanecer em processing por mais tempo do que sua tolerância permite.

Baixe e leia o CSV

Quando o estado for success, baixe o resultado. Você recebe um CSV, não um ZIP. Ele contém o identificador, operadora, operadora subjacente, tipo de número, código do país, região e cidade para os números que retornaram resultados.

Três regras de leitura:

• O identificador não tem sinal de mais. São apenas dígitos com o código do país e sem espaços. Normalize suas próprias chaves da mesma maneira antes de realizar o cruzamento de dados.
• Células vazias significam Indeterminado. Mantenha-as como valores indisponíveis e não as converta em uma conclusão negativa.
• A operadora é a alocação original. Não é a operadora atual após a portabilidade. Região e cidade descrevem a geografia de alocação, não onde uma pessoa ou dispositivo está.

Carregue o arquivo em uma tabela de preparo primeiro e, em seguida, mescle com seus registros de contato por chave. Mantenha a referência da tarefa e a data de execução na tabela de preparo para que auditorias posteriores possam identificar qual execução produziu quais valores. Lembre-se de que o CSV não possui uma coluna que indique se um número pode ser alcançado, e suas próprias regras não devem inferir isso.

Falhas, reserva e saldo

Uma tarefa em lote reserva um custo estimado quando você a envia e cobra apenas os números que retornam resultados. A parte não utilizada da reserva retorna para a mesma carteira quando a tarefa termina, e uma tarefa com falha retorna toda a sua reserva. Isso é uma reconciliação dentro do seu saldo e não um reembolso de compra.

Uma tarefa pode falhar durante a preparação, por exemplo, quando poucos números de celular válidos são estimados ou outra condição de aceitação não é atendida. Quando isso acontecer, revise o arquivo em busca das exclusões descritas acima, corrija a lista e envie uma nova tarefa em vez de tentar repetir o mesmo arquivo cegamente.

Verifique GET /api/v1/balance antes de enviar. Ele lê o saldo sem cobrar nada. Em um trabalho agendado, compare o saldo com o tamanho da sua lista esperada e pare antes, pois uma reserva que não cabe no saldo interromperia a tarefa. Para pequenos grupos restantes após uma divisão por país, uma solicitação múltipla síncrona via POST /api/v1/batch-check pode ser mais simples do que outra tarefa de arquivo.

FAQ

Como os desenvolvedores podem enviar uma tarefa em lote sem erros multipart?

Coloque o campo country antes do campo file no corpo multipart, envie o arquivo como um TXT ou CSV simples com um número codificado por país por linha e mantenha a chave da API no cabeçalho X-API-Key a partir de um servidor confiável. Verifique como seu cliente HTTP ordena os campos do formulário.

Como os desenvolvedores podem escolher um intervalo de consulta para o status da tarefa?

Consulte a chamada de status com um intervalo de, no mínimo, 30 segundos e pare quando o estado for success ou failed. Nenhum tempo normal de conclusão ou progresso por número é documentado; portanto, defina seu próprio tempo máximo de espera e alerte um operador quando uma tarefa excedê-lo.

Como as equipes podem lidar com uma tarefa em lote com falha?

Leia a falha como um sinal sobre o arquivo ou condições de aceitação. A reserva retorna integralmente; portanto, revise a lista em busca de linhas inválidas, duplicatas, códigos de país ausentes e números fora do país selecionado, corrija-a e envie uma nova tarefa.

Saiba mais

Escolha as informações do produto que se ajustam à próxima etapa do seu fluxo de trabalho.

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