Advanced US Carrier API: Verificação em lote

Advanced US Carrier: Processe os valores de entrada pela API em lote e obtenha os campos de resultado listados abaixo.

Formato de entrada

Envie um arquivo de texto com um número de telefone por linha. Normalize os valores antes do upload; o formato E.164 é recomendado para telefones.

+14155552671
+442071838750

Criar uma tarefa

POST https://api.checknumber.ai/v1/tasks

curl --location 'https://api.checknumber.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./input.txt"' \
--form 'task_type="us_carrier_premium"'

A API retorna um ID de tarefa. Guarde esse ID e use-o para consultar o status.

Resposta do upload

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "pending",
  "total": 5000,
  "estimated_amount": {
    "amount": "0.500000",
    "currency": "USD"
  },
  "message": "Task created successfully"
}

Verificar status da tarefa

POST https://api.checknumber.ai/v1/gettasks

curl --location 'https://api.checknumber.ai/v1/gettasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'task_id="d4g8o46p2jvh04o9uolg"'

Consulte até que status se torne exported. Não trate pending ou processing como resultado concluído.

Resposta em processamento

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "processing",
  "total": 5000,
  "success": 2500,
  "failure": 0
}

Resposta exportada

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "exported",
  "total": 5000,
  "success": 5000,
  "failure": 0,
  "result_url": "https://example-link-to-results.zip",
  "actual_amount": {
    "amount": "2.000000",
    "currency": "USD"
  }
}

Campos do resultado

Campo	Descrição	Exemplo
Number	Número de telefone do arquivo enviado.	+14155552671
number_type	Tipo de linha retornado para o número.	mobile
carrier	Carrier value returned for the number.	Exemplo Carrier
city	Cidade retornada pelo serviço para a entrada.	valor de exemplo

Note: Live sample currently contains Number, number_type, carrier, and city only.

Tratamento do arquivo de resultado

Baixe o arquivo por result_url somente após a tarefa ser exportada. Preserve os nomes das colunas retornados ao processar o arquivo.

Campos da resposta

Campo	Descrição
created_at	Data e hora de criação da tarefa.
updated_at	Data e hora da última atualização de status.
task_id	Identificador exclusivo da tarefa.
status	pending, processing, exported ou failed.
total	Total de valores de entrada processados.
success	Valores processados com sucesso.
failure	Valores cujo processamento falhou.
result_url	URL de download quando a tarefa é exportada.
actual_amount	Valor final liquidado, quando disponível.
estimated_amount	Valor estimado retornado ao criar a tarefa.

Códigos de status

Status	Descrição
200	Solicitação bem-sucedida.
202	Tarefa criada com sucesso e cobrança estimada aplicada.
400	Arquivo inválido, tipo de tarefa não compatível ou poucas entradas válidas.
401	Chave de API ausente ou inválida.
402	Saldo insuficiente.
404	Tarefa não encontrada.
413	O arquivo enviado é grande demais.
500	Erro interno do servidor; tente novamente mais tarde.

Observações operacionais

• A tarefa é assíncrona; use o ID da tarefa para consultar o status.
• Verifique os limites de entrada do produto antes do upload.
• As linhas com falha aparecem no resultado exportado e são refletidas nos contadores.
• Os campos acima são baseados no sample atual e podem mudar quando o esquema de exportação upstream mudar.