Consulta de operadora e portabilidade antes de enviar o código
O lookup de operadora (HLR lookup) responde, sem tocar no telefone do usuário, em qual operadora um número está, se ele foi portado e qual a situação da linha segundo a rede. No ProValidPhone ele é uma camada antifraude entre a validação estrutural e o OTP: você decide se vale gastar um envio de SMS ou ligação, e com que regra, antes de enviar.
Ver a referência de POST /v1/lookup Criar conta
Em ativação. O endpoint POST /v1/lookup já existe na API e o escopo lookup já pode ser marcado na sua API key, mas a consulta ao provedor ainda está sendo habilitada para o Brasil: até lá a API responde 503 lookup_indisponivel. O preço do lookup ainda não foi definido e será publicado na página de preços antes da liberação. Validação e OTP não dependem dele.
O que é consulta de operadora (HLR lookup)
Toda linha móvel está registrada na base da sua operadora (o HLR, Home Location Register, ou o equivalente nas redes atuais). Um number lookup consulta essa base, por meio de um provedor de sinalização, e devolve o que a rede sabe sobre o número: a operadora atual, se houve portabilidade e se a linha está alcançável. Nada é enviado ao usuário e ele não percebe a consulta.
Validar
Olha só o formato: DDD, quantidade de dígitos, celular ou fixo, E.164. Regras locais, instantâneo, sem custo de envio. No ProValidPhone é POST /v1/validate.
Consultar (lookup)
Pergunta à rede: operadora atual, portabilidade e situação da linha. Não prova posse, mas diz se existe uma linha ativa do outro lado. É POST /v1/lookup.
Verificar (OTP)
Prova que a pessoa controla o número: envia um código por SMS ou ligação e confere. É a única camada que gera custo de envio. São /v1/verify/sms, /call e /check.
Para que serve contra fraude
O ponto do lookup é tomar a decisão de enviar com mais informação, antes de o envio existir. Alguns usos práticos:
- Não gastar envio com linha inativa. Em ataques de SMS pumping, parte dos números-alvo não tem uma linha real atrás. Se o provedor reporta a linha como não alcançável, você pode recusar o envio, sem consumir a franquia nem pagar SMS.
- Tratar número portado com regra própria. Portabilidade é legítima e comum, mas em operações sensíveis (troca de senha, alteração de chave de pagamento) você pode exigir um passo extra ou preferir a ligação com voz quando
portedviertrue. - Saber a operadora antes de escolher o canal. Se o seu histórico mostra que o SMS chega pior em determinada operadora, ofereça a ligação como padrão para ela em vez de descobrir isso depois do código não chegar.
- Enriquecer o cadastro sem pedir nada ao usuário. Operadora e portabilidade viram atributos do seu modelo de risco, junto com IP, dispositivo e comportamento, tudo do seu lado.
O que o lookup não faz: não prova que a pessoa que digitou o número o controla (isso é o OTP), não devolve nome do titular nem dados cadastrais e não substitui os limites por número e por conta que continuam valendo em cada envio.
Como o ProValidPhone faz
Um endpoint, sob demanda, com escopo próprio. A consulta só acontece quando você chama POST /v1/lookup; ela valida o número, consulta o provedor externo e devolve um contrato normalizado (o formato do provedor nunca é repassado).
- Opt-in por chave: ao criar a API key no painel, marque o escopo
lookup. Uma chave sem esse escopo recebe403 escopo. - Sem envio, sem cota: nada chega ao telefone e a consulta não desconta da franquia de verificações por SMS e voz.
- Fail-safe: se o provedor não responder ou recusar, a API devolve
502 falha_lookup; se o recurso não estiver habilitado na plataforma,503 lookup_indisponivel. Validação e OTP seguem funcionando. - Validação incluída: a resposta traz também
valid,e164,typeeddd, como em/v1/validate. Número inválido volta400 phone_invalidoantes de qualquer consulta.
# 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"}' # resposta 200 { "valid": true, "phone": "(11) 99999-8888", "e164": "+5511999998888", "type": "movel", "ddd": "11", "carrier": "Vivo", "ported": true, "original_carrier": "Claro", "line_status": "delivered" }
| Campo | O que significa |
|---|---|
carrier | Operadora atual do número. Vem vazio quando o provedor não informa. |
ported | true se o número foi portado de outra operadora. |
original_carrier | Operadora de origem, preenchida só quando ported é true. |
line_status | Situação da linha reportada pelo provedor, por exemplo delivered (linha alcançável) ou undeliverable. |
Onde o lookup entra no fluxo
POST /v1/validate assim que o usuário digita. Formato errado é recusado na hora, sem custo.
POST /v1/lookup nos fluxos que justificam: cadastro com risco, operação sensível, canal em dúvida. Sua regra decide o que fazer com a resposta.
/v1/verify/sms ou /v1/verify/call, com os limites por número e por conta de sempre.
POST /v1/verify/check confirma a posse. Webhooks assinados avisam o desfecho.
Perguntas frequentes sobre consulta de operadora
O que é consulta de operadora (number lookup ou HLR lookup)?
É uma consulta à base da operadora, feita por um provedor de sinalização, que devolve o que a rede sabe sobre um número: a operadora atual, se ele foi portado e se a linha está alcançável. Nada é enviado ao telefone e o usuário não percebe a consulta.
Qual a diferença entre validar, consultar e verificar um telefone?
Validar olha só o formato (DDD, dígitos, celular ou fixo). Consultar (lookup) pergunta à rede a operadora, a portabilidade e a situação da linha, sem provar posse. Verificar (OTP) envia um código por SMS ou ligação e confere, provando que a pessoa controla o número. No ProValidPhone são, respectivamente, /v1/validate, /v1/lookup e /v1/verify.
Como o lookup ajuda contra fraude?
Ele permite decidir antes de gastar um envio: recusar o código quando a linha é reportada como não alcançável (comum em SMS pumping), aplicar uma regra extra ou preferir a ligação com voz quando o número foi portado, escolher o canal conforme a operadora e alimentar o seu modelo de risco com esses atributos. Ele não substitui o OTP nem os limites por número e por conta.
O que a API POST /v1/lookup devolve?
Os campos da validação estrutural (valid, phone, e164, type, ddd) mais carrier (operadora atual), ported (se foi portado), original_carrier (operadora de origem, quando portado) e line_status (situação da linha reportada pelo provedor, como delivered ou undeliverable). O formato do provedor nunca é repassado; a resposta é sempre esse contrato.
O lookup consome a franquia de verificações? Quanto custa?
O lookup não desconta da franquia de verificações por SMS e voz. O preço do lookup ainda não foi definido: pode entrar na franquia ou ser cobrado à parte, e será publicado na página de preços antes da liberação do recurso.
O lookup já está disponível?
Está em ativação. O endpoint POST /v1/lookup já existe na API e o escopo lookup já pode ser marcado na chave, mas a consulta ao provedor ainda está sendo habilitada para o Brasil. Até lá a API responde 503 lookup_indisponivel; trate o lookup como enriquecimento opcional e siga com validação e OTP.
Como habilito o lookup na minha conta?
Ao criar uma API key no painel, marque o escopo lookup (ao lado de validate, sms e call). Chaves sem esse escopo recebem 403 escopo ao chamar /v1/lookup. Recomendamos uma chave separada para o lookup, com só esse escopo, no serviço que toma a decisão de risco.
Decida antes de enviar
Crie a conta, marque o escopo lookup na API key e integre o lookup ao seu fluxo de verificação.