REFERÊNCIA

# Documentação UNIFOKAL

<https://unifokal.com/docs>

Verificação de identidade ponta a ponta, sem call de vendas: você cria um **Flow**, instala o **Widget** e recebe o resultado por **Webhook**. A captura e o processamento (CPF, OCR, face match, liveness) rodam no UNIFOKAL, então o seu front **nunca toca foto, selfie ou documento** e você fica fora do escopo mais pesado da LGPD.

BASE URL · REST

https://api.unifokal.com/v1

WIDGET · CDN

api.unifokal.com/dist/widget.global.js

A API vive em `/v1`. Tudo o que já mudou está no [changelog](https://unifokal.com/docs/changelog), e o que consideramos mudança que quebra está na [política de versão](https://unifokal.com/docs/versionamento). Integrando por agente ou por ferramenta? O catálogo de API em [`/.well-known/api-catalog`](https://unifokal.com/.well-known/api-catalog) (RFC 9727) aponta, em uma leitura, para o spec e para esta documentação.

Do zero ao primeiro resultado

Cinco passos acontecem **uma vez**, no painel, e três ficam no seu código. O código inteiro, pronto para copiar, está em [Integração ponta a ponta](https://unifokal.com/docs/integracao#integracao).

| \# | passo | onde |
| --- | --- | --- |
| 01 | Confirme o e-mail da conta e conclua o onboarding. Sem isso, criar sessão devolve `403 email_not_verified`. | painel |
| 02 | Cadastre o **destino do webhook** e escolha o segredo de assinatura. Ele vem primeiro porque o Flow exige um destino já cadastrado. | painel |
| 03 | Crie o **Flow** (os módulos e o destino do webhook). Recebe um `flow_id`. | painel |
| 04 | Gere a **chave secreta**. A de sandbox (`sk_test`) sai na hora. A de produção (`sk_live`) passa por três portões, nesta ordem: e-mail confirmado, verificação da conta concluída (`403 organization_cnpj_required`) e verificação em duas etapas ativa (`403 mfa_enrollment_required`, e depois o código no corpo). Veja [Sandbox e produção](https://unifokal.com/docs/ambientes#ambientes). | painel |
| 05 | Registre as **origens** onde o widget vai rodar. Sem isso o navegador recusa a chamada e o widget não sobe. | painel |
| 06 | No seu backend, crie a sessão: `POST /v1/verification-sessions`. Recebe o `id`. | seu código |
| 07 | No seu front, monte o widget com esse `id`. Nenhum segredo vai ao navegador. | seu código |
| 08 | No seu backend, receba o **webhook**, valide a assinatura e trate o desfecho. | seu código |

! A ordem **02 antes de 03** não é preferência: o Flow exige a URL de um destino de webhook já cadastrado, no mesmo ambiente. E o passo **05** é o que mais derruba integração nova, porque a falha acontece no navegador, longe de qualquer log nosso.

Conceitos

| `flow` | Receita de verificação: quais módulos rodam e em que ordem. |
| --- | --- |
| `verification` | Uma execução do flow por um usuário. Tem status e score. |
| `reference_id` | O ID do usuário no seu sistema. Obrigatório na criação da sessão e do link, e volta igual no webhook e na API. |
| `livemode` | false em sandbox, true em produção. Vem em toda verificação e webhook. |
| `schema_version` | Versão da FORMA do corpo do webhook. Campo novo não muda esse número; leia a política de versão. |

## Mapa da documentação

A referência é dividida por assunto, uma página para cada um, e cada módulo tem a própria página. Todo link antigo para uma seção desta página continua valendo e leva ao lugar novo.

### [O Widget](https://unifokal.com/docs/widget)

Como instalar o Widget UNIFOKAL em uma linha, montar com o id da sessão, tratar os eventos e fixar a versão do bundle com integridade.

- [O Widget](https://unifokal.com/docs/widget#widget)
  - [A forma de uma linha (sem JavaScript seu) (HTML)](https://unifokal.com/docs/widget#montar-widget-uma-linha)

### [Verificação em aplicativo](https://unifokal.com/docs/aplicativo-nativo)

Como abrir a verificação UNIFOKAL numa WebView do seu aplicativo: os ajustes de iOS e de Android que a câmera exige e como o app sabe a hora de fechar a tela.

- [Verificação em aplicativo](https://unifokal.com/docs/aplicativo-nativo#aplicativo-nativo)

### [Autenticação e segurança](https://unifokal.com/docs/autenticacao)

Chaves secretas de sandbox e de produção, os erros estáveis da criação de sessão, a segurança do fluxo e o acesso da equipe por SSO (SAML 2.0).

- [Autenticação](https://unifokal.com/docs/autenticacao#auth)
  - [Criar a sessão (curl)](https://unifokal.com/docs/autenticacao#criar-sessao-curl)
  - [Os erros que você vai encontrar no primeiro dia (curl)](https://unifokal.com/docs/autenticacao#erros-sessao-curl)
- [Segurança do fluxo](https://unifokal.com/docs/autenticacao#seguranca)
- [Acesso da equipe por SSO (SAML 2.0)](https://unifokal.com/docs/autenticacao#sso)

### [Integração ponta a ponta](https://unifokal.com/docs/integracao)

Código completo para criar a sessão, montar o widget, receber o webhook assinado e tratar cada desfecho, em HTTP, TypeScript e Python.

- [Integração ponta a ponta](https://unifokal.com/docs/integracao#integracao)
  - [Criar a sessão (TypeScript / Node)](https://unifokal.com/docs/integracao#criar-sessao-ts)
  - [Criar a sessão (Python)](https://unifokal.com/docs/integracao#criar-sessao-python)
  - [A página que o seu usuário abre (TypeScript / Node)](https://unifokal.com/docs/integracao#montar-widget-ts)
  - [Receber e validar o webhook (TypeScript / Node)](https://unifokal.com/docs/integracao#webhook-ts)
  - [Receber e validar o webhook (Python)](https://unifokal.com/docs/integracao#webhook-python)
  - [Conferir uma assinatura na mão (curl)](https://unifokal.com/docs/integracao#webhook-sh)
- [Os desfechos, e o que fazer com cada um](https://unifokal.com/docs/integracao#desfechos)
  - [Tratar os sete desfechos (TypeScript / Node)](https://unifokal.com/docs/integracao#desfechos-ts)
  - [Tratar os sete desfechos (Python)](https://unifokal.com/docs/integracao#desfechos-python)
  - [Recuperar entregas que falharam (curl)](https://unifokal.com/docs/integracao#recuperar-entregas-curl)
- [Receitas por jornada](https://unifokal.com/docs/integracao#receitas-das-jornadas)
- [Humano verificado: qual peça para qual caso](https://unifokal.com/docs/integracao#humano-verificado)

### [API REST](https://unifokal.com/docs/api-rest)

Os 4 endpoints públicos da API UNIFOKAL, o link de verificação hospedado, a confirmação fora de banda, a spec OpenAPI 3.1 com geração de tipos, a coleção importável e o briefing para agentes de IA.

- [API REST (4 endpoints públicos)](https://unifokal.com/docs/api-rest#api)
  - [POST /v1/verification-sessions](https://unifokal.com/docs/api-rest#post-sessions)
  - [GET /v1/webhook-events](https://unifokal.com/docs/api-rest#get-webhook-events)
  - [POST /v1/webhook-events/replay](https://unifokal.com/docs/api-rest#post-webhook-replay)
- [Link de verificação hospedado](https://unifokal.com/docs/api-rest#link-hospedado)
  - [POST /v1/verification-links](https://unifokal.com/docs/api-rest#post-verification-links)
- [Confirmação fora de banda](https://unifokal.com/docs/api-rest#confirmacao-fora-de-banda)
- [Spec OpenAPI e tipos](https://unifokal.com/docs/api-rest#openapi)
  - [GET /v1/capabilities](https://unifokal.com/docs/api-rest#get-capabilities)
  - [Gerar os tipos do contrato (curl)](https://unifokal.com/docs/api-rest#gerar-tipos-curl)
- [Coleção importável](https://unifokal.com/docs/api-rest#colecao-importavel)
- [Para agentes de IA](https://unifokal.com/docs/api-rest#agentes-de-ia)

### [Pacotes para IA](https://unifokal.com/docs/pacotes-para-ia)

A documentação da UNIFOKAL recortada por produto, em Markdown, para colar no seu assistente de IA, com o tamanho medido de cada pacote e a versão em Markdown de cada página.

- [Pacotes para o seu assistente de IA](https://unifokal.com/docs/pacotes-para-ia#pacotes-para-ia)
- [Cada página em Markdown](https://unifokal.com/docs/pacotes-para-ia#markdown-por-pagina)

### [Webhooks](https://unifokal.com/docs/webhooks)

O corpo do webhook da UNIFOKAL, os eventos, as retentativas e a validação da assinatura HMAC, com exemplos prontos.

- [Webhooks e eventos](https://unifokal.com/docs/webhooks#webhooks)
- [Valide a assinatura do webhook](https://unifokal.com/docs/webhooks#webhook-signature)
- [Conferir e apresentar o atestado de pessoa verificada](https://unifokal.com/docs/webhooks#atestado-de-pessoa-verificada)
- [Como conciliar o que foi cobrado](https://unifokal.com/docs/webhooks#conciliacao)

### [Sandbox, produção e lista de bloqueio](https://unifokal.com/docs/ambientes)

Como o sandbox simula cada desfecho, o que muda entre sandbox e produção e como funciona a lista de bloqueio da conta e do flow.

- [Lista de bloqueio](https://unifokal.com/docs/ambientes#blocklist)
- [Sandbox](https://unifokal.com/docs/ambientes#sandbox)
- [Sandbox e produção: o que muda](https://unifokal.com/docs/ambientes#ambientes)

### [Conta, dados e privacidade](https://unifokal.com/docs/conta-e-dados)

Exportação de dados, encerramento de conta e o aviso de privacidade e consentimento que o widget mostra ao titular.

- [Exportação de dados](https://unifokal.com/docs/conta-e-dados#exportacao-de-dados)
- [Encerramento de conta](https://unifokal.com/docs/conta-e-dados#encerramento-de-conta)
- [Privacidade e consentimento](https://unifokal.com/docs/conta-e-dados#privacidade-consentimento)

### [Painel de operação](https://unifokal.com/docs/painel-de-operacao)

O funil por etapa e por flow, o registro de requisições sem corpo, o orçamento diário de gasto com o spend_cap_reached, a consulta em lote, a simulação de política no histórico e a lista de permissão.

- [Painel de operação](https://unifokal.com/docs/painel-de-operacao#painel-de-operacao)
- [Lista de permissão](https://unifokal.com/docs/painel-de-operacao#lista-de-permissao)
- [Consulta em lote por planilha](https://unifokal.com/docs/painel-de-operacao#consulta-em-lote)
- [Permissões próprias](https://unifokal.com/docs/painel-de-operacao#permissoes-proprias)

### [PLD/FT pela regra da norma](https://unifokal.com/docs/pld-ft)

Como ligar o monitoramento de PLD/FT: a política aprovada, os campos do evento, o perfil do cliente, a fila com o prazo legal, o caso e o rascunho do Siscoaf.

- [PLD/FT pela regra da norma](https://unifokal.com/docs/pld-ft#pld-ft)
- [Dossiê selado: exportar e conferir](https://unifokal.com/docs/pld-ft#pld-ft-dossie-selado)
- [A contratação, pelos arts. 44, 45 e 47](https://unifokal.com/docs/pld-ft#pld-ft-contratacao)

### [Erros da API](https://unifokal.com/docs/erros)

Todo código de erro da API UNIFOKAL, com o status HTTP, o que aconteceu, o que fazer e o que não fazer, cada um na própria âncora.

- [Erros da API](https://unifokal.com/docs/erros#erros)

### [Glossário](https://unifokal.com/docs/glossario)

Os termos de verificação de identidade e de empresa (KYC, KYB, PEP, prova de vida, 1:1 e 1:N) e o vocabulário da API UNIFOKAL, um verbete por âncora.

- [Glossário](https://unifokal.com/docs/glossario#glossario)

### [Módulos](https://unifokal.com/docs/modulos)

O [catálogo de módulos](https://unifokal.com/docs/modulos#catalogo-modulos) lista tudo o que dá para ligar num Flow. Cada página abaixo traz o que o módulo entrega e o payload de resultado dele no webhook.

- [Documento, face match e prova de vida](https://unifokal.com/docs/modulos/identidade#modulos-identidade)
  - [Documento (OCR): cpf_ocr](https://unifokal.com/docs/modulos/identidade#modulo-cpf-ocr)
  - [Face Match 1:1: face](https://unifokal.com/docs/modulos/identidade#modulo-face)
  - [Prova de vida: liveness](https://unifokal.com/docs/modulos/identidade#modulo-liveness)
  - [Detecção de injeção de câmera](https://unifokal.com/docs/modulos/identidade#deteccao-injecao-camera)
- [Comprovante de endereço](https://unifokal.com/docs/modulos/endereco-ocr#modulo-endereco-ocr)
- [Verificação de idade](https://unifokal.com/docs/modulos/idade#modulo-idade)
- [Detecção de múltiplas contas (1:N)](https://unifokal.com/docs/modulos/face-unica#modulo-face-unica)
- [Reautenticação facial](https://unifokal.com/docs/modulos/face-reauth#modulo-face-reauth)
- [Aprovação de ato com passkey](https://unifokal.com/docs/modulos/passkey#modulo-passkey)
- [Atestado de pessoa verificada](https://unifokal.com/docs/modulos/atestado-humano#modulo-atestado-humano)
- [Reuso de Documento](https://unifokal.com/docs/modulos/doclink#modulo-doclink)
- [Validação de canal: e-mail e telefone](https://unifokal.com/docs/modulos/canal#modulos-canal)
  - [Código de canal: como chega ao titular](https://unifokal.com/docs/modulos/canal#post-otp)
  - [Código de canal: limites](https://unifokal.com/docs/modulos/canal#post-otp-verify)
- [PEP e listas restritivas](https://unifokal.com/docs/modulos/pep#modulo-pep)
- [Consulta cadastral de CPF e de CNPJ](https://unifokal.com/docs/modulos/cadastrais#modulos-cadastrais)
- [OCR do documento de empresa](https://unifokal.com/docs/modulos/cnpj-ocr#modulo-cnpj-ocr)
- [Dados cadastrais entregues](https://unifokal.com/docs/modulos/dados-cadastrais#modulo-dados-cadastrais)
- [Benefícios do governo](https://unifokal.com/docs/modulos/beneficios-gov#modulo-beneficios-gov)
- [Screening do quadro societário](https://unifokal.com/docs/modulos/screening-socios#screening-socios)
- [Impedidos de apostar](https://unifokal.com/docs/modulos/impedidos-apostar#modulo-impedidos-apostar)
- [Mídia adversa](https://unifokal.com/docs/modulos/midia-adversa#modulo-midia-adversa)
- [Coerência cadastral](https://unifokal.com/docs/modulos/coerencia-cadastral#modulo-coerencia-cadastral)
- [Forense de documento](https://unifokal.com/docs/modulos/doc-forense#modulo-doc-forense)
- [Detecção de rede de fraude](https://unifokal.com/docs/modulos/fraud-network#modulo-fraud-network)
- [Cadastro de dispositivo Pix](https://unifokal.com/docs/modulos/pix-device#modulo-pix-device)
- [Monitoramento de sessão](https://unifokal.com/docs/modulos/sessao-monitor#modulo-sessao-monitor)
- [Sinais do aparelho](https://unifokal.com/docs/modulos/device-intel#modulo-device-intel)
- [Assinatura eletrônica](https://unifokal.com/docs/modulos/assinatura#modulo-assinatura)
- [Custódia da autorização de consulta](https://unifokal.com/docs/modulos/custodia-autorizacao#modulo-custodia-autorizacao)
- [Documento de viagem estrangeiro (MRZ)](https://unifokal.com/docs/modulos/doc-global#modulo-doc-global)
- [Cadeia societária até o beneficiário final](https://unifokal.com/docs/modulos/ubo-profundo#modulo-ubo-profundo)
- [Inscrição estadual](https://unifokal.com/docs/modulos/inscricao-estadual#modulo-inscricao-estadual)
- [Certidão trabalhista (CNDT)](https://unifokal.com/docs/modulos/cndt#modulo-cndt)
- [Representante vinculado à empresa](https://unifokal.com/docs/modulos/representante-pj#modulo-representante-pj)
- [Empresa estrangeira](https://unifokal.com/docs/modulos/kyb-estrangeira#modulo-kyb-estrangeira)
- [Motor Antifraude](https://unifokal.com/docs/modulos/fraud-ai#modulo-fraud-ai)
- [Gate transacional](https://unifokal.com/docs/modulos/transacao#modulo-transacao)
- [Monitoramento transacional](https://unifokal.com/docs/modulos/transacao-monitor#modulo-transacao-monitor)
- [Proteção de conta](https://unifokal.com/docs/modulos/conta#modulo-conta)
- [Risco de IP e de e-mail](https://unifokal.com/docs/modulos/risco#modulos-risco)
- [Análise de crédito](https://unifokal.com/docs/modulos/credito#modulos-credito)
- [Monitoramento contínuo](https://unifokal.com/docs/modulos/monitoring-aml#modulo-monitoring-aml)
- [Monitoramento PLD/FT](https://unifokal.com/docs/modulos/pld-monitor#modulo-pld-monitor)
- [Classificação de risco PLD/FT](https://unifokal.com/docs/modulos/pld-risco#modulo-pld-risco)
- [Vínculos, listas restritivas e processos](https://unifokal.com/docs/modulos/compliance-vinculos#modulos-compliance-vinculos)
- [Background check e sanções](https://unifokal.com/docs/modulos/background#modulos-background)