Entrega do Widget
O widget é um aplicativo web hospedado que guia seu cliente pela captura do documento e da selfie. Você não constrói o tratamento da câmera, a orientação de enquadramento nem o coaching de novas tentativas — você entrega uma URL.
A URL
POST /v1/sessions retorna:
{ "widget_url": "https://{FQDN}/verify/8Kd2mQ…" }
O segmento final é um código de bootstrap de uso único, não um identificador de sessão. Quando a página carrega, o navegador o troca por um token de página de curta duração; o código em si não concede nada além de iniciar aquela única verificação.
| Propriedade | Comportamento |
|---|---|
| Vida útil | 48 horas a partir da criação da sessão |
| Escopo | Uma sessão. Não expõe dados do tenant e não pode ser usado para ler um resultado |
| Link expirado | O cliente vê uma mensagem de link expirado — crie uma nova sessão |
| Sessão já concluída | Reabrir uma verificação finalizada mostra uma mensagem de conclusão em vez de recomeçar |
Como o link tem prazo limitado, gere-o quando estiver pronto para enviá-lo — não com antecedência, em massa.
Três Formas de Entregá-lo
| Método | Como | Bom para |
|---|---|---|
| Redirect | Envie o navegador do cliente para o widget_url, e use a entrega por redirect para trazê-lo de volta | Fluxos de onboarding web |
| Webview nativa | Abra o widget_url em uma webview do sistema (WKWebView, WebView do Android) com permissão de câmera concedida | Apps móveis que mantêm o cliente dentro do app |
| Link externo | Envie a URL por SMS, WhatsApp ou e-mail | Fluxos desktop ou assistidos por agente em que o celular do cliente tem a câmera melhor |
Não há SDK JavaScript, API de iframe ou fluxo de eventos postMessage. A conclusão é sinalizada no lado do servidor — pelo webhook assinado ou pelo redirect assinado — o que também é o que a torna confiável: o desfecho sobre o qual seu backend age nunca passa sem assinatura pelo navegador do cliente.
Requisitos de Câmera
O acesso à câmera exige um contexto seguro. Na prática:
- Sirva ou abra o widget por HTTPS.
http://localhostehttp://127.0.0.1também se qualificam, para desenvolvimento local. - Em uma webview nativa, conceda a permissão de câmera antes de carregar a URL — o prompt do SO dentro de uma webview passa despercebido facilmente pelos clientes.
- A captura é apenas por câmera por padrão. Um seletor de arquivos aparece somente se o upload de arquivos estiver habilitado para o seu tenant, de modo que um cliente não pode enviar uma foto armazenada de um documento a menos que você tenha pedido para permitirmos.
As imagens são limitadas a 10 MB por captura, limite que a própria codificação do widget mantém com folga.
O Que o Cliente Vê
- Tipo de documento — passaporte, carteira de motorista ou carteira de identidade. Pulado quando você define
prefill.document_type, e limitado aos tipos habilitados para o seu tenant. - Captura do documento — uma máscara no formato do documento (página de foto do passaporte e zona de leitura mecânica, contorno de cartão ID-1) com feedback ao vivo de enquadramento, reflexo e desfoque. Documentos com dois lados solicitam o verso.
- Confirmação — os campos extraídos são exibidos para que o cliente identifique uma leitura errada antes de continuar.
- Selfie — um oval para o rosto com orientação de captura.
- Resultado — aprovado, recusado ou uma mensagem de "em análise". No modo redirect o cliente é devolvido à sua URL em vez disso.
Novas Tentativas de Captura
Uma captura que não pode ser verificada — desfocada demais para ler, uma foto de uma tela, um rosto que não corresponde — devolve o cliente à etapa relevante com feedback específico, em vez de falhar a sessão de imediato.
| Comportamento | Detalhe |
|---|---|
| Limite de tentativas | O padrão do seu tenant (3, salvo configuração em contrário), com sobreposição por sessão via max_capture_attempts |
| A cada falha | O cliente vê feedback direcionado para o problema específico e tenta novamente |
| Ao esgotar | A sessão é recusada, e você recebe esse resultado como qualquer outro, carregando uma verificação capture_attempts que informa o limite atingido |
Aumente o limite para um fluxo de consumidor tolerante; reduza-o onde capturas falhas repetidas forem, por si sós, um sinal de fraude.
Identidade Visual e Localização
Ambas são configuradas por tenant no onboarding — veja Configuração do Tenant.
A identidade visual aplica seu logotipo, o nome da empresa e as cores primária, de fundo e de texto ao chrome do widget, para que o fluxo pareça parte do seu produto. O rodapé "Powered by Inyo 360" sempre é renderizado e intencionalmente não é configurável.
O idioma vem do campo language da sessão, com fallback para o seu padrão configurado. Inglês, português e espanhol são fornecidos completos; qualquer código xx ou xx-XX é aceito, e qualquer string sem tradução recorre individualmente ao inglês em vez de descartar o idioma inteiro. Toda string que o widget renderiza é servida a partir do repositório de textos da Inyo, então a redação — incluindo o feedback de novas tentativas e as telas de resultado — pode ser ajustada para o seu tenant sem uma release do seu lado.
Verificação de Presença Humana
O widget pode apresentar um breve desafio da Cloudflare ao iniciar, para impedir que tráfego automatizado consuma verificações. Ele é invisível ou quase invisível para clientes reais e não exige nada da sua integração.
Acompanhando o Progresso
Você não precisa observar o progresso do cliente — o resultado é enviado a você — mas GET /v1/sessions/{session_id} expõe um campo step (document_front, document_back, selfie, done) caso você queira exibir um estado "em andamento" na sua própria UI ou medir o abandono entre etapas.
Próximos Passos
- Recebendo Resultados — verificação de assinatura para ambos os modos de entrega
- Configuração do Tenant — identidade visual, tipos de documento permitidos, comportamento de captura
- Verificação Server-to-Server — a alternativa quando você é dono da UI de captura