Configurações do produto

O que você pode decidir na implementação do Fortface​

Configurações gerais (via API)​

Estas decisões vêm da API e valem independentemente da plataforma usada para capturar a selfie ou o documento. São as mesmas para Android, iOS e Web.

Qual ação ou endpoint usar em cada momento da jornada​

A Fortface oferece um conjunto de ações e endpoints, cada um pensado para um momento diferente da jornada do usuário. Escolher o certo para cada etapa é a decisão mais estrutural de todas, pois define o que a API vai processar e o que ela retorna:

  • enroll: cadastra a selfie do usuário na base biométrica (ex.: no cadastro/abertura de conta)
  • identify: compara a selfie com a foto já cadastrada (ex.: login, autenticação de uma ação sensível)
  • search: compara a selfie contra toda a base de cadastros (1:N), útil para detectar identidades duplicadas/fraude
  • capture: verifica a selfie cruzando com o CPF (único caso em que o CPF é obrigatório)
  • liveness: só confirma que é uma pessoa real, sem comparar com nada
  • /document: analisa um documento de identidade (foto ou PDF), com opção de extrair os dados via OCR e/ou comparar o documento com a selfie do usuário

Essas ações estão disponíveis pela chamada direta via SDK/Backoffice (handshake).

Veja a seção "Recursos" para o detalhamento completo de cada ação e endpoint.

Regras de aprovação e reprovação​

Match Level (nível de correspondência facial 1:1)

A API nunca decide sozinha se aprova ou reprova: ela retorna um número de 0 a 16 (matchLevel) indicando o quanto a selfie bate com a foto cadastrada. Sua empresa define o ponto de corte. A Fortface recomenda usar 13 ou mais como referência de baixo risco de falso positivo/negativo.

Veja a tabela completa de taxas de erro por nível na seção "Melhores Práticas de Segurança".

Score de risco de identidade (selfie + CPF, via Hubface)

Ao usar a ação capture, a API cruza a selfie com o CPF e devolve um score de 1 a 5 (mais os casos NULL e 0). Isso define sua política de decisão:

  • 5 → risco baixíssimo → pode aprovar automaticamente
  • 4 → risco baixo → aprovar com monitoramento
  • 3 → neutro → indicar para revisão manual
  • 2 → risco médio → reprovar preventivamente (com possibilidade de recurso)
  • 1 → risco alto → reprovar automaticamente
  • 0 / NULL → sem informação suficiente → pedir nova captura ou complementar com outra fonte

Em ambiente de testes (sandbox), esse score pode ser simulado pelo último dígito do CPF enviado, útil para testar todos os cenários sem depender de dados reais.

Aprofunde na seção "Hubface: Validação de Rosto e Documento" antes de definir sua política de aprovação.

Detecção de rosto coberto/obstruído (Face Occlusion)

Sinaliza se óculos escuros, mãos, objetos ou a região dos olhos estão cobrindo o rosto na selfie. É um dado adicional; não bloqueia sozinho o resultado, mas pode ser usado na sua regra para pedir uma nova foto. Óculos de grau comuns normalmente não contam como oclusão.

Como ativar: por configuração de conta ou enviando analysis.faceOcclusion na requisição.

Detecção de conteúdo impróprio (NSFW)

Verifica se a imagem enviada é uma foto apropriada, evitando o envio de conteúdo indevido no lugar da selfie. Ativa via analysis.nsfw: true.

Rigor da prova de vida (Liveness Calibration)

Permite calibrar a sensibilidade da checagem de vivacidade facial. Três níveis disponíveis: optimal, enhanced e supreme (padrão da API). Quanto mais rigoroso o nível, maior a segurança contra fraudes, mas também maior a chance de o usuário legítimo precisar repetir a captura. O Fortface usa liveness passivo: o usuário não precisa piscar, sorrir ou virar o rosto.

Como configurar: campo analysis.livenessCalibration (valores optimal, enhanced ou supreme) no handshake (SDK) ou direto na requisição (Backoffice).

O que sua empresa pode decidir sobre os dados do usuário​

Além das regras de aprovação, existem algumas decisões sobre quais dados coletar/receber de volta durante a verificação e o que fazer com eles. Esta lista traz só o que é de fato configurável pela sua empresa; não é um inventário de tudo que a API processa internamente.

  • Extração de dados do documento (OCR): decide se, ao analisar o documento, a API também retorna os dados extraídos dele (nome, número do documento, data de nascimento, validade, nacionalidade, sexo). Ativa via ocr: true na chamada de análise de documento.

  • Geolocalização: decide se sua aplicação vai solicitar a localização do usuário durante a sessão, como sinal adicional de antifraude. A configuração real acontece no tópico "Permissões do usuário" desta mesma seção, via SessionDetails.getGeolocation.

  • Retorno da própria foto capturada (returnPhoto): decide se sua empresa quer receber a imagem da selfie de volta na resposta da API (para guardar por conta própria) ou deixar que o Fortface armazene.

IDs de correlação​

externalTransactionId e externalUserId: campos que você define para conseguir cruzar o resultado recebido na resposta da chamada direta com sua transação e usuário internos. Fortemente recomendado usar sempre, para rastreabilidade e suporte.

Vale reforçar também o papel do externalTransactionId nas retentativas: quando o usuário falha e tenta de novo, o app deve reutilizar o mesmo externalTransactionId em vez de abrir uma transação nova, para medir corretamente a taxa de sucesso por transação (e não por tentativa avulsa). Essa prática também está detalhada no tópico "Comportamento de erro e nova tentativa" desta mesma seção.

Configurações de conta​

  • Sandbox vs. Produção: ambientes separados; sandbox tem flexibilizações para facilitar testes.
  • Permissões por API-Key: quais ações (enroll, identify, search, etc.) sua chave pode executar dependem do plano comercial contratado.
  • Galerias: permitem separar cadastros por contexto de negócio (ex.: por produto/linha de negócio); hoje configurada via time comercial, não self-service.
  • Armazenamento de fotos (savePhoto): decisão de arquitetura/compliance: a Fortface guarda as fotos capturadas, ou sua empresa prefere guardar por conta própria? Impacta LGPD e custo de armazenamento.
  • Certificado mTLS: pré-requisito obrigatório de segurança de conexão; gerado pela sua empresa e validado pela Fortface (validade de 10 anos). Impacta o cronograma de implementação.
  • Assinatura de resposta (Response Signature): recurso opcional que garante que as respostas da API não foram adulteradas; precisa ser solicitado e ativado com o time Fortface.
  • Remoção de usuário / exclusão de dados: endpoint DELETE /backoffice/v1/enroll, disponível apenas via Backoffice (não é self-service pelo SDK), para excluir o cadastro biométrico de um usuário. Relevante para atender solicitações de titular de dados (LGPD).

SDK Android​

O SDK Android controla toda a experiência visual da captura (selfie e documento) dentro do seu app. Há duas formas de customizar: por código (FortfaceCustomizer, em processo de descontinuação) ou por arquivo JSON (recomendado para novas integrações); as duas não podem ser combinadas na mesma implementação.

Cores, tema e branding​

Praticamente toda tela do fluxo é customizável: cor de fundo, cor de botões, cor de textos, ícones, fonte e (na tela de câmera) a logo da sua marca (se você não configurar uma, nenhuma logo aparece).

As cores de status da câmera (sucesso/alerta/luminosidade) seguem uma convenção recomendada pela Fortface: verde para sucesso, laranja/amarelo para alerta, azul para luminosidade. Isso porque testes de usabilidade mostraram que o usuário confia mais na cor do que no texto para saber se está tudo certo. Vale manter essa convenção mesmo customizando as cores.

A lista completa de parâmetros (cor de fundo da câmera, cor dos botões de aceitar/recusar no upload, cor do frame do documento, etc.) está na seção "Customizações SDK".

→ Recomendação: se sua empresa optar por cores, fontes ou textos diferentes dos padrões já enviados pela Fortface, leia a página "Guia de Usabilidade" antes de fechar o guia de marca. Ela traz as diretrizes testadas com usuários reais (convenção de cores por status, contraste mínimo, tom de voz das mensagens) que impactam diretamente a taxa de sucesso da captura.

Tela de instrução (antes da selfie)​

Pode ser ligada ou desligada por completo (instructionScreen). Quando ativa, mostra 4 dicas padrão antes de abrir a câmera (tirar óculos/boné, buscar local iluminado, expressão neutra, posição do celular): título, textos, ícones, cores e o botão "Continuar" são todos customizáveis.

Recomendação da Fortface: manter a tela ativa. Ela reduz retrabalho e aumenta a taxa de sucesso na primeira tentativa de captura.

Não existe uma tela de instrução equivalente antes da captura de documento: esse fluxo vai direto para a câmera.

Permissões do usuário​

  • Câmera: obrigatória. Sem ela, o SDK não funciona.
  • Geolocalização: opcional, ativada por sessão (SessionDetails.getGeolocation). Se o usuário negar, a captura segue normalmente. É uma decisão de negócio: mais um sinal antifraude vs. uma permissão a mais pedida ao usuário (o que pode gerar atrito).

Captura e upload de documentos​

  • Modo de captura: automática (padrão) com fallback de botão manual, diferente da selfie, que é só automática.
  • Upload de arquivo: pode abrir a galeria de fotos ou o gerenciador de arquivos do celular (openPhotoGalery), o que muda se o usuário pode enviar PDFs ou só imagens.
  • Limite de tamanho: arquivos acima de 4MB são rejeitados automaticamente (regra fixa, não configurável; vale considerar na orientação ao usuário).
  • Tela de revisão pós-captura: pergunta se o documento ficou nítido/legível, com opção de confirmar ou refazer.

Modo de exibição​

  • Tela cheia (padrão) ou modal: modal só funciona em tablets; em smartphone, sempre abre em tela cheia.
  • Orientação: automática, retrato ou paisagem (também só configurável em tablets; smartphone é sempre retrato).

Comportamento de erro e nova tentativa​

Quando o usuário falha e tenta de novo, o app deve reutilizar o mesmo externalTransactionId em vez de abrir uma transação nova: isso é o que permite medir corretamente a taxa de sucesso por transação (e não por tentativa avulsa).

SDK iOS​

Cores, tema e branding​

A lógica de customização do iOS é equivalente à do Android: duas formas (código Swift, em descontinuação, ou arquivo JSON, recomendado), que não podem ser combinadas.

Mesma cobertura do Android: cor de fundo, cor/texto de botões, ícones, logo (câmera de selfie) e fonte, em cada uma das telas do fluxo (instrução, câmera de selfie, câmera de documento, upload).

Diferença importante do iOS: ao usar o arquivo JSON, apenas a família da fonte é aplicada: tamanho e peso da fonte (font.size, font.weight) definidos no JSON não têm efeito no iOS. Vale alinhar essa limitação com o time de design ao montar o guia de marca.

→ Recomendação: se sua empresa optar por cores, fontes ou textos diferentes dos padrões já enviados pela Fortface, vale ler a página "Guia de Usabilidade" antes de fechar o guia de marca. Ela traz as diretrizes testadas com usuários reais (convenção de cores por status, contraste mínimo, tom de voz das mensagens) que impactam diretamente a taxa de sucesso da captura.

Tela de instrução​

Mesmo comportamento do Android: pode ser ativada/desativada, com título, 4 dicas, ícones e botão "Continuar" customizáveis. A Fortface recomenda manter ativa: reduz retrabalho e aumenta a taxa de sucesso na primeira tentativa. Também não existe versão equivalente antes da captura de documento (só uma tela de revisão pós-captura).

Permissões do usuário​

  • Câmera: obrigatória. O texto exibido ao usuário explicando por que o acesso é necessário é livre; cabe ao seu time de produto escrever essa mensagem (configurada no app, não no SDK).
  • Geolocalização: opcional, por sessão, mesmo racional do Android (sinal antifraude vs. atrito).
  • Galeria de fotos/arquivos: solicitada apenas se o fluxo de upload de documento estiver habilitado.

Captura e upload de documentos​

  • Captura automática com fallback manual, limite de 4MB por arquivo, e a mesma tela de revisão pós-captura do Android.
  • Orientação da captura de documento é sempre retrato, sem opção de configurar diferente (diferente da selfie, que permite retrato/paisagem em tablets).

Modo de exibição​

Mesmas opções do Android: tela cheia (padrão) ou modal (só em tablets), orientação automática/retrato/paisagem (só em tablets).

Comportamento de erro e nova tentativa​

O SDK não tem uma tela de erro pronta; cabe ao app decidir a experiência para cada cenário (câmera negada, timeout, erro técnico, cancelamento). A Fortface recomenda registrar também os eventos de cancelamento e timeout (não só sucesso) para ter métricas reais de funil, e reaproveitar o mesmo externalTransactionId em novas tentativas.

SDK Web​

Cores, tema e branding​

O SDK Web segue a mesma filosofia de customização via objeto de tema (theme/components), com algumas opções exclusivas da versão web (modo embutido, uso em iframe/WebView). Esta seção também é a única que traz as decisões sobre o Fortlink (link de captura remota), já que é um fluxo hospedado via navegador.

Cobertura equivalente às SDKs mobile: fonte, cor de fundo, logo, botões e cores de status por tela (tema geral, tela de instrução, câmera de selfie, tela de prontidão, câmera de documento, upload).

A lista completa de parâmetros de customização está na seção "Customizações SDK".

→ Recomendação: se sua empresa optar por cores, fontes ou textos diferentes dos padrões já enviados pela Fortface, vale ler a página "Guia de Usabilidade" antes de fechar o guia de marca. Ela traz as diretrizes testadas com usuários reais (convenção de cores por status, contraste mínimo, tom de voz das mensagens) que impactam diretamente a taxa de sucesso da captura.

Tela de instrução​

Pode ser ativada/desativada (face_recognition.instructions_screen.visible), com o mesmo conjunto de textos, ícones e botão customizáveis das outras plataformas. Recomendação de manter ativa se repete aqui: reduz retrabalho e aumenta a taxa de sucesso na primeira tentativa.

→ CTA: a validar com o time técnico: a documentação de origem apresenta uma possível duplicidade de chave entre dois textos da tela de instrução (dica de "expressão neutra" e "retirar óculos/boné" usando a mesma referência); vale confirmar qual prevalece antes de traduzir isso num guia de customização para o cliente.

Assim como nas SDKs mobile, não há tela de instrução equivalente antes da captura de documento.

Modos de exibição (exclusivo da Web)​

Três opções, mais flexíveis que mobile:

  • Tela cheia: padrão.
  • Modal: com overlay customizável (cor/opacidade); ativado automaticamente a partir de uma largura mínima de tela configurável (pensado para desktop).
  • Embutido (embedded): o SDK roda dentro de um espaço da sua própria página, sem abrir por cima de tudo. Exige um tamanho mínimo de área (400x650px).

Essa é uma decisão de arquitetura de produto relevante (ex.: embutir a verificação dentro de um formulário de onboarding vs. abrir por cima da tela); veja a seção "Modo Modal ou Fullscreen" para os detalhes técnicos.

Permissões do usuário​

  • Câmera: obrigatória; se negada, os navegadores não reabrem o pedido automaticamente, então a Fortface recomenda não tentar de novo em loop e orientar o usuário a liberar manualmente e recarregar a página.
  • Geolocalização: opcional, por sessão, mesmo racional das SDKs mobile.
  • Uso em iframe/WebView: requer configuração adicional (allow="camera") para a câmera funcionar; sem isso, o fluxo falha antes mesmo de começar. Relevante se o produto for integrado dentro do app de um parceiro.

Câmera usada na captura da selfie​

Por padrão, o SDK Web abre a câmera frontal para a selfie. É possível configurar o uso da câmera traseira no lugar (parâmetro useBackCamera, disponível a partir da versão 2.3.0 do SDK Web), útil em cenários de captura assistida, como um atendente fotografando o usuário. Essa opção é exclusiva do SDK Web; não foi encontrada documentação equivalente para Android ou iOS.

Como configurar: useBackCamera: true ao iniciar a sessão de biometria facial.

Captura e upload de documentos​

Mesma lógica das SDKs mobile: captura ao vivo com fallback manual, upload de arquivo, tela de revisão pós-captura.

Comportamento de erro e nova tentativa​

O SDK encerra cada sessão em uma destas ações, que o app precisa tratar com sua própria experiência: capture (sucesso), cancel (usuário cancelou), timeout (tempo de captura esgotado), timeout_ready (tempo de carregamento/prontidão esgotado) e error (falha, com um código específico). A Fortface recomenda manter log desses eventos (não só o de sucesso) para ter métricas reais de funil, evitar tentar novamente em loop quando a permissão de câmera for negada, e reaproveitar o mesmo externalTransactionId em novas tentativas.

Métricas de experiência (exclusivo da Web)​

Ativando returnMetrics: true, a sessão retorna o tempo gasto em cada etapa (download de assets, abertura da câmera, tela de instrução, captura). Isso é uma ferramenta de produto: dá para medir, por exemplo, se vale a pena manter a tela de instrução comparando o tempo dela com a taxa de sucesso.

Compatibilidade de navegador​

Define quem consegue completar o fluxo: exige, por exemplo, Chrome 112+, Safari 15.4+, Firefox 110+ (varia por sistema operacional). Vale considerar ao dimensionar conversão: usuários em navegadores mais antigos recebem erro de incompatibilidade.

O Fortlink é um link de captura remota gerado pela API. Sua empresa cria o link e decide como enviá-lo ao usuário (SMS, e-mail, WhatsApp); a Fortface não envia nada, só gera o link. O usuário final abre o link no navegador e completa a verificação sem precisar instalar nada, o que é uma alternativa a embutir o SDK Web diretamente no seu site ou app. Por isso essas decisões aparecem só aqui, na seção Web.

Pelo Fortlink, o conjunto de ações disponível hoje é enroll, identify, capture e liveness; search e /document são exclusivos da chamada direta via SDK/Backoffice (ver tópico 1).

Veja a seção "Fortlink: Ações disponíveis" para desenhar o fluxo completo por caso de uso.

Todo Fortlink termina em um destes status, e cabe à sua empresa decidir o que fazer em cada um:

  • PENDING: usuário ainda não concluiu
  • EXPIRED: link venceu antes do uso
  • APPROVED: aprovado (liveness e/ou score Hubface positivos)
  • REJECTED: liveness reprovado mais de 5 vezes, ou score Hubface 1 ou 2
  • INCONCLUSIVE: score Hubface 0 ou 3 (não dá para afirmar nada)

Veja a seção "Fortlink: Status possíveis" para o detalhamento de cada regra.

Sua empresa decide como e quando recebe o resultado da verificação. Três mecanismos disponíveis, que podem ser combinados:

Webhook do Fortlink: ao criar um link de captura remota, você informa uma URL que recebe automaticamente o resultado assim que o usuário concluir (ou o link expirar). É o canal recomendado, mais confiável que ficar consultando manualmente.

Consulta manual (polling): alternativa ao webhook: consultar o status do link a qualquer momento por uma chamada própria.

Redirecionamento pós-fluxo (redirectURL): leva o usuário de volta ao seu app/site depois da tela final. É só navegação; não substitui o webhook como fonte do resultado.

Como o Fortlink é assíncrono (o resultado chega depois, por webhook ou consulta manual, e não na hora como numa chamada direta), os campos externalTransactionId e externalUserId (ver tópico "IDs de correlação" acima) são essenciais para cruzar o resultado recebido com sua transação e usuário internos. Fortemente recomendado sempre gerar e enviar esses IDs ao criar o Fortlink.

Última atualização em