1. Começo Rápido (API REST)
Você só precisa de uma requisição HTTP autenticada para iniciar uma verificação completa.
Obtenha sua API Key no Painel
Crie sua conta em /signup (self-serve, sem burocracia comercial). Sua chave de acesso (jano_live_…) será exibida uma única vez. Guarde-a com segurança em variáveis de ambiente (UAIID_API_KEY).
Authorization: Bearer jano_live_SUA_CHAVE_AQUI
Content-Type: application/jsonCriar a Sessão de Verificação
O campo cpf é o único identificador obrigatório. Você também pode enviar full_name e birth_date para conferência cadastral, ou deixar vazio no modo extração-first (o OCR do documento preenche o seu cadastro). O parâmetro flow: "own" aciona o motor proprietário Uai ID.
curl -X POST https://uaiid.com.br/v1/verifications \
-H "Authorization: Bearer jano_live_SUA_KEY" \
-H "Content-Type: application/json" \
-d '{
"cpf": "12345678909",
"flow": "own"
}'{
"verification_id": "23923d24-9c1f-4b7e-a2d3-8f6b41c2e77a",
"session_token": "st_5f2c…",
"verify_url": "https://uaiid.com.br/verify/ab12cd34",
"expires_at": "2026-09-10T01:23:45Z"
}verify_url para o candidato (via SMS, WhatsApp, e-mail ou WebView no seu app). As fotos do documento e a selfie biométrica sobem diretamente do dispositivo para o S3 criptografado via URLs pré-assinadas, sem sobrecarregar sua infraestrutura.Receber o Veredito em Tempo Real
O seu backend é notificado automaticamente via Webhook assinado com o score final e dados extraídos. Adicionalmente, seu app cliente pode consultar o status através do endpoint:
curl -X GET https://uaiid.com.br/v1/verifications/23923d24-9c1f-4b7e-a2d3-8f6b41c2e77a \
-H "Authorization: Bearer jano_live_SUA_KEY"2. SDK Flutter (uaiid_kyc)
Adicione prova de vida e captura guiada com oval holográfico no seu aplicativo Flutter com menos de 10 linhas de código.
// 1. pubspec.yaml
// dependencies:
// uaiid_kyc: ^0.3.0
// 2. AndroidManifest.xml
// <uses-permission android:name="android.permission.INTERNET"/>
// <uses-permission android:name="android.permission.CAMERA"/>
// 3. iOS Info.plist
// <key>NSCameraUsageDescription</key>
// <string>Prova de vida facial para verificação de identidade</string>
// 4. No seu app:
final kyc = UaiIdClient(
apiKey: 'jano_live_…',
baseUrl: 'https://uaiid.com.br',
);
final sess = await kyc.create(cpf: '12345678909');
final decision = await Navigator.push<UaiDecision>(context,
MaterialPageRoute(builder: (_) =>
UaiKycPage(session: sess, client: kyc)));
if (decision.isApproved) liberarUsuario();Ideal para protótipos e lançamentos rápidos. O resultado chega na entidade UaiDecision com o friendlyReason pronto para ser renderizado na UI do seu usuário.
// Seu BACKEND cria a sessão (a key fica SÓ lá) e entrega
// 3 campos ao app: verification_id · verify_url · session_token
final decision = await Navigator.push<UaiDecision>(context,
MaterialPageRoute(builder: (_) => UaiKycPage(session: sess)));
// O SDK acompanha o resultado pelo TOKEN DA SESSÃO —
// nenhuma credencial da sua empresa no aparelho.
// O score completo chega no seu backend via webhook assinado.Máxima segurança institucional: o seu backend cria a sessão e repassa apenas o session_token temporário. Nenhuma chave mestra fica exposta a descompilação de APK/IPA.
3. O Contrato JSON de Decisão
O mesmo esquema estruturado é entregue na API REST, no SDK Flutter e nos Webhooks.
Dicionário de Campos
approved, manual_review ou rejected.liveness_fail).document, liveness e face_match.{
"verification_id": "23923d24-9c1f-4b7e-a2d3-8f6b41c2e77a",
"status": "approved",
"score": 830,
"reason_code": null,
"face_similarity": 0.9562,
"extracted": {
"full_name": "MARIA DA SILVA",
"birth_date": "1990-01-01",
"doc_type": "cnh",
"document_number": "01234567890"
},
"checks": {
"document": "valid",
"liveness": "passed",
"face_match": "passed"
},
"identity_id": "id_8829f0a21",
"completed_at": "2026-09-09T01:02:03Z"
}4. O que fazer com cada Status
Diretrizes de arquitetura para o comportamento do seu aplicativo e do seu servidor.
| Status | Significado | No seu App Mobile | No seu Backend |
|---|---|---|---|
| approved | Documento autêntico + prova de vida validada + biometria facial confirmada. | Libera o usuário na hora (ativação da conta ou aprovação de crédito). | Valida a assinatura do Webhook e grava a liberação no banco de dados. |
| manual_review | Zona intermediária (ex: foto com reflexo ou doc antigo). Encaminhado à mesa de análise. | Exibe mensagem amigável: "Documentos em análise manual. Você receberá aviso em breve." | Mantém a conta em pendência sem reprovar; aguarda evento verification.approved. |
| rejected | Inconclusivo ou inconsistente: face divergente, fraude confirmada ou documento vencido. | Exibe o motivo explicativo (friendlyReason) e botão para refazer. | Aplica cooldown inteligente da API (4h para mesma biometria) para conter investidas maliciosas. |
5. Catálogo de reason_code
Quando o status não é approved, a API fornece o código exato da causa.
| reason_code | Descrição Técnica | Ação Sugerida |
|---|---|---|
face_mismatch | Similaridade facial abaixo do limiar estrito — indivíduos diferentes. | Bloquear operação e permitir nova tentativa com captura mais nítida. |
face_mismatch_review | Similaridade em faixa cinzenta limítrofe (iluminação deficitária ou pose angular). | Encaminhado automaticamente para conferência humana no dashboard. |
liveness_fail | Falha na prova de vida (foto de tela, máscara ou foto impressa detectada). | Bloquear tentativa; solicitar nova selfie em ambiente bem iluminado. |
data_mismatch_name / data_mismatch_cpf | Dados digitados pelo usuário divergem do texto impresso no documento oficial. | Permitir que o usuário confira os dados cadastrais antes de prosseguir. |
document_expired | Documento de identificação fora da validade legal ou emitido há mais de 10 anos. | Orientar o envio de via digital atualizada (CNH Digital ou RG novo). |
document_not_recognized | Imagem capturada não condiz com modelos aceitos de CNH, RG ou RNE/CRNM. | Instruir o candidato a posicionar o documento original sem reflexos. |
fraud_confirmed | Biometria ou CPF sinalizados em consórcio antifraude da rede Uai ID. | Bloqueio preventivo definitivo de acesso à plataforma. |
6. Webhooks com Prova Criptográfica
Receba notificações imediatas assim que uma decisão for consolidada pelo motor sovereign.
Eventos Disponíveis
X-Uai-Signature: t=1694123456,v1=5d41402abc4b...Utilize seu WEBHOOK_SECRET cadastrado no painel para computar o HMAC SHA-256 e blindar seu endpoint contra adulterações e ataques de repetição.
// Node.js — SEMPRE confira a assinatura antes de confiar no corpo
import crypto from "crypto";
function verifyWebhookSignature(rawBody, signatureHeader, secret) {
// Header: "t=1694123456,v1=5d41402abc4b2a76b9719d911017c592..."
const parts = Object.fromEntries(
signatureHeader.split(",").map((p) => p.split("="))
);
const t = parseInt(parts.t, 10);
const sig = parts.v1;
// Tolerância de 5 minutos contra replay attacks
if (Math.abs(Date.now() / 1000 - t) > 300) {
throw new Error("Assinatura expirada (possível replay attack)");
}
const expected = "v1=" + crypto
.createHmac("sha256", secret)
.update(`${t}.${rawBody}`)
.digest("hex");
if (expected !== `v1=${sig}`) {
throw new Error("Assinatura inválida: payload adulterado");
}
return true;
}7. Códigos de Erro HTTP
A API responde com códigos de status HTTP semânticos e mensagens de erro estruturadas.
| Código | Quando Ocorre | Como Tratar |
|---|---|---|
| 401 Unauthorized | API key ausente, expirada ou inválida para o ambiente. | Verifique a variável de ambiente no seu servidor; não realize retentativas em loop. |
| 402 Payment Required | Limite de créditos para homologação atingido (proteção anti-surpresa). | Acesse o painel para recarregar créditos pré-pagos ou alterar plano. |
| 404 Not Found | Identificador de verificação não encontrado para este tenant. | Verifique se o UUID da sessão pertence à sua organização e ambiente correto. |
| 409 Conflict | Tentativa de submissão em sessão que já foi previamente finalizada. | Recupere o estado final via GET /v1/verifications/{id}. |
| 429 Too Many Requests | Rate limit excedido ou cooldown de 4h ativo para contenção de fraude. | Implemente backoff exponencial com jitter aleatório; aguarde o cabeçalho Retry-After. |
8. LGPD e Arquitetura de Dados
Projetado desde o primeiro dia de acordo com as exigências da Lei Geral de Proteção de Dados (Lei 13.709/2018).
Biometria como Dado Sensível
Enquadramento estrito nos Artigos 7º e 11 da LGPD. Vetores e embeddings faciais contam com isolamento lógico de banco de dados e controle estrito de RBAC.
Criptografia SSE-KMS & AES-256
Fotos de documentos e evidências de liveness trafegam via HTTPS TLS 1.3 e repousam criptografadas em storage soberano brasileiro com rotação contínua de chaves.
Princípio da Minimização
Dados cadastrais de consulta transitória nunca são utilizados para finalidades secundárias ou comercializados para terceiros.
Soberania Nacional
Diferente de soluções gringas que enviam biometria de brasileiros para servidores no exterior, o Uai ID processa e retém evidências em solo nacional.
