Documentação da API

Integre ZapValida em sua aplicação com nossa API REST completa

Autenticação
Todas as requisições devem incluir sua API Key no header Authorization

Authorization: Bearer sua_api_key_aqui

Você pode gerar API Keys na seção API Keys do dashboard

Endpoints

Validar Número Individual
POST /api/v1/validate

Valida um único número de telefone

curl -X POST https://api.zapvalida.com/api/v1/validate \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+5511999999999",
    "credential_id": "123"
  }'

Response:

{
  "validation_id": "123",
  "phone_number": "+5511999999999",
  "status": "sent",
  "is_valid": null,
  "created_at": "2026-02-23T10:30:00Z"
}
Validar Números em Lote
POST /api/v1/validate/bulk

Valida até 100 números de telefone em uma única requisição

curl -X POST https://api.zapvalida.com/api/v1/validate/bulk \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": [
      "+5511999999999",
      "+5511988888888",
      "+5511977777777"
    ],
    "credential_id": "123"
  }'

Response:

{
  "batch_id": "batch_123",
  "total_queued": 3,
  "limited": false,
  "status": "processing"
}
Verificar Uso
GET /api/v1/usage

Retorna informações sobre o uso mensal de validações

curl -X GET https://api.zapvalida.com/api/v1/usage \
  -H "Authorization: Bearer sk_live_..."

Response:

{
  "plan": "pro",
  "monthly_limit": 5000,
  "used_this_month": 1250,
  "remaining": 3750,
  "period_start": "2026-02-01T00:00:00Z",
  "period_end": "2026-02-28T23:59:59Z"
}

Webhooks

Registrar Webhook
POST /api/v1/webhooks

Registre uma URL para receber notificações de eventos

curl -X POST https://api.zapvalida.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-servidor.com/webhooks",
    "events": [
      "validation.success",
      "validation.failed",
      "limit.reached"
    ],
    "description": "Webhook para processar validações"
  }'

Eventos disponíveis:

  • • validation.success - Número validado com sucesso
  • • validation.failed - Validação falhou
  • • limit.reached - Limite mensal atingido
Payload de Webhook
Estrutura dos eventos enviados
{
  "event": "validation.success",
  "validation_id": "123",
  "phone_number": "+5511999999999",
  "is_valid": true,
  "status": "delivered",
  "timestamp": "2026-02-23T10:30:00Z"
}

Headers:
X-Webhook-Signature: sha256=abc123...
X-Webhook-ID: webhook_123
X-Webhook-Timestamp: 2026-02-23T10:30:00Z

Valide a assinatura HMAC-SHA256 usando o secret fornecido ao registrar o webhook

Rate Limits
Limites de requisições por plano
PlanoRequisições/minValidações/mês
Gratuito10100
Pro605.000
EnterpriseIlimitado50.000
Tratamento de Erros
Códigos de erro e mensagens

400 Bad Request

Parâmetros inválidos ou ausentes

401 Unauthorized

API Key ausente ou inválida

429 Too Many Requests

Limite de requisições atingido

500 Internal Server Error

Erro no servidor

Precisa de Ajuda?
Entre em contato com nosso time de suporte

Temos documentação completa, exemplos de código e suporte 24/7 para ajudá-lo