API de verificação facial online

Compare duas imagens faciais no seu backend e receba os sinais documentados dist, sim e same_person. Sua aplicação decide como usar o resultado. Para um fluxo de navegador com captura ao vivo, consulte verificação facial online.

ABRIR o FACEIO Console

Conecte-se ao FACEIO Console para criar aplicações, gerenciar APIs e configurar webhooks para eventos de cadastro, autenticação e Facial ID.

Como a verificação se encaixa no seu fluxo

Escolha o caminho de integração que corresponde à sua arquitetura e ao modelo de interação com o usuário.

A FACEIO oferece dois caminhos para verificação facial, dependendo de onde a verificação precisa ocorrer no seu sistema. O fluxo do navegador usa fio.js para interação com a câmera e captura ao vivo. A API REST é destinada a serviços de backend que já possuem duas imagens faciais para comparar. Para um pop-up no navegador que combina a captura de um documento de identidade com uma selfie ao vivo, consulte o FACEIO ID Match. Para entender o conceito, compare com fluxos de verificação facial online.

SDK baseado no navegador

Adequado quando a verificação ocorre em um ponto de interação no qual o usuário está fisicamente presente.

fio.js gerencia a interface da câmera e a captura ao vivo
Ideal para onboarding KYC e recuperação de conta
O backend verifica o payload e toma a decisão

API REST direta

Adequado para fluxos exclusivamente de backend nos quais as imagens já estão disponíveis no seu servidor.

Chamadas diretas ao endpoint /faceverify do endpoint
Útil para comparação de imagens no backend e verificações de documentos de identidade
Não requer uma sessão ativa no navegador

Entradas da API e sinais de verificação

O endpoint faceverify aceita uma requisição POST com sua chave de API e duas imagens, como data URIs Base64 ou URLs publicamente acessíveis. Cada imagem deve conter um único rosto. Se a entrada contiver vários rostos, extraia o rosto-alvo antes de enviar a requisição.

Entradas da requisição

Parâmetro	Descrição
`key`	A chave da API REST da sua aplicação. Envie este valor somente pelo seu backend; não a exponha no código do cliente.
`src`	A imagem de origem como data URI Base64 ou URL publicamente acessível. Normalmente, uma foto de documento de identidade ou uma selfie verificada anteriormente.
`target`	A imagem-alvo a ser comparada com a origem, como data URI Base64 ou URL publicamente acessível.

Saídas da resposta

Campo	Tipo	Descrição
`status`	Integer	Código de status HTTP; `200` indica que a requisição foi processada com sucesso.
`same_person`	Boolean	`true` se as duas imagens corresponderem, `false` se não corresponderem.
`dist`	Float	Métrica de distância entre 0 e 1. Um valor maior indica uma correspondência mais forte.
`sim`	Float	Pontuação de similaridade de cosseno entre os dois vetores de características faciais.

Dica de implementação: Para fluxos sensíveis, use os valores dist e sim juntos para calibrar o limite de correspondência na lógica de decisão, em vez de depender apenas do valor booleano binário same_person booleano. Alinhe os limites à sua política documentada e revise Boas práticas de segurança.

Padrões de implementação

1. Onboarding web com captura no navegador (KYC)

Em um fluxo no estilo KYC, o usuário faz uma captura facial ao vivo no navegador durante o cadastro. Seu backend fornece essa captura e uma imagem de referência de uma digitalização de documento anterior e chama faceverify para compará-las. A resposta é uma entrada técnica para a política de onboarding, nova tentativa ou revisão manual controlada pelo cliente; ela não autentica o documento nem conclui verificações KYC ou AML.

                         backend_verify.py 
                      

                        # Python: chamada de verificação no backend
import requests, base64

def encode_image(path):
    with open(path, 'rb') as f:
        return 'data:image/jpeg;base64,' + base64.b64encode(f.read()).decode()

payload = {
    'key': 'YOUR_API_KEY',
    'src': encode_image('id_document.jpg'),   # reference
    'target': encode_image('live_selfie.jpg') # live capture
}

result = requests.post('https://api.faceio.net/faceverify', json=payload).json()

# Exemplo de resposta
# {
#     "status": 200,
#     "same_person": true,
#     "dist": 0.97,
#     "sim": 0.94
# }
                      

2. Decisão no backend com limites de confiança

Seu backend pode ler os campos documentados da resposta e encaminhar a requisição conforme os limites e as regras de revisão definidos para seu caso de uso. Teste essas regras com seus próprios dados e requisitos, sem tratar um limite de exemplo como universal. Esse padrão pode contribuir para controles de fintech e eKYC.

Alta confiança

Aplique a política de continuação definida e testada pela sua organização.

Confiança limítrofe

Encaminhe resultados de baixa confiança para uma fila de revisão manual em vez de rejeitá-los automaticamente.

Baixa confiança

Solicite nova tentativa, outro fator ou revisão conforme sua política.

3. Recuperação de conta sem credenciais

O usuário solicita acesso a uma conta e envia uma nova selfie por uma página de recuperação. Seu backend a compara com a imagem de referência mantida para essa conta.

Trate o resultado da comparação facial como um sinal de recuperação. Seu backend também deve aplicar os controles necessários de conta, dispositivo, sessão, novas tentativas e suporte antes de restaurar o acesso.

Boas práticas de segurança e privacidade

A API de verificação facial processa transitoriamente imagens faciais sensíveis em cada comparação. Sua aplicação continua responsável por avisos, consentimento, validação de entrada, sua própria política de retenção e decisões finais sobre a conta. Use as práticas a seguir em toda integração:

Mantenha sua chave de API privada.
O endpoint faceverify deve ser chamado somente pelo seu backend. Sua chave de API autentica a requisição e não deve aparecer em código do navegador, bundles móveis, analytics ou logs.
Sempre encaminhe pelo seu backend.
As requisições de verificação feitas diretamente do navegador ignoram sua camada de validação no servidor e não podem ser consideradas confiáveis.
Minimize a retenção de imagens.
A FACEIO processa ambas as imagens em memória e as descarta depois que o resultado é gerado. Sua aplicação deve manter imagens faciais somente quando o fluxo, a política e a base legal exigirem.
Registre os resultados da verificação para sua trilha de auditoria.
Se precisar de uma trilha de auditoria, seu backend deve registrar o resultado, o timestamp, o contexto da requisição e os identificadores internos relevantes quando a resposta for recebida. Evite registrar imagens brutas ou chaves de API.
Forneça avisos e obtenha consentimento quando necessário.
Seu fluxo de onboarding ou recuperação deve explicar por que a verificação facial é usada, quais dados são processados e como os usuários podem solicitar exclusão ou acesso alternativo. Revise Boas práticas de privacidade e a Central de confiança.

Conclusão

A API de Verificação Facial da FACEIO oferece ao seu backend uma forma clara e chamável de comparar duas imagens faciais. Você fornece as imagens e o limite de decisão; a API retorna os sinais de verificação e a lógica da sua aplicação controla a decisão final. Para um fluxo de captura ao vivo no navegador com verificações de vivacidade, use verificação facial online. Para digitalização de documentos e correspondência de selfie em um único widget, use ID Match. Próximos passos: consulte Guias para desenvolvedores, o endpoint FACEVERIFY, e Boas práticas de segurança.

Guias relacionados

Conecte a API de Verificação Facial

Crie uma aplicação FACEIO, mantenha a chave da API REST no seu backend e use a referência oficial do endpoint para comparar imagens de origem e alvo no seu fluxo de identidade.

Abrir o FACEIO Console Referência da API REST

Chave de API exclusiva do backend

Processamento transitório

Integração orientada por políticas