Central de desenvolvedores fio.js, API e Webhooks

Documentação para integrar o FACEIO a um aplicativo web: crie uma aplicação, carregue fio.js, chame enroll() ou authenticate(), depois conecte endpoints da REST API e webhooks quando o seu backend precisar deles.

Ir para: Início rápido Guia de integração REST API Webhooks
ABRIR o FACEIO Console

Crie uma aplicação no FACEIO Console, copie o Public ID, configure os domínios e as opções de segurança e adicione fio.js ao seu site ou aplicativo web.

Início rápido - Autenticação facial

~ 5 min

1 Crie sua aplicação

Entre no FACEIO Console ↗ e use o Application Wizard para criar uma aplicação. Escolha um mecanismo de reconhecimento, adicione os domínios onde o widget poderá ser executado e copie o Public ID exibido ao final.

Um Public ID tem o formato fioa1b2c3d4. É seguro usá-lo no navegador e ele é necessário para criar a instância do SDK.

2 Importe fio.js para o seu site

Adicione o contêiner do widget e carregue fio.js antes da tag de fechamento </body>. Use a CDN oficial para que correções no navegador e atualizações de segurança cheguem à sua aplicação sem exigir uma nova implantação.

index.html
HTML 
<div id="faceio-modal"></div>
<script src="https://cdn.faceio.net/fio.js"></script>
Usa um bundler? Instale o pacote NPM oficial ↗
npm i @faceio/fiojs

3 Crie uma instância de faceIO Object

Crie uma instância de faceIO com o Public ID da sua aplicação. Mantenha essa instância disponível nas partes da interface que precisam cadastrar ou autenticar usuários.

app.js
JavaScript 
<script type="text/javascript">
  /* Crie uma instância do fio.js com o Public ID da sua aplicação */
  const faceio = new faceIO("app-public-id");
</script>

4 Chame o widget

Quando fio.js estiver carregado e a instância faceIO() existir, chame um dos dois métodos principais:

enroll()

Registra um novo usuário e retorna um Facial ID que você pode associar ao registro da conta desse usuário - Acessar documentação →

authenticate()

Verifica um usuário recorrente no índice facial da sua aplicação - Acessar documentação →

app.js
JavaScript 
<button onclick="enrollNewUser()">Cadastrar novo usuário</button>
<button onclick="authenticateUser()">Autenticar usuário</button>

<script type="text/javascript">
  const faceio = new faceIO("app-public-id");

  function enrollNewUser() {
    // Chamar faceio.enroll() inicia o fluxo de cadastro
  }

  function authenticateUser() {
    // Chamar faceio.authenticate() inicia o fluxo de autenticação
  }

  function handleError(errCode) {
    // Trate o erro aqui
  }
</script>

Próximos passos

Guia completo de primeiros passos

Configuração do Console, capturas de tela e checklist de lançamento

Guias de SDK e frameworks

Exemplos para React, Vue, Angular e JavaScript puro

Segurança e boas práticas

Verificações antes de colocar em produção

SDK e frameworks

Ícone de primeiros passos
Início rápido

Guia de primeiros passos

Um passo a passo prático para sua primeira integração com o FACEIO: configuração do Console, permissão de domínios, seleção do mecanismo e um fluxo de cadastro funcional, com capturas de tela.

  • Passo a passo do Console com capturas de tela
  • Checklist de domínios, chaves e permissões do navegador
  • HTML inicial para adaptar à sua aplicação
Abrir guia de configuração
Ícone de código para desenvolvedores
Documentação da API

Referência da API e boilerplate

A referência de fio.js cobre parâmetros de métodos, valores de retorno, códigos de erro e exemplos para frameworks.

  • Referência completa dos métodos enroll() e authenticate()
  • Todos os códigos de erro com padrões recomendados de tratamento
  • Exemplos de frameworks para stacks JavaScript comuns
Ver guia de integração
Vanilla JavaScript

Vanilla JS

JavaScript puro
React

React

v18+ / Hooks
Vue.js

Vue.js

Vue 3 / Composition
Angular

Angular

v15+ / Standalone
Next.js

Next.js

App Router e Pages Router
Svelte

Svelte

Pronto para SvelteKit
Nuxt.js

Nuxt.js

Nuxt 3 / SSR
Ember.js

Ember.js

Edição Octane
Notas de compatibilidade dos frameworks
  • SDK independente de framework
    Use o FACEIO com React, Vue, Angular, Next.js, Svelte, Nuxt.js, Ember.js ou JavaScript puro.
  • Use as rotas existentes
    fio.js é independente de framework. Adicione-o aos fluxos de cadastro e login já usados pelo seu site ou aplicativo web.
  • Requisitos do navegador
    Funciona em navegadores modernos com uma webcam padrão. Os usuários não precisam de hardware biométrico dedicado.
Navegadores compatíveis:
Chrome Chrome
Firefox Firefox
Edge Edge
+ todos os navegadores baseados em Chromium
Ver todos os exemplos

Webhooks e API

Quando um usuário se cadastra, se autentica ou exclui um Facial ID, o FACEIO envia um HTTP POST ao endpoint configurado, com os detalhes do evento no corpo JSON.

Documentação completa
Ícone de Webhooks
Eventos em tempo real

Webhooks e notificações de eventos

Mantenha seu backend sincronizado quando os usuários se cadastrarem, se autenticarem ou excluírem um Facial ID.

ENROLL AUTH DELETION
Configurar webhooks

Como os webhooks funcionam

  1. 1

    Um usuário conclui um fluxo de cadastro, autenticação ou exclusão no widget do FACEIO.

  2. 2

    O FACEIO envia um HTTP POST para a URL do endpoint configurado.

  3. 3

    Valide o WWW-Authenticate bearer token antes de processar o payload JSON.

  4. Retorne 200 OK em até 6 segundos para que o FACEIO saiba que o evento foi recebido.

Guia de configuração (5 passos)
webhook-payload.json
JSON 
{
  "eventName": "AUTH",
  "facialId": "fid_a1b2c3d4e5f6...",
  "appId": "your-app-public-id",
  "clientIp": "203.0.113.42",
  "payload": "your-linked-user-data",
  "details": {
    "timestamp": "2025-12-29",
    "gender": "male",
    "age": "28"
  }
}

Campos principais

eventName
Tipo de evento: ENROLL / AUTH / DELETION
facialId
Facial ID associado à aplicação
payload
Seus dados de usuário associados (plano Business+)
clientIp
IP público do navegador do usuário
Autentique as requisições recebidas

Sempre compare o token Bearer do cabeçalho WWW-Authenticate com a chave do webhook exibida no FACEIO Console antes de confiar no payload.

Endpoints da REST API

Ícone de HTTP e rede

Acesse os endpoints da REST API

Controle programático

Use endpoints HTTPS autenticados para gerenciar aplicações FACEIO, Facial IDs e fluxos de conta no servidor. O fio.js é executado no navegador e não é necessário no seu backend.

GET POST DELETE Gerencie aplicações e Facial IDs
Explorar REST API
DELETE
Excluir Facial ID

Remova o Facial ID de um usuário do índice facial da sua aplicação.
GET
Obter detalhes da aplicação

Obtenha metadados, contagens de cadastros e a configuração de uma aplicação.
GET
Listar todas as aplicações

Liste as aplicações FACEIO vinculadas à sua conta, incluindo IDs, nomes e status.
POST
Verificar associação

Verifique se um Facial ID pertence ao índice facial da sua aplicação.
POST
Alterar nível do mecanismo

Alterne programaticamente entre níveis de mecanismos de reconhecimento facial para sua aplicação.
Ver todos os endpoints

Referência completa da REST API

Quer executar o FACEIO na sua própria infraestrutura?

Use a opção on-premise se a sua implantação exigir infraestrutura local e controle local do mecanismo de reconhecimento selecionado.

Saiba mais

Códigos de erro

Quando a Promise retornada por enroll() ou authenticate() é rejeitada, você recebe um errCode. Trate explicitamente os casos comuns para oferecer ao usuário um próximo passo claro.

Código Constante Significado Ação recomendada
1 fioErrCode.PERMISSION_REFUSED O acesso à câmera ou ao microfone foi negado pelo usuário ou pelo navegador. Peça ao usuário para permitir o acesso à câmera e tente novamente.
2 fioErrCode.NO_FACES_DETECTED Nenhum rosto foi detectado no quadro da câmera durante a sessão. Peça ao usuário para garantir boa iluminação e olhar diretamente para a câmera.
3 fioErrCode.UNRECOGNIZED_FACE O rosto escaneado não corresponde a nenhum usuário cadastrado no índice facial da sua aplicação. Mostre um erro e ofereça o fluxo de cadastro se o usuário for novo.
4 fioErrCode.MANY_FACES Vários rostos foram detectados simultaneamente no quadro da câmera. Peça ao usuário para garantir que apenas o próprio rosto esteja visível.
5 fioErrCode.FACE_DUPLICATION Este rosto já está enrolled no índice facial da sua aplicação. Redirecione o usuário para o fluxo de login (authenticate).
6 fioErrCode.PAD_ATTACK A detecção de vivacidade sinalizou uma tentativa de spoofing (foto, vídeo ou máscara). Rejeite a tentativa sem expor detalhes da lógica de detecção.
7 fioErrCode.MINORS_NOT_ALLOWED A estimativa de idade indica que o usuário está abaixo do limite mínimo definido na configuração da aplicação. Exiba uma mensagem adequada de controle de idade e interrompa o fluxo.
10 fioErrCode.NETWORK_IO Ocorreu um erro de rede ou timeout na comunicação com os servidores FACEIO. Tente novamente após uma breve espera e verifique a conexão do usuário.

Esta tabela cobre os casos comuns. A referência completa inclui erros de rede, sessão, navegador e consentimento.

Referência completa dos códigos de erro

Boas práticas

Leia antes de entrar em produção

A autenticação facial exige uma implantação cuidadosa. Comece pelas boas práticas de segurança e pelo controles de privacidade e consentimento antes de publicar.

Ícone de segurança
Configuração necessária

Segurança da aplicação

Restrinja onde o Widget pode ser executado, mantenha a validação por PIN Code ativada por padrão, configure a detecção de vivacidade e valide os eventos do backend.

  • Permita domínios para as origens exatas de produção
  • Configure a detecção de vivacidade para ajudar a detectar ataques de apresentação
  • Valide tokens de webhook antes de atualizar o estado da conta
Ver orientações de segurança
Ícone de privacidade
Controles de privacidade

Privacidade da aplicação

Mostre um consentimento claro antes da captura, mantenha os payloads pequenos, atenda aos pedidos de exclusão e mantenha uma trilha de auditoria para sua equipe revisar.

  • Sempre mostre o consentimento antes da captura
  • Minimize os dados do payload ao estritamente necessário
  • Atenda às solicitações de exclusão válidas conforme as regras de retenção aplicáveis
Ver orientações de privacidade
Facial ID
Modelo de identidade

Identificador facial exclusivo

Após o cadastro, o FACEIO retorna um Facial ID pertencente à sua aplicação. Armazene esse identificador junto ao seu próprio registro de usuário.

// Exemplo de associação
await db.users.update({
  where: { email: "user@x.com" },
  data:  { facialId: u.facialId }
});
Saiba mais sobre Facial IDs
Trust Center
Fluxo de dados

Mecanismo de reconhecimento e fluxo de dados

O FACEIO, incluindo fio.js, o Widget, a REST API e o Console, não armazena, processa nem acessa hashes biométricos. O Facial Recognition Engine selecionado pelo proprietário da aplicação realiza a comparação facial e gerencia os hashes biométricos. Os proprietários das aplicações continuam responsáveis pelo consentimento, retenção, exclusão e configuração do mecanismo.

Consentimento
Exclusão pelo usuário
Escolha do mecanismo
IDs associados ao escopo
Visitar Trust Center

Checklist de produção

Faça

  • Carregue fio.js exclusivamente de cdn.faceio.net
  • Restrinja o widget aos seus domínios exatos de produção no Console
  • Valide tokens de webhook e os identificadores esperados da aplicação antes de atualizar o estado da conta
  • Use HTTPS em todas as páginas onde o widget é carregado
  • Mostre uma tela de consentimento antes de chamar enroll()

Não faça

  • Não carregue fio.js de mirrors não oficiais; use a CDN oficial para que correções no navegador cheguem à sua aplicação
  • Não armazene imagens faciais, hashes biométricos ou payloads de autenticação sensíveis no armazenamento do cliente ou nos logs da aplicação
  • Não carregue o widget em http://; o acesso à câmera e as APIs seguras do navegador exigem HTTPS
  • Não chame enroll() antes de apresentar o aviso obrigatório e obter o consentimento explícito do usuário final
  • Nunca exponha sua chave secreta da API no lado do cliente

Visão geral dos produtos

Autenticação facial

Adicione autenticação facial com fio.js. Os usuários se cadastram no navegador, e sua aplicação recebe um facialId associado à aplicação para futuros fluxos de autenticação.

  • Armazene o facialId retornado no seu backend para associar o cadastro do FACEIO ao seu próprio registro de usuário.
  • Chame enroll() e authenticate() a partir da mesma instância de fio.js.
  • Use-o para login sem senha, reautenticação da conta ou verificações adicionais no seu fluxo de acesso existente.
fio.js login com reconhecimento facial autenticação facial
Guia de integração

Meeting Shield

Uma extensão do Chrome para detecção de deepfakes no Google Meet, Zoom Web e Microsoft Teams Web. Use-a para alertar participantes sobre vídeos suspeitos, sintéticos, reproduzidos ou manipulados em reuniões no navegador.

Explorar Meeting Shield

ID Match

Um widget de navegador incorporável para capturar um documento de identidade e uma selfie ao vivo, verificar a vivacidade e comparar a selfie com o retrato do documento. A extração opcional de campos usa o PixLab DOCSCAN ↗, compatível com mais de 11 mil formatos de documentos de mais de 197 países e territórios. O ID Match não autentica o documento nem estabelece identidade legal.

Explorar ID Match

Recursos e comunidade

FACEIO Console

FACEIO Console

Crie aplicações, consulte métricas, ajuste configurações de segurança e copie as chaves necessárias para sua integração.

Use o Console durante o desenvolvimento para gerenciar domínios permitidos, escolher configurações de reconhecimento e confirmar que cada ambiente está usando o Public ID correto.

Métricas ao vivo Configuração da aplicação Chaves da API
Abrir Console

FAQ

Perguntas comuns

Central de ajuda

Solução de problemas

Status

Disponibilidade em tempo real
Configuração para desenvolvedores

Adicione autenticação facial ao seu site ou aplicativo web

Crie uma aplicação no FACEIO Console, copie seu Public ID, carregue fio.js e teste enroll() e authenticate() com seu backend.

Integração direta em 5 minutos
Referências do fio.js, REST API e webhooks
Integração de navegador independente de framework
Verificações de consentimento, exclusão e segurança
Abrir FACEIO Console Ler guia de configuração