Verificação de maioridade

A máquina mostra um QR code, o app do cliente valida a maioridade do consumidor e o backend do cliente devolve o resultado à ETech. A ETech repassa o resultado à máquina.

O cliente implementa os passos 2 a 4: a validação no app e o envio do resultado pelo backend. Nesta frente a ETech não chama nenhuma API do cliente.

O deep link

O QR code da máquina abre o deep link que a organização cadastrou na ETech, com dois parâmetros acrescentados. Com um OneLink do AppsFlyer cadastrado, por exemplo, o QR code fica assim:

https://app.exemplo.com.br/Zx1q?deep_link_value=validacao-facial&verificationId=7c1e2a4b-0d3f-4e8a-9b21-5f6a7d8c9e01&document=12345678909

Parâmetro	Formato	O que é
verificationId	GUID	Identifica esta verificação e a máquina que a pediu
document	CPF, 11 dígitos, sem pontuação	O CPF que o consumidor digitou na máquina

• O verificationId tem de chegar intacto ao backend do cliente. É a única ligação entre o resultado e a máquina, e um valor alterado não encontra a verificação.
• Se o deep link cadastrado já tiver query, os dois parâmetros entram com & no fim dela.
• A verificação vale 10 minutos a partir do momento em que o QR code aparece na tela.

LGPD

O document é dado pessoal. Ele aparece no QR code nesta fase, e não deve ir para log nem para ferramenta de análise do app.

Enviar o resultado

O backend do cliente envia o resultado da validação em uma única chamada, com os headers de Acesso.

POST /integration/v1/legal-age-verifications/result
x-api-key: <api key>
Authorization: Bearer <access_token>
User-Agent: <nome-do-sistema>/<versão>
Content-Type: application/json

{
  "verificationId": "7c1e2a4b-0d3f-4e8a-9b21-5f6a7d8c9e01",
  "approved": true,
  "document": "12345678909",
  "validatedAt": "2026-10-21T14:03:11Z",
  "externalReference": "val-000123",
  "reason": null
}

Campo	Tipo	Obrigatório	Regra
verificationId	string (GUID)	sim	O valor recebido no deep link, sem alteração
approved	boolean	sim	true quando o consumidor é maior de idade
document	string, 11 dígitos	sim	O CPF validado pelo app. Tem de ser o mesmo do deep link
validatedAt	data e hora ISO 8601, UTC	sim	Quando a validação terminou. Não pode ser anterior à abertura nem estar no futuro
externalReference	string, até 100	não	Identificador da validação no sistema do cliente, para rastreio
reason	string, até 100	não	Motivo, quando approved é false

Resposta de sucesso, 200:

{ "verificationId": "7c1e2a4b-0d3f-4e8a-9b21-5f6a7d8c9e01", "status": "Approved" }

status é Approved ou Rejected, conforme o approved enviado.

Respostas e erros

Só 429, 5xx e falha de rede justificam reenviar o mesmo resultado. Os outros erros pedem correção ou encerram a verificação. Os erros de token, credencial e gateway estão em Acesso.

HTTP	Código	Quando acontece	O que fazer
200	—	Resultado aceito, ou o mesmo resultado reenviado	Nada
400	LEGAL_AGE_VERIFICATION.ID_REQUIRED	verificationId ausente ou fora do formato GUID	Corrigir o corpo
400	LEGAL_AGE_VERIFICATION.STALE_RESULT	validatedAt anterior à abertura ou no futuro	Conferir o relógio do servidor e o fuso (UTC)
400	validação de campo	Campo obrigatório ausente ou fora do formato	Corrigir o corpo
404	—	Verificação inexistente, ou de outra organização	Conferir se o verificationId veio intacto do deep link
409	LEGAL_AGE_VERIFICATION.ALREADY_DECIDED	Já existe um resultado diferente para essa verificação	Não reenviar; o primeiro resultado vale
410	LEGAL_AGE_VERIFICATION.EXPIRED	Passaram os 10 minutos de validade	Não reenviar; o consumidor abre outra verificação na máquina
422	LEGAL_AGE_VERIFICATION.DOCUMENT_MISMATCH	O document é diferente do CPF digitado na máquina	Não reenviar; o consumidor abre outra verificação

Regras de uso

• Reenvio sem risco: o mesmo resultado para a mesma verificação é aceito uma vez e repetido sem efeito novo.
• Validade: 10 minutos a partir do QR code. Depois disso, a verificação responde 410 e o consumidor precisa abrir outra na máquina.
• Reenvio: em timeout, 429 ou 5xx, reenvie o mesmo corpo com intervalo crescente (por exemplo 1 s, 2 s, 4 s), sem passar da validade.
• Um resultado por verificação. Depois do primeiro aceito, um resultado diferente é recusado com 409.