Skip to main content
A url devolvida por POST /v1/sessions abre a verificação completa: formulários, documento, selfie e prova de vida. Você pode exibi-la num iframe, numa WebView, num popup ou por redirecionamento. Nenhum desses caminhos exige SDK.
Os eventos da página servem para atualizar a sua tela, como fechar o iframe ou mostrar “aguarde”. Eles não provam o resultado. Para decidir, use o webhook verification.completed ou consulte GET /v1/sessions/{id} no seu back-end.

Iframe

1. Crie a sessão com o seu site em allowedOrigins

allowedOrigins define quais sites podem exibir a verificação em iframe. Use só esquema, domínio e porta, sem caminho (https://app.exemplo.com). Se a lista ficar vazia, qualquer site que tenha o link pode exibir. Recomendamos preencher.

2. Coloque o iframe na página

Não reaproveite o mesmo iframe para outra sessão. Para uma nova verificação, crie outra sessão e troque o src.

3. Escute os eventos

A página manda mensagens para a janela que contém o iframe com window.parent.postMessage. Antes de usar uma mensagem, confira a origem dela e o campo source:

4. Fim do fluxo

Ao terminar, a página mostra um botão “Voltar para” seguido do nome da sua empresa se a sessão tiver redirectUrl. Dentro do iframe, esse botão abre o endereço na janela principal, não dentro do iframe. Se preferir controlar a saída você mesmo, não envie redirectUrl e use o evento terminal para fechar o iframe.

Eventos da página

Toda mensagem tem este formato:
Os quatro últimos são terminais: depois deles, a sessão não muda mais. Eles podem chegar mais de uma vez, porque a página reenvia o evento a cada atualização de estado. Trate só o primeiro. verification.completed quer dizer que a verificação terminou, não que a pessoa foi aprovada. A decisão fica em outcome e reviewState, na consulta da sessão. As mensagens não trazem o id da sessão nem dados da pessoa. Associe o evento à sessão pelo iframe ou pela tela que você abriu.

Etapas (step)

Workflows novos podem trazer etapas que não estão nesta lista. Se step vier com um valor que você não conhece, ignore e continue.

WebView

A WebView carrega a url como página principal, então allowedOrigins não se aplica. Você precisa liberar a câmera no app e, para receber os eventos, expor um canal que a página procura. A página manda cada evento como texto JSON, no mesmo formato acima, por estes canais (os que existirem):

iOS (WKWebView)

No Info.plist, adicione NSCameraUsageDescription (e NSMicrophoneUsageDescription se o workflow usar áudio).

Android (WebView)

No AndroidManifest.xml, declare android.permission.CAMERA e peça a permissão em tempo de execução antes de abrir a tela.

React Native

Use react-native-webview, ou o componente pronto em React Native, que já faz isto:

Voltar para o app ao terminar

Em WebView, você pode usar um esquema do seu app como redirectUrl, por exemplo meuapp://verificacao/fim. Intercepte essa navegação (decidePolicyFor no iOS, shouldOverrideUrlLoading no Android, onShouldStartLoadWithRequest no React Native) para fechar a tela. Os eventos terminais já bastam para isso, então o redirectUrl é opcional.

Comportamento nos dois casos

  • Continuar depois: o progresso fica salvo. Se a pessoa fechar e abrir o mesmo link no mesmo aparelho em até 1 hora, ela volta para a etapa onde parou. Depois disso, gere outro link com POST /v1/sessions/{id}/link.
  • Trocar de aparelho: nas etapas de câmera, a página oferece um QR code para continuar no celular. A partir daí, os eventos de etapa (verification.step_changed) saem no celular. O seu iframe ou WebView continua acompanhando e recebe o evento terminal enquanto estiver aberto. Se ele for fechado antes, o resultado chega só pelo back-end.
  • Sem câmera ao vivo: a página oferece enviar uma foto do aparelho. A prova de vida exige câmera ao vivo.

Problemas comuns