Widget Auth

Visão Geral

O Widget Auth é servido pelo mesmo script do KYC (widget.js), mas opera em modo de autenticação: não há captura de documento. O fluxo é apenas selfie com verificação de liveness, tornando a experiência muito mais rápida (< 4 segundos em média). O widget compara a selfie capturada contra o embedding facial armazenado no KYC do external_id informado.

Carregar o Script

<script src="https://api-kyc.campeaosec.com/widget.js"></script>

O mesmo arquivo serve tanto KYC quanto Auth — o modo é determinado pelo tipo de token passado em init().

Inicializar

Após obter o session_token do seu servidor (via POST /v1/auth/session), inicialize o widget:

CampeaoSec.init({
  sessionToken: 'token_obtido_do_seu_servidor',
  onSuccess: (result) => {
    // result.authenticated → true se autenticado, false se rejeitado
    // result.auth_id       → UUID do registro de autenticação
    // result.status        → 'authenticated' | 'rejected'
    console.log('Auth concluído', result.authenticated, result.auth_id)
  },
  onCancel: () => {
    console.log('Usuário cancelou')
  },
  onError: (err) => {
    console.error('Erro:', err.code, err.message)
  },
})

Não tome decisões de segurança baseado apenas no onSuccess. Use o webhook como fonte de verdade — ele chega com scores completos e assinatura HMAC verificável.

Característica	KYC	Auth 1:1
Captura de documento	Sim	Não
Selfie + liveness	Sim	Sim
Tempo médio	60–90s	< 4s
Crédito consumido	KYC	Auth
Token de sessão	`POST /v1/verify/session`	`POST /v1/auth/session`
Callback de resultado	`result.status`	`result.authenticated`

Opções

Opção	Tipo	Obrigatório	Descrição
`sessionToken`	string	Sim	Token obtido de `POST /v1/auth/session`
`onSuccess`	function	Sim	Callback ao concluir (qualquer resultado)
`onCancel`	function	Sim	Callback quando usuário fecha o widget
`onError`	function	Sim	Callback em erro técnico
`locale`	string	Não	Idioma: `'pt'`, `'en'`, `'es'`. Auto-detectado
`containerId`	string	Não	ID de elemento HTML para embed. Se omitido, abre como overlay
`apiUrl`	string	Não	URL base da API. Default: `https://api-kyc.campeaosec.com`

[Consentimento]
      ↓
[Selfie com liveness]
  • Desafio aleatório: piscar, sorrir, virar, acenar
  • ~3–4 segundos
      ↓
[Processamento]
  • Extração de embedding
  • Comparação com embedding KYC armazenado
      ↓
[onSuccess chamado]
  • authenticated: true / false

Callbacks

`onSuccess(result)`

onSuccess: (result) => {
  // result.auth_id        → string UUID do registro
  // result.authenticated  → boolean
  // result.status         → 'authenticated' | 'rejected' | 'expired'
  // result.score_liveness → número (0–1) ou null
  // result.score_facial   → número (0–1) ou null
}

`onError({ code, message })`

`code`	Causa
`LIVENESS_ERROR`	Falha no desafio de liveness (câmera bloqueada, pouca luz)
`NO_EMBEDDING`	Embedding KYC não encontrado para o usuário
`STATUS_TIMEOUT`	Timeout ao aguardar resultado do servidor
`WIDGET_ERROR`	Erro técnico genérico

Embed em Container

<div id="auth-container" style="width: 360px; margin: 0 auto;"></div>

<script>
CampeaoSec.init({
  sessionToken: 'token_aqui',
  containerId: 'auth-container',
  onSuccess: (result) => { /* ... */ },
  onCancel: () => { /* ... */ },
  onError: (err) => { /* ... */ },
})
</script>

Fechar Programaticamente

CampeaoSec.destroy()

Exemplo Completo

<!DOCTYPE html>
<html>
<head>
  <script src="https://api-kyc.campeaosec.com/widget.js"></script>
</head>
<body>
  <button id="btn-autenticar">Confirmar identidade</button>

  <script>
    document.getElementById('btn-autenticar').addEventListener('click', async () => {
      // 1. Buscar session_token do seu servidor
      const res = await fetch('/api/auth/session', { method: 'POST' })
      const { session_token } = await res.json()

      // 2. Inicializar o widget de autenticação
      CampeaoSec.init({
        sessionToken: session_token,
        locale: 'pt',
        onSuccess: (result) => {
          if (result.authenticated) {
            // Usuário autenticado — prosseguir com a operação sensível
            window.location.href = '/confirmar-transacao'
          } else {
            alert('Autenticação não confirmada. Tente novamente.')
          }
        },
        onCancel: () => {
          console.log('Usuário cancelou a autenticação')
        },
        onError: (err) => {
          console.error('Erro na autenticação:', err.code)
        },
      })
    })
  </script>
</body>
</html>

Apps Nativos (React Native / Flutter)

Para apps nativos, use redirect_uri ao criar a sessão e abra a widget_url retornada em um WebView ou browser externo. O app é retomado via deep link após a autenticação.

// Criar sessão no seu servidor com redirect_uri
const { widget_url } = await criarSessaoAuth({
  external_id: userId,
  redirect_uri: 'meuapp://auth-complete',
})

// Abrir widget_url no browser do dispositivo
Linking.openURL(widget_url)

// Capturar retorno via deep link
// meuapp://auth-complete?auth_id=abc123&status=authenticated

Primeiros Passos

KYC Verify

Auth 1:1

Visão Geral

Carregar o Script

Inicializar

Diferenças em relação ao Widget KYC

Opções

Fluxo do Widget

Callbacks

`onSuccess(result)`

`onError({ code, message })`

Embed em Container

Fechar Programaticamente

Exemplo Completo

Apps Nativos (React Native / Flutter)

​Visão Geral

​Carregar o Script

​Inicializar

​Diferenças em relação ao Widget KYC

​Opções

​Fluxo do Widget

​Callbacks

​onSuccess(result)

​onError({ code, message })

​Embed em Container

​Fechar Programaticamente

​Exemplo Completo

​Apps Nativos (React Native / Flutter)

Visão Geral

Carregar o Script

Inicializar

Diferenças em relação ao Widget KYC

Opções

Fluxo do Widget

Callbacks

`onSuccess(result)`

`onError({ code, message })`

Embed em Container

Fechar Programaticamente

Exemplo Completo

Apps Nativos (React Native / Flutter)