DOCUMENTAÇÃO OFICIAL · API REST · SDK FLUTTER · WEBHOOKS

Integre o Uai ID em uma tarde

Crie sessões de KYC, oriente seu usuário na captura biométrica sovereign e receba um contrato JSON determinístico no seu app, backend e webhook. Tudo pronto para produção em conformidade com a LGPD.

1. Começo Rápido (API REST)

Você só precisa de uma requisição HTTP autenticada para iniciar uma verificação completa.

01

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).

Header HTTP de Autenticação
http
Authorization: Bearer jano_live_SUA_CHAVE_AQUI
Content-Type: application/json
02

Criar 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 — Criar Verificação
bash
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"
  }'
Resposta 201 Created
json
{
  "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"
}
💡
Envie o 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.
03

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:

GET /v1/verifications/{id}
bash
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.

MODO A · RÁPIDOAPI Key direto no aplicativo móvel
App Flutter (Modo A)
dart
// 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.

MODO B · RECOMENDADOZero credenciais da empresa no aparelho
App Flutter (Modo B)
dart
// 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

status string
Veredito principal binário: approved, manual_review ou rejected.
score integer (0–1000)
Score de confiança agregada. Scores ≥ 700 habilitam revalidação rápida com custo reduzido.
reason_code string | null
Código padronizado explicando a causa quando não aprovado (ex: liveness_fail).
face_similarity float (0.00–1.00)
Similaridade cosseno entre o vetor facial da selfie viva e a foto do documento.
extracted object
Dados extraídos pelo OCR sovereign: nome completo, data de nascimento, CPF e número do espelho.
checks object
Checagens individuais para auditoria: document, liveness e face_match.
Payload JSON do Veredito
json
{
  "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.

StatusSignificadoNo seu App MobileNo seu Backend
approvedDocumento 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_reviewZona 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.
rejectedInconclusivo 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_codeDescrição TécnicaAção Sugerida
face_mismatchSimilaridade facial abaixo do limiar estrito — indivíduos diferentes.Bloquear operação e permitir nova tentativa com captura mais nítida.
face_mismatch_reviewSimilaridade em faixa cinzenta limítrofe (iluminação deficitária ou pose angular).Encaminhado automaticamente para conferência humana no dashboard.
liveness_failFalha 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_cpfDados digitados pelo usuário divergem do texto impresso no documento oficial.Permitir que o usuário confira os dados cadastrais antes de prosseguir.
document_expiredDocumento 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_recognizedImagem capturada não condiz com modelos aceitos de CNH, RG ou RNE/CRNM.Instruir o candidato a posicionar o documento original sem reflexos.
fraud_confirmedBiometria 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

verification.approvedDisparado no instante em que o candidato é 100% aprovado.
verification.rejectedDisparado quando a validação é rejeitada de forma conclusiva.
verification.manual_reviewNotifica que o caso está aguardando decisão de analista na mesa.
Header de Segurança
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.

Validação de Assinatura (Node.js / Express)
javascript
// 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ódigoQuando OcorreComo Tratar
401 UnauthorizedAPI 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 RequiredLimite 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 FoundIdentificador de verificação não encontrado para este tenant.Verifique se o UUID da sessão pertence à sua organização e ambiente correto.
409 ConflictTentativa de submissão em sessão que já foi previamente finalizada.Recupere o estado final via GET /v1/verifications/{id}.
429 Too Many RequestsRate 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.

Pronto para validar sua primeira identidade?

Crie sua conta em 30 segundos e comece a testar a API no ambiente Sandbox com R$ 100 de crédito gratuito para homologação.