> ## Documentation Index
> Fetch the complete documentation index at: https://docs.campeaosec.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Widget
> SDK JavaScript que gerencia captura de documento, selfie e liveness diretamente no browser do usuário.
## Visão Geral
O Widget Campeão Sec é um SDK JavaScript que você incorpora no frontend do seu produto. Ele gerencia todo o fluxo de captura: seleção de documento, foto da frente (e verso quando necessário), selfie com verificação de liveness.
Nenhuma imagem passa pelo seu servidor — o widget envia diretamente para a Campeão Sec via URLs pré-assinadas.
***
## Carregar o Script
```html theme={null}
```
O arquivo é self-contained (\~510 KB minificado). Carregue-o no `` ou antes de usar `CampeaoSec.init()`.
***
## Inicializar
Após obter o `session_token` do seu servidor, inicialize o widget:
```javascript theme={null}
CampeaoSec.init({
sessionToken: 'token_obtido_do_seu_servidor',
onSuccess: (result) => {
console.log('Verificação concluída', result.status, result.verification_id)
// status: 'approved' | 'rejected' | 'manual_review'
},
onCancel: () => {
console.log('Usuário cancelou')
},
onError: (err) => {
console.error('Erro:', err.code, err.message)
},
})
```
***
## Opções Completas
| Opção | Tipo | Obrigatório | Descrição |
| ------------------- | --------- | ----------- | -------------------------------------------------------------------------------------------- |
| `sessionToken` | string | **Sim** | Token obtido de `POST /v1/verify/session` |
| `onSuccess` | function | **Sim** | Callback chamado quando a verificação termina (qualquer status) |
| `onCancel` | function | **Sim** | Callback chamado quando o usuário fecha o widget |
| `onError` | function | **Sim** | Callback chamado em caso de erro técnico |
| `apiUrl` | string | Não | URL base da API. Default: `https://api-kyc.campeaosec.com` |
| `locale` | string | Não | Idioma: `'pt'`, `'en'`, `'es'`. Auto-detectado pelo browser |
| `country` | string | Não | País do usuário (ex: `'BR'`). Filtra os tipos de documento exibidos |
| `documentosAceitos` | string\[] | Não | Restringe os tipos de documento. Ver [Criar Sessão](/kyc/criar-sessao) |
| `containerId` | string | Não | ID de um elemento HTML onde renderizar o widget. Se omitido, abre como overlay em tela cheia |
***
## Callbacks
### `onSuccess(result)`
Chamado quando a verificação é concluída — independentemente do resultado (aprovado, reprovado ou revisão).
```javascript theme={null}
onSuccess: (result) => {
// result.verification_id → string UUID
// result.status → 'approved' | 'rejected' | 'manual_review' | 'webhook_failed'
// result.score_composto → número (0–100) ou null se ainda processando
// result.completed_at → ISO string ou null
// result.motivos_rejeicao → string[] ou null
}
```
Não tome decisões de negócio baseado apenas no `onSuccess`. Use o **webhook** como fonte de verdade — ele chega com o payload completo e assinatura verificável.
### `onError({ code, message })`
| `code` | Causa |
| ------------------ | ---------------------------------- |
| `CONSENT_ERROR` | Falha ao registrar o consentimento |
| `DOC_UPLOAD_ERROR` | Erro no upload do documento |
| `LIVENESS_ERROR` | Falha no desafio de liveness |
| `STATUS_TIMEOUT` | Timeout ao aguardar resultado |
| `WIDGET_ERROR` | Erro genérico |
***
## Fluxo do Widget
```
[Consentimento]
↓
[Selecionar tipo de documento]
• Passaporte, CIN, CNH, RG, etc.
↓
[Capturar frente do documento]
↓ (se documento exige verso, ex: RG)
[Capturar verso do documento]
↓
[Selfie com liveness]
• Ações aleatórias: piscar, sorrir, virar, acenar
↓
[Aguardando resultado]
↓
[onSuccess chamado]
```
***
## Embed em Container
Para renderizar dentro de um elemento específico (em vez de overlay):
```html theme={null}
```
***
## Fechar Programaticamente
```javascript theme={null}
CampeaoSec.destroy()
```
***
## Mobile
O widget funciona em navegadores mobile modernos (iOS Safari 15+, Chrome Android 90+). A câmera traseira é usada por padrão para documentos; a câmera frontal é usada para a selfie.
A captura de câmera requer **HTTPS**. Em desenvolvimento local, use `localhost` (permitido pelos browsers) ou um proxy com certificado válido.
***
## Exemplo Completo
```html theme={null}
```