API de verificação de idade para sites e aplicativos

Passo um, verificar o número. Você chama POST /start-verification com flow=age e exibe o deep link do WhatsApp devolvido, como QR code no desktop ou botão no celular. O visitante envia uma mensagem já preenchida da própria conta de WhatsApp, então o controle do número é provado pelo ato de enviar, e não por um código que você tenha mandado para ele.

Passo dois, definir o limite. A mesma chamada aceita um min_age opcional. Sem ele vale o limite configurado na sua conta, que é 18 enquanto você não mudar. min_age só é aceito em flow=age e precisa ser um inteiro positivo; qualquer outra coisa volta como 400.

Passo três, concluir a checagem de idade. Assim que a metade do telefone é comprovada, a resposta traz um bloco age com status pending e uma age_verification_url. O visitante recebe esse mesmo link de uso único pelo WhatsApp, e você pode usá-lo para levá-lo adiante no navegador em que ele já está. Ele responde no provedor de idade e volta para a sua callback_url com token e age=verified, denied ou failed anexados.

Passo quatro, receber o resultado. Um segundo webhook, age_verification_result, dispara quando o provedor responde, e GET /check-verification-status informa a mesma coisa. O bloco age traz status, verified, required — o limite realmente checado —, verified_at e provider.

Vale conhecer uma armadilha antes de escrever o laço de polling. O status da própria sessão chega a verified assim que o número é comprovado, enquanto age.status ainda está em pending. Trate o bloco age como o sinal do passo de idade, nunca o status da sessão.

Os dois passos respondem a perguntas diferentes, e o fluxo os mantém separados de propósito. Enviar uma mensagem de WhatsApp prova que o visitante controla aquele número. Não diz absolutamente nada sobre a idade dele: um número de telefone não é prova de idade, e nenhuma parte deste fluxo o trata como tal.

O que o passo do telefone traz é um lugar para pôr a resposta. Um resultado de idade sozinho é um fato sem âncora — alguém, em algum lugar, passou de um limite. Ligado a um número que o visitante acabou de usar de forma demonstrável, vira algo que você reconhece na próxima visita.

Isso também barateia o visitante recorrente. Um resultado positivo é guardado por um ano junto ao número, então quem já passou do mesmo limite comprova o número de novo e carrega a resposta anterior em vez de voltar ao provedor. Terminar a mensagem de WhatsApp com #reset ignora esse cache quando você precisa de uma resposta nova.

A pergunta que uma checagem de idade faz é um booleano. A maior parte dos dados normalmente coletados para respondê-la não é, e é isso que torna o arquivo de documentos um péssimo negócio: você acaba guardando passaportes e carteiras de motorista para armazenar um sim.

O que o seu aplicativo precisa é pouco. O resultado — verified, denied, failed ou ainda pending. O limite checado. Quando foi respondido e qual provedor respondeu. O identificador da sessão e o número verificado, que ligam a resposta ao visitante à sua frente. É todo o bloco age, mais o que o fluxo do telefone já devolve.

O que o seu aplicativo não precisa é de data de nascimento nem de documento de identidade, e a API não devolve nenhum dos dois, então não há campo para registrar por acidente. Uma resposta positiva é guardada junto ao número como a resposta, o limite e a data. As credenciais do provedor ficam em segredos do lado do servidor, e o que o provedor precisou olhar para decidir não é repassado a você.

Nada disso diz o que quer que seja sobre as suas próprias obrigações. O que você precisa checar, por quanto tempo precisa poder comprovar que checou e o que conta como método aceitável são perguntas para o seu jurídico e o seu regulador, não para um fornecedor de API.

A verificação de idade responde a uma pergunta: este visitante atinge o limite de idade que você definiu? A verificação de identidade responde a outra: quem é esta pessoa? As duas costumam ser vendidas juntas e movem quantidades de dados muito diferentes.

flow=age é do primeiro tipo. Não devolve nome, nem data de nascimento, nem nada vindo de um documento. Não é KYC, e um resultado positivo não é uma afirmação de identidade em que você possa se apoiar em outro lugar. Se a sua obrigação é saber quem é o cliente, esta não é a ferramenta para essa parte.

Ele também herda a suposição que existe sob toda checagem baseada em telefone: a de que o número pertence a quem o está usando. Provar o controle enviando uma mensagem é terreno mais firme do que receber um SMS, mas um adolescente com acesso ao telefone de um adulto é um cenário que nenhuma checagem remota fecha por completo. O artigo sobre checagens de idade que não viram um banco de documentos, no link abaixo, detalha a arquitetura, os quatro estados e os limites.