Documentação da API — BulkChecker

Autenticação

Todos os endpoints exigem uma chave de API no header da requisição.

http

X-API-Key: YOUR_API_KEY

Sua chave de API está disponível no Console em "Centro de API". A chave em texto plano só é exibida uma vez na criação; guarde-a imediatamente.

Formato da Resposta

Todos os endpoints retornam JSON.

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued.",
  "summary": {
    "total": 5000,
    "cost_deducted": 0.500000
  }
}

GET /v1/balance

Consultar Saldo

Retorna o saldo USDT atual da conta autenticada.

Exemplo de Resposta

json

{ "balance": "5.230000" }

POST /v1/detect

Enviar Verificação (Array)

Envie um array de números de telefone para verificação. Processado assincronamente. O custo é pré-deduzido; números não verificados são reembolsados automaticamente.

1.000 a 2.000.000 números por requisição. Inclua o código do país, ex. +8613800138000.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
product	string	Sim	Slug do produto. Veja a lista de produtos.
country	string	Sim	Código de país ISO 3166-1 com duas letras, por exemplo CN ou US.
phones	array	Sim	Array de números de telefone, de 1.000 a 2.000.000.

Exemplo de Resposta

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued. Poll GET /api/v1/tasks/xKj9aP3qLm7v for progress.",
  "summary": {
    "total": 5000,
    "cost_deducted": 0.500000
  }
}

POST /v1/detect/file

Enviar Verificação (Upload de Arquivo)

Envie um arquivo TXT ou CSV com um número por linha, máx 50 MB.

Parâmetros

Content-Type: multipart/form-data

Campo	Tipo	Obrigatório	Descrição
product	string	Sim	Slug do produto
country	string	Sim	Código de país ISO
file	file	Sim	Arquivo TXT ou CSV, um número por linha, máximo 50 MB.

Exemplo de Resposta

json

{
  "mode": "async",
  "task_id": "qH5rZ7Lp3Wm9",
  "message": "File queued (10000 numbers). Poll GET /api/v1/tasks/qH5rZ7Lp3Wm9 for progress.",
  "summary": {
    "total": 10000,
    "cost_deducted": 1.000000
  }
}

GET /v1/tasks/{task_id}

Status da Tarefa

Faça polling da tarefa até o status ser completed ou failed. Intervalo recomendado: 3–5 segundos.

Exemplo de Resposta

json

{
  "task_id": "xKj9aP3qLm7v",
  "status": "completed",
  "progress": 100,
  "product": "whatsapp-active",
  "country": "CN",
  "total": 5000,
  "processed": 5000,
  "valid": 3800,
  "invalid": 1200,
  "unknown": 0,
  "cost_deducted": "0.500000",
  "cost_refunded": "0.000000",
  "result_available": true,
  "result_expires_at": "2026-05-02T10:00:00+00:00",
  "created_at": "2026-05-01T10:00:00+00:00"
}

Status da Tarefa

status	Descrição
pending	Na fila, aguardando recursos.
processing	Detecção em andamento.
completed	Concluído. O resultado está pronto para download.
failed	Execução falhou.

GET /v1/tasks/{task_id}/result

URL de Download

Após concluída, recupere uma URL de download para o arquivo de resultado. Os arquivos são mantidos por 7 dias por padrão (controlado pela configuração result_retention_days).

Exemplo de Resposta

json

{
  "task_id": "xKj9aP3qLm7v",
  "download_url": "https://api.bulkchecker.io/api/v1/tasks/xKj9aP3qLm7v/download",
  "expires_at": "2026-05-02T10:00:00+00:00",
  "summary": {
    "total": 5000,
    "valid": 3800,
    "invalid": 1200,
    "unknown": 0
  }
}

Códigos de Erro

Em caso de falha, verifique o código HTTP e o campo message.

HTTP	Erro	Solução
401	Unauthenticated	Verifique se o header X-API-Key está presente e válido.
402	Insufficient balance.	Saldo insuficiente. Recarregue e tente novamente.
404	Not found	task_id não existe ou pertence a outra conta.
422	Validação falhou	Verifique campos obrigatórios, formato dos números e tipo de arquivo.
429	Too Many Requests	Endpoints de detecção têm limite de 10 requisições por minuto.

Lista de Produtos

Use o valor slug no campo product ao enviar uma tarefa.

Nome do produto	Slug
Verificador de números do Amazon	`amazonValid`
Verificador de emails para Amazon	`amazonemailValid`
Verificador de números do Apple ID	`appleidValid`
Verificador de emails para Apple ID	`appleidEmailValid`
Verificador de números do BAND	`bandValid`
Verificador de números do Binance	`binanceValid`
Verificador de emails para Binance	`binanceEmailValid`
Verificador de números do CoinW	`coinwValid`
Verificador de emails para CoinW	`coinwEmailValid`
Verificador de números do Facebook	`fbValid`
Verificador de emails para Facebook	`fbemailValid`
Consulta HLR	`hlr-lookup`
Verificador de números do HTX	`htxValid`
Verificador de emails para HTX	`htxEmailValid`
Verificador de números do iMessage	`imessageValid`
Verificador de números do Instagram	`instagram`
Verificador de emails para Instagram	`insEmailValid`
Verificador de números do KuCoin	`kucoinValid`
Verificador de emails para KuCoin	`kucoin`
Idade e gênero do LINE	`lineGender`
Verificador de números do LINE	`lineValid`
Number Checker	`linkednAll`
Number Checker	`linkedn`
Verificador de números do Microsoft	`microsoftValid`
Verificador de números do RCS	`RCSValid`
Verificador de números do Signal	`signalValid`
Verificador de números do Snapchat	`snapchatValid`
Perfil completo do Telegram	`tgGender`
Verificador de números do Telegram	`tgValid`
Verificação de atividade do Telegram	`tgActive`
Busca de usuário do TikTok	`tkUsername`
Verificador de números do Viber	`viberValid`
Verificação de atividade do Viber	`viberActive`
Perfil completo do WhatsApp	`wsGender`
Verificador de números do WhatsApp	`wsValid`
Verificação de atividade do WhatsApp	`wsActive`
Idade e gênero do Zalo	`zaloGender`
Verificador de números do Zalo	`zaloValid`
Filtro de atividade na internet	`internet-activity-filter`
Verificação de status do número	`phone-status-check`
Detecção de modelo de telefone	`phone-model-detection`
Phone Status Check（CN）	`cnActiveNumber`

Exemplos Completos

Copie e execute estes exemplos cURL — substitua YOUR_API_KEY e os parâmetros.

1. Consultar saldo

bash

curl -X GET "https://api.bulkchecker.io/api/v1/balance" \
  -H "X-API-Key: YOUR_API_KEY"

2. Enviar detecção

bash

curl -X POST "https://api.bulkchecker.io/api/v1/detect" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "whatsapp-active",
    "country": "CN",
    "phones": ["+8613800138000", "+8613900139000"]
  }'

3. Enviar arquivo

bash

curl -X POST "https://api.bulkchecker.io/api/v1/detect/file" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "product=whatsapp-active" \
  -F "country=CN" \
  -F "file=@/path/to/numbers.txt"

4. Consultar status da tarefa

bash

curl -X GET "https://api.bulkchecker.io/api/v1/tasks/xKj9aP3qLm7v" \
  -H "X-API-Key: YOUR_API_KEY"

5. Obter URL de download

bash

curl -X GET "https://api.bulkchecker.io/api/v1/tasks/xKj9aP3qLm7v/result" \
  -H "X-API-Key: YOUR_API_KEY"