Documentação da API ProValidPhone v1
Endpoints REST em JSON para validar números brasileiros, confirmar posse por código OTP via SMS ou ligação com voz e, opcionalmente, consultar operadora e portabilidade. Base: https://api.provalidphone.com.br. Todas as respostas são JSON em UTF-8. Especificação OpenAPI 3 para Postman e geradores de SDK: https://api.provalidphone.com.br/v1/openapi.json · referência interativa em https://api.provalidphone.com.br/v1/docs/.
Versão da API: v1. Última atualização desta página: 29 de setembro de 2026.
Autenticação
Toda chamada exige uma API key criada no painel. A chave crua (pvp_live_…) é exibida uma única vez na criação; a plataforma guarda apenas o hash SHA-256. Envie a chave em um dos dois headers:
Authorization: Bearer pvp_live_SUACHAVE
# ou
X-API-Key: pvp_live_SUACHAVE
Chave ausente, inválida ou revogada devolve 403 com um campo detail (sem o campo error das demais falhas):
# 403: sem header de autenticação { "detail": "As credenciais de autenticação não foram fornecidas." } # 403: chave inválida ou revogada { "detail": "API key invalida ou revogada." }
Cada API key pode ter um nome de projeto (remetente), que aparece no texto do SMS e é repassado ao serviço de voz para a locução da ligação.
Escopos: ao criar a chave você escolhe o que ela pode fazer — validate (validar número), sms (enviar código por SMS), call (enviar código por ligação) e lookup (consultar operadora e portabilidade, em ativação); o padrão é todos. Uma chave sem o escopo do endpoint recebe 403 escopo. Crie chaves separadas por projeto ou ambiente e dê a cada uma só o que precisa.
Saúde da API: GET /v1/health não exige autenticação e devolve { "status": "ok" } — use no seu monitor de disponibilidade.
Validação estrutural
POST /v1/validate
Normaliza e valida um número brasileiro sem enviar nada ao telefone. Não consome cota. Aceita o número como o usuário digitou: com ou sem parênteses, traço, espaço, DDI.
# requisição curl -X POST https://api.provalidphone.com.br/v1/validate \ -H "Authorization: Bearer pvp_live_SUACHAVE" \ -H "Content-Type: application/json" \ -d '{"phone":"(11) 99999-8888"}' # resposta 200 { "valid": true, "phone": "(11) 99999-8888", "e164": "+5511999998888", "type": "movel", "ddd": "11", "errors": [] }
type é movel ou fixo. Quando valid é false, errors traz a lista de motivos em português (por exemplo, DDD inválido ou comprimento incorreto), type vem desconhecido e e164 vem null. Números especiais (0800, 0300, 3003, 4004, 190, 192, 193…) voltam com valid false e type especial: são reconhecidos, mas não recebem SMS nem ligação de verificação.
Envio do código (SMS ou voz)
POST /v1/verify/sms e POST /v1/verify/call
Valida o número, gera um código de 6 dígitos e o envia por SMS (/sms) ou por uma ligação que dita o código em voz (/call). Cria uma sessão de verificação e devolve o id para a conferência. Consome 1 verificação da cota quando o provedor aceita o envio.
# SMS: requisição curl -X POST https://api.provalidphone.com.br/v1/verify/sms \ -H "Authorization: Bearer pvp_live_SUACHAVE" \ -H "Content-Type: application/json" \ -d '{"phone":"+5511999998888"}' # SMS: resposta 201 { "id": "3f6c1c2e-9a1b-4d0e-8f7a-2b5c9d1e4a77", "status": "pending", "channel": "sms", "phone": "+5511999998888" }
# Ligação com voz: mesmo corpo, outro caminho curl -X POST https://api.provalidphone.com.br/v1/verify/call \ -H "Authorization: Bearer pvp_live_SUACHAVE" \ -H "Content-Type: application/json" \ -d '{"phone":"+551132210000"}' # Ligação com voz: resposta 201 { "id": "8a2d5f10-4c7e-4b39-9e61-0d3f7c2a9b54", "status": "pending", "channel": "call", "phone": "+551132210000" }
Texto do SMS: {Nome do projeto} enviou o codigo: 123456. Na ligação, o nome do projeto é falado e o código é ditado dígito a dígito. O canal de voz aceita celular e telefone fixo. As ligações saem uma por vez: se a linha estiver em uso, a verificação entra numa fila curta e a resposta continua sendo 201 (a ligação sai em seguida, dentro da validade do código). Com a fila cheia, a resposta é 503 canal_ocupado.
# 400: número reprovado na validação estrutural (nada é enviado)
{
"error": "phone_invalido",
"errors": ["DDD invalido: 00"]
}
Idempotência: envie o header Idempotency-Key (até 255 caracteres, por exemplo o id do pedido no seu sistema) para reenviar a requisição com segurança em caso de timeout. Com a mesma chave, por 24 horas, a API devolve a mesma resposta e a mesma sessão, com o header Idempotent-Replayed: true, sem enviar outro código. Falhas 5xx não ficam guardadas: com a mesma chave, a nova tentativa envia de novo.
curl -X POST https://api.provalidphone.com.br/v1/verify/sms \
-H "Authorization: Bearer pvp_live_SUACHAVE" \
-H "Idempotency-Key: pedido-48213" \
-H "Content-Type: application/json" \
-d '{"phone":"+5511999998888"}'
Código fornecido por você (opcional): se o seu sistema já gera o código (por exemplo, um bot que é o dono do código), envie "code" com exatamente 6 dígitos. Entregamos esse código em vez de gerar um; os limites por hora, a validade de 5 minutos e a conferência por sessão (/v1/verify/check) continuam iguais. Um code fora do formato é recusado com 400 codigo_invalido, antes de qualquer envio. O código nunca fica guardado em texto: só o hash.
# requisição com código fornecido curl -X POST https://api.provalidphone.com.br/v1/verify/sms \ -H "Authorization: Bearer pvp_live_SUACHAVE" \ -H "Content-Type: application/json" \ -d '{"phone":"+5511999998888","code":"482715"}' # resposta 201 (mesmo formato de sempre) { "id": "5b1e0c7a-2f4d-4a8e-9c31-6d2b8f0e1a93", "status": "pending", "channel": "sms", "phone": "+5511999998888" } # 400: code fora do formato (nada é enviado) { "error": "codigo_invalido", "detail": "code deve ter exatamente 6 dígitos." }
A API abstrai os provedores. As respostas dos gateways de SMS e de voz nunca são repassadas ao cliente. Sucesso é sempre { id, status, channel, phone }; falha é sempre { error, detail } com um motivo abstrato, como falha_envio (502, o provedor não aceitou o envio) ou canal_indisponivel (503). A resposta crua do gateway (porta indisponível, erro de rota, etc.) fica apenas nos registros do servidor.
Conferência do código
POST /v1/verify/check
Confere o código digitado pelo usuário para a sessão informada. Não consome cota. Ao acertar, a sessão passa a verified e não aceita novas conferências.
# requisição curl -X POST https://api.provalidphone.com.br/v1/verify/check \ -H "Authorization: Bearer pvp_live_SUACHAVE" \ -H "Content-Type: application/json" \ -d '{"id":"3f6c1c2e-9a1b-4d0e-8f7a-2b5c9d1e4a77","code":"123456"}' # resposta 200 { "id": "3f6c1c2e-9a1b-4d0e-8f7a-2b5c9d1e4a77", "valid": true, "status": "verified" }
Valores de status: pending (aguardando), verified (confirmado), failed (tentativas esgotadas) e expired (prazo vencido). Sessões só são visíveis para a conta que as criou; id desconhecido devolve 404.
Status da verificação de um número
GET /v1/verify/status?phone=
Devolve a última verificação daquele número na sua conta, venha ela da sua integração (origin: "api") ou de uma pessoa da sua equipe que enviou o código pelo painel (origin: "painel"). Serve para manter "telefone verificado" em sincronia no seu sistema mesmo quando alguém validou pelo painel. Não consome cota. Só enxerga verificações da conta da API key; conta apenas envios que de fato saíram (ou ligações na fila).
# requisição (o número pode ir em qualquer formato; use URL-encode no "+") curl -G https://api.provalidphone.com.br/v1/verify/status \ -H "Authorization: Bearer pvp_live_SUACHAVE" \ --data-urlencode "phone=+5511999998888" # resposta 200 { "id": "3f6c1c2e-9a1b-4d0e-8f7a-2b5c9d1e4a77", "phone": "+5511999998888", "status": "verified", "channel": "sms", "origin": "painel", "created_at": "2026-09-29T10:12:40-03:00", "verified_at": "2026-09-29T10:13:05-03:00", "expires_at": "2026-09-29T10:17:40-03:00" } # 404: a conta nunca verificou este número { "error": "sem_verificacao", "detail": "Nenhuma verificação deste número nesta conta." }
status: verified, pending (aguardando o código), expired (prazo vencido sem conferência) ou failed (tentativas esgotadas). Para receber o desfecho sem consultar, use os webhooks, que também trazem origin. A chave precisa poder enviar códigos (escopo SMS ou voz).
Lookup de operadora e portabilidade (opcional, em ativação)
Em ativação. O endpoint já existe e o escopo lookup já pode ser marcado na chave, mas a consulta ao provedor ainda está sendo habilitada para o Brasil: até lá POST /v1/lookup responde 503 lookup_indisponivel para todas as contas. Integre já tratando esse status como recurso opcional. O preço do lookup ainda não foi definido e será publicado em preços antes da liberação. Contexto e usos antifraude na página do lookup.
POST /v1/lookup valida o número e consulta, em um provedor externo de HLR, a operadora atual, se o número foi portado (e de qual operadora veio) e a situação da linha. É sob demanda: só acontece quando você chama, e exige que a API key tenha o escopo lookup (marque ao criar a chave; sem ele, 403 escopo). Não envia nada ao usuário e não consome cota de verificação. A resposta do provedor nunca é repassada: o contrato abaixo é o único formato devolvido.
# requisição
curl -X POST https://api.provalidphone.com.br/v1/lookup \
-H "Authorization: Bearer pvp_live_SUACHAVE" \
-H "Content-Type: application/json" \
-d '{"phone":"(11) 99999-8888"}'
# 200 OK
{
"valid": true,
"phone": "(11) 99999-8888",
"e164": "+5511999998888",
"type": "movel",
"ddd": "11",
"carrier": "Vivo",
"ported": true,
"original_carrier": "Claro",
"line_status": "delivered"
}
# 400: número reprovado na validação estrutural (nenhuma consulta é feita)
{ "error": "phone_invalido", "errors": ["DDD invalido: 00"] }
# 403: a API key não tem o escopo lookup
{ "error": "escopo", "detail": "Esta API key nao tem permissao para este endpoint." }
# 503: consulta de operadora não habilitada na plataforma
{ "error": "lookup_indisponivel", "detail": "Consulta de operadora indisponivel no momento." }
# 502: o provedor não respondeu ou recusou a consulta
{ "error": "falha_lookup", "detail": "O provedor de lookup nao respondeu. Tente novamente." }
Campos: valid, phone, e164, type e ddd como em /v1/validate; carrier (operadora atual; vazio quando o provedor não informa), ported, original_carrier (só quando portado) e line_status (situação reportada pelo provedor, por exemplo delivered para linha alcançável ou undeliverable). Número inválido devolve 400 phone_invalido antes de qualquer consulta; sem provedor habilitado na plataforma, 503 lookup_indisponivel; falha ou recusa do provedor, 502 falha_lookup. O limite geral de requisições por conta (120 por minuto) vale também aqui. Trate o lookup como enriquecimento opcional: validação e OTP funcionam sem ele.
Códigos de erro
| HTTP | error | Quando acontece | O que fazer |
|---|---|---|---|
| 400 | phone_invalido | O número não passou na validação estrutural; o corpo traz errors com os motivos | Mostrar os motivos de errors ao usuário e pedir correção |
| 400 | codigo_invalido | O campo opcional code não tem exatamente 6 dígitos numéricos. Nada é enviado | Mandar 6 dígitos ou omitir o code para gerarmos |
| 400 | canal_incompativel | Pedido de SMS para um número que não é celular (fixo não recebe SMS). Recusado antes do envio, sem consumir cota | Usar /v1/verify/call para telefone fixo |
| 403 | (sem error; só detail) | API key ausente, inválida ou revogada | Conferir o header e a chave no painel |
| 402 | cota | Cota mensal de verificações atingida | Aguardar a próxima competência ou ampliar o plano |
| 402 | trial | Período de teste encerrado sem plano ativo | Contratar um plano de produção |
| 403 | suspensa | Conta suspensa | Entrar em contato com o suporte |
| 403 | cadastro | Cadastro da conta incompleto (falta confirmar os dados de pagamento); vale para todos os envios da conta | Concluir o cadastro no painel; a validação estrutural segue funcionando |
| 403 | escopo | A API key não tem permissão para este endpoint (escopos definidos ao criar a chave) | Usar uma chave com o escopo certo ou criar outra no painel |
| 404 | sessao_nao_encontrada | id inexistente ou de outra conta | Conferir o id devolvido no envio |
| 404 | sem_verificacao | /v1/verify/status: a conta nunca verificou esse número | Tratar como não verificado |
| 409 | idempotencia_em_andamento | Outra requisição com a mesma Idempotency-Key ainda está sendo processada | Aguardar alguns segundos e repetir |
| 422 | idempotencia_conflito | A Idempotency-Key já foi usada com outro número ou canal | Gerar uma chave nova para cada verificação |
| 422 | gateway | O número de destino não pode receber verificação (é uma linha da própria infraestrutura de envio) | Usar um telefone real do usuário final; o bloqueio acontece antes do envio |
| 502 | falha_lookup | O provedor de lookup não respondeu ou recusou a consulta (só em /v1/lookup) | Tentar novamente; a validação estrutural continua disponível |
| 503 | lookup_indisponivel | Consulta de operadora não está habilitada na plataforma no momento (só em /v1/lookup) | Tratar como recurso opcional: seguir com validação e OTP normalmente |
| 429 | limite | Mais de 3 envios na última hora para o mesmo número no mesmo canal | Aguardar antes de reenviar; oferecer o outro canal |
| 429 | rate_limit | Muitas requisições da conta em pouco tempo; o corpo traz retry_after (segundos) e há o header Retry-After | Esperar retry_after e repetir, sem loop |
| 502 | falha_envio | O provedor não aceitou o SMS ou a ligação (o motivo técnico fica só no servidor) | Tentar novamente ou usar o outro canal |
| 503 | canal_indisponivel | Canal (SMS ou voz) desativado no momento | Usar o outro canal e tentar mais tarde |
| 503 | canal_ocupado | Todas as linhas do canal estão ocupadas com outros envios (enviamos um por vez em cada linha) | Tentar de novo em alguns segundos ou usar o outro canal |
Formato das falhas de negócio: { "error": "cota", "detail": "Cota mensal atingida." }. Nos erros 402, 403 (conta suspensa), 429, 502 e 503 o campo id pode vir junto quando a sessão chegou a ser criada. Envios recusados por qualquer um desses motivos não consomem cota.
Limites e regras do código
| Regra | Valor padrão |
|---|---|
| Tamanho do código | 6 dígitos numéricos |
| Validade do código | 5 minutos a partir do envio |
| Tentativas de conferência por código | 5 |
| Envios por hora para o mesmo número | 3 em cada canal (SMS e voz contados separadamente; toda tentativa conta, mesmo com falha do provedor) |
| Requisições por conta | 120 por minuto no total; 30 por minuto em /v1/verify/sms e /v1/verify/call |
Guarda da Idempotency-Key | 24 horas |
| Cota mensal no período de teste | 100 verificações |
| Armazenamento do código | Apenas hash SHA-256; nunca em texto claro |
Webhooks de resultado
Cadastre uma URL https pública no painel (menu Webhooks) e receba um POST JSON a cada desfecho de verificação, sem precisar consultar a API. Eventos: verification.verified (código conferido), verification.failed (tentativas esgotadas), verification.expired (ninguém conferiu no prazo) e ping (botão "Enviar teste").
# corpo do POST
{
"event": "verification.verified",
"created_at": "2026-09-24T10:15:02-03:00",
"data": {
"id": "3f6c1c2e-9a1b-4d0e-8f7a-2b5c9d1e4a77",
"status": "verified",
"channel": "sms",
"phone": "+5511999998888",
"attempts": 1,
"origin": "api",
"verified_at": "2026-09-24T10:15:02-03:00"
}
}
origin diz quem pediu o código: api (sua integração) ou painel (uma pessoa da sua equipe). verified_at vem preenchido em verification.verified e é null nos demais eventos.
Assinatura: cada entrega traz X-ProValidPhone-Timestamp (Unix) e X-ProValidPhone-Signature: v1=<hex>, o HMAC-SHA256 de "{timestamp}.{corpo cru}" com o segredo do webhook (whsec_…, mostrado uma vez no painel). Recalcule e compare antes de confiar no conteúdo, e recuse timestamps com mais de 5 minutos.
# Python: conferir a assinatura
import hashlib, hmac, time
def assinatura_ok(corpo_cru: bytes, ts: str, assinatura: str, segredo: str) -> bool:
if abs(time.time() - int(ts)) > 300:
return False
esperado = hmac.new(segredo.encode(), f"{ts}.".encode() + corpo_cru, hashlib.sha256).hexdigest()
return hmac.compare_digest("v1=" + esperado, assinatura)
Entrega: qualquer resposta 2xx conta como recebida. Outras respostas, timeout ou erro de rede são repetidos até 5 vezes com espera crescente (1, 2, 4, 8 minutos…). Redirecionamentos não são seguidos. Cada POST traz também X-ProValidPhone-Event (nome do evento) e X-ProValidPhone-Delivery (id da entrega) — use o segundo para ignorar duplicatas. O histórico das entregas aparece no painel.
Exemplos em Python, Node e PHP
O fluxo completo (enviar o código e conferir) com a biblioteca HTTP padrão de cada linguagem. Troque pvp_live_SUACHAVE pela chave gerada no painel.
Python (requests)
import requests
BASE = "https://api.provalidphone.com.br"
HEADERS = {"Authorization": "Bearer pvp_live_SUACHAVE"}
# 1. enviar o código por SMS (use /v1/verify/call para ligação)
r = requests.post(f"{BASE}/v1/verify/sms", json={"phone": "+5511999998888"}, headers=HEADERS, timeout=15)
if r.status_code != 201:
erro = r.json() # {"error": "...", "detail": "..."} ou {"detail": "..."} no 403
raise RuntimeError(erro.get("error") or erro.get("detail"))
sessao_id = r.json()["id"]
# 2. conferir o código digitado pelo usuário
r = requests.post(f"{BASE}/v1/verify/check", json={"id": sessao_id, "code": "123456"}, headers=HEADERS, timeout=15)
resultado = r.json()
print(resultado["valid"], resultado["status"]) # True verified
Node.js (fetch nativo, 18+)
const BASE = "https://api.provalidphone.com.br";
const headers = {
"Authorization": "Bearer pvp_live_SUACHAVE",
"Content-Type": "application/json",
};
// 1. enviar o código por SMS (use /v1/verify/call para ligação)
const envio = await fetch(`${BASE}/v1/verify/sms`, {
method: "POST", headers, body: JSON.stringify({ phone: "+5511999998888" }),
});
const sessao = await envio.json();
if (envio.status !== 201) throw new Error(sessao.error || sessao.detail);
// 2. conferir o código digitado pelo usuário
const check = await fetch(`${BASE}/v1/verify/check`, {
method: "POST", headers, body: JSON.stringify({ id: sessao.id, code: "123456" }),
});
const resultado = await check.json();
console.log(resultado.valid, resultado.status); // true verified
PHP (cURL)
<?php
$base = "https://api.provalidphone.com.br";
$headers = ["Authorization: Bearer pvp_live_SUACHAVE", "Content-Type: application/json"];
function chamar(string $url, array $corpo, array $headers): array {
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_POSTFIELDS => json_encode($corpo),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
return [$status, $resposta];
}
// 1. enviar o código por SMS (use /v1/verify/call para ligação)
[$status, $sessao] = chamar("$base/v1/verify/sms", ["phone" => "+5511999998888"], $headers);
if ($status !== 201) {
throw new RuntimeException($sessao["error"] ?? $sessao["detail"]);
}
// 2. conferir o código digitado pelo usuário
[$status, $resultado] = chamar("$base/v1/verify/check", ["id" => $sessao["id"], "code" => "123456"], $headers);
var_dump($resultado["valid"], $resultado["status"]); // bool(true) "verified"
Fluxo recomendado de integração
- Chame
/v1/validateassim que o usuário digitar o número e mostre o erro na hora sevalidforfalse. Isso evita envio para número impossível. - Opcional (em ativação): nos fluxos de risco, chame
/v1/lookupantes do envio e aplique a sua regra (por exemplo, não enviar quandoline_statusindicar linha não alcançável). Trate502e503como "sem informação" e siga o fluxo normal. - Ofereça SMS como padrão e a ligação com voz como alternativa visível (útil para fixo e quando o SMS não chega).
- Guarde o
idda sessão no seu lado e mostre um campo de 6 dígitos com contagem de 5 minutos. - Em
/v1/verify/check, tratevalid: falsecomstatus: pendingcomo código errado (ainda há tentativas) efailedouexpiredcomo sessão encerrada, oferecendo novo envio. - Trate
429mostrando o tempo de espera e sugerindo o outro canal; nunca reenvie automaticamente em loop. - Persista o número em E.164 (campo
e164) para evitar duplicidade na sua base.