Documentação da API

Autenticação

Todos os endpoints exigem uma chave de API no header da requisição. The public product catalog does not require authentication.

http

X-API-Key: YOUR_KEY_HERE

Authorization: Bearer YOUR_KEY_HERE

Sua chave tem 51 caracteres: o prefixo zn_ seguido de 48 caracteres aleatórios. Chaves emitidas anteriormente com o prefixo ck_ continuam válidas.

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.

Exemplo de resposta em tempo real

json

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "status": "succeeded",
  "replayed": false,
  "results": []
}

Exemplo de resposta em lote

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued."
}

GET /v1/balance

Consultar Saldo

Retorna o saldo USD atual da conta autenticada.

Exemplo de Resposta

json

{ "balance": "5.230000" }

GET /v1/products

Lista de Produtos

Catálogo público de produtos; não é necessária uma chave de API. Ele retorna produtos ativos em tempo real e em lote, suas séries e quantidades mínimas. Consulte-o antes de enviar.

Exemplo de Resposta

json

{
  "data": [
    {
      "id": 101,
      "slug": "whatsapp-realtime",
      "name": "WhatsApp Number Checker",
      "name_translations": { "zh_CN": "WhatsApp 注册检测" },
      "mode": "realtime",
      "series": "phone",
      "min_phones": 1
    }
  ]
}

GET /v1/api-key

Detalhes da chave de API

Retorna os metadados da chave de API da conta autenticada. A chave em texto simples nunca é retornada.

json

{
  "api_key_id": 42,
  "masked_key": "ck_••••••••••••••••••••••••••••••••••••••••••••••••",
  "last_used": "2026-09-05T10:00:00Z",
  "created_at": "2026-08-01T09:00:00Z"
}

A chave em texto simples é exibida apenas uma vez ao ser criada ou alternada; este endpoint retorna somente um valor mascarado.

Códigos de Erro

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

Corpo de erro

json

{
  "code": "insufficient_balance",
  "message": "Insufficient balance for this submission."
}

Erros de negócio sempre retornam um code legível por máquina para ramificação programática. Parâmetros inválidos (validação) e rotas desconhecidas retornam o formato padrão do Laravel: { "message": "...", "errors": { ... } }. Valide as entradas antes de enviar.

Erro

code	HTTP	Descrição
unauthorized	401	Chave de API ausente, inválida ou inativa.
account_banned	403	Conta suspensa. Fale com o suporte.
invalid_realtime_request	400	Requisição em tempo real malformada (ex.: número sem prefixo internacional + quando country é omitido).
idempotency_key_required	400	Requisições em tempo real exigem o cabeçalho Idempotency-Key.
invalid_idempotency_key	422	Idempotency-Key inválido: 1-128 caracteres de letras, dígitos e . _ : -
idempotency_conflict	409	A mesma Idempotency-Key foi usada com um conteúdo de requisição diferente.
request_in_progress	409	Uma requisição em tempo real idêntica ainda está sendo processada. Tente novamente em breve (Retry-After: 1).
empty_input	422	O arquivo enviado não contém linhas utilizáveis.
product_not_found	422	O slug de produto enviado não existe ou está inativo.
product_mode_not_supported	422	Este endpoint não aceita este modo de produto (produtos em tempo real não vão para endpoints em lote).
invalid_country	422	O produto não suporta o país enviado.
too_few_numbers	422	O envio está abaixo do mínimo do produto.
too_many_numbers	422	O envio excede o máximo da plataforma.
insufficient_balance	402	Saldo insuficiente. Recarregue e tente novamente.
realtime_disabled	403	A detecção em tempo real não está habilitada para esta conta.
realtime_rate_limited	429	Limite de requisições em tempo real excedido. Respeite o retry_after.
product_pricing_unavailable	503	O preço deste produto ainda não está configurado. Fale com o suporte.
detection_capacity_unavailable	503	Sem capacidade de detecção disponível no momento. Tente mais tarde.
realtime_route_unavailable	503	Nenhuma rota em tempo real disponível. Tente mais tarde.
realtime_fact_cache_unavailable	503	Uma dependência em tempo real está temporariamente indisponível. Tente mais tarde.
realtime_rate_limiter_unavailable	503	O limitador de requisições está temporariamente indisponível. Tente mais tarde.
not_found	404	task_id não existe ou pertence a outra conta.
result_not_ready	422	A tarefa não foi concluída ou seu arquivo de resultado ainda não foi gerado.
result_expired	404	O arquivo de resultado expirou, está ausente ou indisponível.
validation_failed	422	Verifique campos obrigatórios, formato dos números e tipo de arquivo.
internal_error	500	Erro interno do servidor. É seguro repetir com a mesma Idempotency-Key.

Limites de requisições

As requisições à API são limitadas por chave de API, por grupo de endpoints:

Endpoints	Limite
GET /v1/products · GET /v1/balance · GET /v1/api-key · GET /v1/tasks/{token} · GET /v1/tasks/{token}/result · GET /v1/tasks/{token}/download	60 requisições / minuto por chave de API (120 / minuto por IP)
Rotas: POST /v1/detect · POST /v1/detect/file · POST /v1/quotes/bulk	10 requisições / minuto por chave de API (30 / minuto por IP)
Rotas: POST /v1/realtime/quote/{series} · POST /v1/realtime/check/{series} · POST /v1/realtime/detect	Token bucket por chave de API: burst 60, recarga 1/s (≈60 / minuto sustentado); por conta: burst 120, recarga 2/s. A camada de IP permite 180 / minuto. Cada resposta inclui o cabeçalho X-RateLimit-Remaining.

Ao exceder um limite, a API retorna 429 com o cabeçalho Retry-After (respostas em tempo real também incluem o campo retry_after). Pause as requisições pelo número de segundos indicado e retome com backoff exponencial.

POST /v1/realtime/check/{series}

Consulta unitária em tempo real

Consulta síncrona de um telefone ou endereço de e-mail. Uma solicitação pode selecionar vários produtos em tempo real da mesma série por ID; não use slugs de produtos em lote.

Idempotency-Key é obrigatório. Repetir a mesma solicitação com a mesma chave não gera cobrança duplicada; alterar o conteúdo retorna 409. cached=true indica resultado reutilizado.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
series	path	Sim	Série: phone ou email; deve corresponder à série do produto em tempo real selecionado.
identifier	string	Sim	Um identificador: número E.164 ou endereço de e-mail válido.
country	string	Não	Somente para telefone: opcional com E.164 completo; um número nacional exige o código ISO correspondente. Deixe vazio para e-mail.
product_ids	array<int>	Sim	Lista de 1 a 10 IDs de produtos em tempo real.

Exemplo de Resposta

json

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "identifier": "+8613800138000",
  "series": "phone",
  "status": "succeeded",
  "request_status": "completed",
  "total_reserved": 0.004000,
  "total_charged": 0.004000,
  "total_refunded": 0.000000,
  "charged_amount": 0.004000,
  "refunded_amount": 0.000000,
  "replayed": false,
  "results": [
    {
      "product_id": 101,
      "product": "whatsapp-realtime",
      "result": "valid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.004000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-05T10:00:00Z",
      "error_code": null
    }
  ]
}

Exemplo de cURL

bash

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/phone" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","country":"CN","product_ids":[101,102]}'

bash

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/email" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"[email protected]","country":null,"product_ids":[201]}'

Cada produto usa o preço por consulta fixado para a solicitação, inclusive com cache. valid e invalid são cobrados; unknown, timeout e itens ocupados são reembolsados.

Um combo parcialmente bem-sucedido retorna HTTP 200 com status=partial_succeeded; falha total usa status=failed. Verifique billing_status e error_code de cada item.

Idempotency-Key tem até 191 bytes e é limitado por usuário. Após timeout ou erro 500, repita o conteúdo original com a chave original. Os resultados são mantidos por 30 dias por padrão.

HTTP	code	Significado / ação
400	invalid_realtime_request / idempotency_key_required	Corrija o número, os produtos ou a chave; não houve pré-cobrança.
401 / 403	unauthorized / account_banned / realtime_disabled	Verifique a chave, a conta e o acesso em tempo real; não houve pré-cobrança.
402	insufficient_balance	Saldo insuficiente; nenhum item do combo é executado.
409	request_in_progress / idempotency_conflict	Repita após Retry-After; um conteúdo diferente não pode reutilizar a chave.
429	realtime_rate_limited	Aguarde o Retry-After; não houve pré-cobrança.
503	realtime_route_unavailable / realtime_fact_cache_unavailable / realtime_rate_limiter_unavailable	Rota, cache ou limitador indisponível; tente novamente mais tarde.
500	internal_error	O resultado é incerto. Repita com a chave original e não envie uma nova chave.

error_code identifica falhas do provedor, capacidade, prazo, cache ou proteção de concorrência. Itens com falha não são cobrados.

O endpoint de compatibilidade POST /v1/realtime/detect é mantido temporariamente para clientes antigos. Novas integrações devem usar /v1/realtime/check/phone ou /v1/realtime/check/email.

Lista de Produtos · Unitário (tempo real)

Os produtos em tempo real são selecionados pelo ID do produto e pela série; não use slugs de produtos em lote.

Nome do produto	Series	Identificador	Mínimo
Verificação de número de Amazon	`phone`	`#53`	1
Verificação de e-mail de Amazon	`email`	`#54`	1
Verificação de número de Apple ID	`phone`	`#57`	1
Verificação de e-mail de Apple ID	`email`	`#58`	1
Verificação de número de BAND	`phone`	`#60`	1
Verificação de número de Facebook	`phone`	`#51`	1
Verificação de e-mail de Facebook	`email`	`#52`	1
Verificação de número de Instagram	`phone`	`#48`	1
Verificação de e-mail de Instagram	`email`	`#49`	1
Verificação de número de Microsoft	`phone`	`#59`	1
Verificação de número de Telegram	`phone`	`#50`	1
Verificação de número de Viber	`phone`	`#55`	1
Verificação de número de WhatsApp	`phone`	`#47`	1
Verificação de número de telefone no X	`phone`	`#61`	1

POST /v1/detect

Enviar Verificação (Array)

Envie uma lista de telefones ou e-mails para detecção em lote assíncrona. O custo é reservado e os itens não processados são reembolsados.

O mínimo é definido pelo produto e o máximo da plataforma é 2.000.000. Omita country para e-mail; ele é obrigatório para telefone.

HTTP 202 Accepted

Parâmetros

Campo	Tipo	Obrigatório	Descrição
product	string	Sim	Slug do produto. Veja a lista de produtos.
country	string	Obrigatório para telefone; omita para e-mail	Código de país ISO 3166-1 de duas letras. Obrigatório para telefone; omita para e-mail.
phones	array	Sim	Array de telefones ou e-mails; o produto define o mínimo e o máximo é 2.000.000.

Exemplo de Resposta

json

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

POST /v1/detect/file

Enviar Verificação (Upload de Arquivo)

Envie um TXT ou CSV para detecção em lote, um telefone ou e-mail por linha, máximo de 50 MB.

HTTP 202 Accepted

Parâmetros

Content-Type: multipart/form-data

Campo	Tipo	Obrigatório	Descrição
product	string	Sim	Slug do produto
country	string	Obrigatório para telefone; omita para e-mail	Código ISO obrigatório para telefone; omita para e-mail.
file	file	Sim	Arquivo TXT ou CSV, um telefone ou e-mail por linha, máximo de 50 MB.

Exemplo de Resposta

json

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

GET /v1/tasks/{token}

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": "YOUR_PRODUCT_SLUG",
  "country": "CN",
  "submitted": 5000,
  "prefiltered": 0,
  "deduped": 0,
  "total": 5000,
  "processed": 5000,
  "valid": 3800,
  "invalid": 1200,
  "unknown": 0,
  "unknown_processed": 0,
  "unknown_unprocessed": 0,
  "stage": "completed",
  "stage_seconds": 12,
  "last_progress_at": "2026-09-05T10:00:12+00:00",
  "failure_message": null,
  "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/{token}/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.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/download",
  "expires_at": "2026-05-02T10:00:00+00:00",
  "summary": {
    "submitted": 5000,
    "prefiltered": 0,
    "deduped": 0,
    "total": 5000,
    "valid": 3800,
    "invalid": 1200,
    "unknown": 0,
    "unknown_processed": 0,
    "unknown_unprocessed": 0
  }
}

GET /v1/tasks/{token}/download

Baixar resultado

Baixa o arquivo de resultado de uma tarefa concluída enquanto ele estiver dentro do período de retenção.

Exemplo de Resposta

Content-Type: application/zip (or text/csv for a single result).

Este endpoint transmite um arquivo em vez de JSON. Retorna 404/422 quando a tarefa não está pronta, expirou, está indisponível ou pertence a outra conta.

Lista de Produtos · Em lote (assíncrono)

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

Nome do produto	Identificador	Mínimo
Verificação de número de Amazon	`amazonValid`	500
Verificação de e-mail de Amazon	`amazonEmailValid`	1000
Verificação de número de Apple ID	`appleidValid`	2000
Verificação de e-mail de Apple ID	`appleidEmailValid`	1000
Verificação de número de BAND	`bandValid`	500
Verificação de número de Binance	`binanceValid`	2000
Verificação de e-mail de Binance	`binanceEmailValid`	2000
Verificação de número de CoinW	`coinwValid`	2000
Verificação de e-mail de CoinW	`coinwEmailValid`	2000
Verificação de número de Facebook	`fbValid`	500
Verificação de e-mail de Facebook	`fbEmailValid`	1000
Verificação de número de HTX	`htxValid`	1000
Verificação de e-mail de HTX	`htxEmailValid`	2000
Verificação de número de iMessage	`imessageValid`	2000
Verificação de número de Instagram	`insValid`	500
Verificação de e-mail de Instagram	`insEmailValid`	1000
Verificação de número de KuCoin	`kucoinValid`	1000
Verificação de e-mail de KuCoin	`kucoinEmailValid`	2000
Idade e gênero em LINE	`lineGender`	2000
Verificação de número de LINE	`lineValid`	2000
Perfil completo do Linkedin	`linkedinGender`	2000
Verificação de número do Linkedin	`linkedinValid`	2000
Verificação de número de Microsoft	`microsoftValid`	500
Verificação de suporte ao RCS	`rcsValid`	1000
Verificação de número de Signal	`signalValid`	2000
Verificação de número de Snapchat	`snapchatValid`	500
Perfil completo do Telegram	`tgGender`	500
Verificação de número de Telegram	`tgValid`	1000
Verificação de atividade do Telegram	`tgActive`	500
Busca de nome de usuário do TikTok	`tiktokUsername`	2000
Verificação de número de Viber	`viberValid`	1000
Verificação de atividade do Viber	`viberActive`	1000
Perfil completo do WhatsApp	`waGender`	1000
Verificação de número de WhatsApp	`waValid`	1000
Detalhes da atividade do WhatsApp	`waActive`	500
Verificação de número de telefone no X	`twitterValid`	2000
Verificação de e-mail do X	`twitterEmailValid`	2000
Idade e gênero em Zalo	`zaloGender`	500
Verificação de número de Zalo	`zaloValid`	2000
Filtro de atividade na internet	`live-activity-filter`	2000
Verificação do status do número	`phone-status-check`	2000
Celular ligado/desligado	`phone-onoff-check`	1500
Detecção de modelo de telefone	`phone-model-detection`	500
Consulta HLR	`hlr-lookup`	2000

Exemplos Completos

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

1. Consultar saldo

bash

curl -X GET "https://api.zelnum.com/api/v1/balance" \
  -H "X-API-Key: YOUR_KEY_HERE"

2. Enviar detecção

bash

curl -X POST "https://api.zelnum.com/api/v1/detect" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "YOUR_PRODUCT_SLUG",
    "country": "CN",
    "phones": ["+8613800138000", "+8613900139000"]
  }'

3. Enviar arquivo

bash

curl -X POST "https://api.zelnum.com/api/v1/detect/file" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -F "product=YOUR_PRODUCT_SLUG" \
  -F "country=CN" \
  -F "file=@/path/to/numbers.txt"

4. Consultar status da tarefa

bash

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v" \
  -H "X-API-Key: YOUR_KEY_HERE"

5. Obter URL de download

bash

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/result" \
  -H "X-API-Key: YOUR_KEY_HERE"