ℹ️ Conteúdo em atualização

Estamos revisando estes procedimentos. Pessoas técnicas podem encontrar ajustes em códigos de erro ou mapeamentos de payload; valide com os logs e o OpenAPI mais recente. Pessoas não técnicas podem continuar usando o passo a passo e acionar o time de suporte caso algo pareça diferente do descrito.

🔐 CredFace - Venda com Biometria Facial

O CredFace é uma solução de venda com autenticação biométrica facial que adiciona uma camada extra de segurança às transações realizadas em pontos de venda (PDV), garantindo que apenas o titular do cartão possa realizar compras.

🎯 Visão Geral

O CredFace combina a tecnologia de biometria facial com o processo de venda, proporcionando:

• 🔒 Segurança Avançada: Validação biométrica do cliente antes de aprovar a transação
• ⚡ Processo Rápido: Autenticação em poucos segundos
• 🛡️ Prevenção de Fraudes: Redução significativa de transações fraudulentas
• ✅ Experiência do Usuário: Processo simples e intuitivo para o cliente

🏗️ Arquitetura da Solução

Componentes Necessários

A solução CredFace é composta por três elementos principais:

1. Hardware

• Webcam: Câmera com as mesmas configurações utilizadas no Credline
• Computador/PDV: Sistema operacional que suporte navegador Chrome 85 ou superior (versão atual: 124)

2. Integração de Software

• APIs de Pagamento: Integração do PDV com as APIs Credsystem
• Motor de Biometria: Sistema de captura e validação biométrica facial
• Navegador: Chrome 85+ para execução da WebView de biometria

3. Conectividade

• Internet: Conexão estável para comunicação com as APIs
• Certificados SSL: Comunicação segura com os servidores

🔄 Fluxo de Venda com Biometria

Passo a Passo

1. Início da Transação

O processo começa quando o cliente deseja realizar uma compra:

// Exemplo de início de transação
const iniciarVenda = async (dadosVenda) => {
  const response = await fetch('https://api.credsystem.com/v1/venda/pre-autorizacao', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      numeroCartao: dadosVenda.cartao,
      valorVenda: dadosVenda.valor,
      estabelecimento: dadosVenda.estabelecimentoId,
      requireBiometria: true
    })
  });
  
  const resultado = await response.json();
  
  if (resultado.requireBiometria) {
    // Abrir interface de captura biométrica
    abrirCapturaBiometria(resultado.tokenBiometria);
  }
};

2. Captura Biométrica

Quando a biometria é solicitada, o sistema abre a interface de captura:

const abrirCapturaBiometria = (tokenBiometria) => {
  // Abrir WebView de biometria
  const biometriaWindow = window.open(
    'https://biometria.credsystem.com/captura',
    'Biometria',
    'width=800,height=600'
  );
  
  // Escutar eventos da WebView
  window.addEventListener('message', (event) => {
    if (event.data.type === 'OnInit') {
      // WebView carregou, enviar configurações
      biometriaWindow.postMessage({
        type: 'OnInit',
        detail: {
          authorization: authToken,
          token: tokenBiometria,
          theme: {
            primaryColor: '#0066CC',
            buttonTextColor: '#FFFFFF'
          }
        }
      }, '*');
    }
    
    if (event.data.type === 'OnFinished') {
      // Biometria concluída
      processarResultadoBiometria(event.data.detail);
    }
    
    if (event.data.type === 'OnError') {
      // Erro na captura
      tratarErroBiometria(event.data.detail);
    }
  });
};

3. Validação e Conclusão

Após a captura, o sistema valida e finaliza a transação:

const processarResultadoBiometria = async (resultado) => {
  if (resultado.decision === 'APPROVED') {
    // Biometria aprovada, capturar venda
    await capturarVenda({
      preAutorizacaoId: preAuthId,
      biometriaJWT: resultado.jwt
    });
    
    exibirMensagem('Venda aprovada com sucesso!');
  } else if (resultado.decision === 'DENIED') {
    // Biometria negada
    await cancelarVenda(preAuthId);
    exibirErro('Biometria não reconhecida. Venda cancelada.');
  } else if (resultado.decision === 'CLOSE') {
    // Cliente fechou a janela
    await cancelarVenda(preAuthId);
    exibirErro('Processo cancelado pelo usuário.');
  }
};

📋 Requisitos Técnicos

Hardware Mínimo

Componente	Especificação
Webcam	Resolução mínima 720p (1280x720)
Processador	Intel Core i3 ou equivalente
Memória RAM	4 GB
Conexão Internet	Mínimo 5 Mbps (download/upload)

Software

Componente	Versão
Sistema Operacional	Windows 10+, Linux (Ubuntu 18.04+), macOS 10.14+
Navegador	Google Chrome 85+ (recomendado: versão 124+)
Certificados SSL	TLS 1.2 ou superior

APIs Necessárias

Para implementar o CredFace, você precisará integrar com:

1. API de Venda: Para criar pré-autorizações e capturar vendas
2. API de Biometria: Para validação facial
3. API de Autenticação: Para obter tokens de acesso

🔧 Configuração do PDV

1. Instalação da Webcam

Certifique-se de que a webcam está:

• Corretamente instalada e reconhecida pelo sistema operacional
• Posicionada em altura adequada para captura facial (nível dos olhos do cliente)
• Com boa iluminação frontal (evitar contraluz)

2. Configuração do Navegador

No Chrome, verifique as permissões:

// Solicitar permissões de câmera
navigator.mediaDevices.getUserMedia({ video: true })
  .then(stream => {
    console.log('Câmera autorizada');
    stream.getTracks().forEach(track => track.stop());
  })
  .catch(error => {
    console.error('Erro ao acessar câmera:', error);
  });

3. Integração com o Sistema de Venda

Adicione o módulo de biometria ao seu PDV:

// credface-module.js
export class CredFaceModule {
  constructor(config) {
    this.apiUrl = config.apiUrl;
    this.authToken = config.authToken;
    this.biometriaUrl = config.biometriaUrl;
  }
  
  async realizarVendaComBiometria(dadosVenda) {
    try {
      // 1. Criar pré-autorização
      const preAuth = await this.criarPreAutorizacao(dadosVenda);
      
      // 2. Capturar biometria
      const biometria = await this.capturarBiometria(preAuth.token);
      
      // 3. Finalizar venda
      if (biometria.decision === 'APPROVED') {
        return await this.capturarVenda(preAuth.id, biometria.jwt);
      } else {
        await this.cancelarVenda(preAuth.id);
        throw new Error('Biometria não aprovada');
      }
    } catch (error) {
      console.error('Erro na venda com biometria:', error);
      throw error;
    }
  }
}

🎨 Experiência do Usuário

Interface de Captura

A interface de captura biométrica deve:

1. Orientar o Cliente: Mostrar claramente onde posicionar o rosto
2. Feedback Visual: Indicar quando a face está corretamente posicionada
3. Mensagens Claras: Informar sobre o progresso e resultados
4. Design Responsivo: Adaptar-se a diferentes tamanhos de tela

Mensagens Recomendadas

• Aguardando: "Posicione seu rosto no centro da câmera"
• Capturando: "Aguarde, capturando imagem..."
• Validando: "Validando biometria..."
• Sucesso: "Biometria confirmada! ✓"
• Falha: "Não foi possível validar. Tente novamente."

🛡️ Segurança e Privacidade

Proteção de Dados

• Criptografia: Todas as imagens são criptografadas antes da transmissão
• Tokens JWT: Biometrias validadas retornam tokens assinados
• Não Armazenamento: Imagens biométricas não são armazenadas permanentemente
• LGPD Compliance: Conformidade com a Lei Geral de Proteção de Dados

Boas Práticas

// ✅ Correto: Usar HTTPS
const API_URL = 'https://api.credsystem.com';

// ❌ Incorreto: Não use HTTP
// const API_URL = 'http://api.credsystem.com';

// ✅ Correto: Limpar dados sensíveis após uso
const processarBiometria = async (data) => {
  try {
    const resultado = await validarBiometria(data);
    return resultado;
  } finally {
    // Limpar imagem da memória
    data = null;
  }
};

📊 Monitoramento e Logs

Eventos para Registrar

Registre os seguintes eventos para análise e troubleshooting:

const logEvent = (evento, detalhes) => {
  console.log({
    timestamp: new Date().toISOString(),
    evento: evento,
    detalhes: detalhes,
    pdv: pdvId,
    estabelecimento: estabelecimentoId
  });
};

// Exemplos de uso
logEvent('BIOMETRIA_INICIADA', { vendaId, valor });
logEvent('BIOMETRIA_APROVADA', { vendaId, tempo: tempoMs });
logEvent('BIOMETRIA_NEGADA', { vendaId, motivo });
logEvent('BIOMETRIA_ERRO', { vendaId, erro });

⚠️ Tratamento de Erros

Erros Comuns

Erro	Causa	Solução
Câmera não encontrada	Webcam desconectada ou sem permissão	Verificar conexão e permissões do navegador
Timeout na captura	Cliente demorou muito para posicionar	Reiniciar processo de captura
Biometria negada	Face não reconhecida	Permitir nova tentativa ou método alternativo
Erro de conexão	Falha na comunicação com API	Verificar internet e tentar novamente

Implementação de Retry

const capturarBiometriaComRetry = async (maxTentativas = 3) => {
  for (let tentativa = 1; tentativa <= maxTentativas; tentativa++) {
    try {
      const resultado = await capturarBiometria();
      return resultado;
    } catch (error) {
      console.error(`Tentativa ${tentativa} falhou:`, error);
      
      if (tentativa === maxTentativas) {
        throw new Error('Número máximo de tentativas excedido');
      }
      
      // Aguardar antes de tentar novamente
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
  }
};

📚 Documentação Relacionada

Para implementar completamente o CredFace, consulte também:

• Motor de Biometria - Documentação técnica do motor de biometria
• Acordos WebView - Padrões de comunicação e eventos
• API de Venda Loja - Endpoints de pré-autorização e captura
• Autenticação - Como obter tokens de acesso

🚀 Exemplo Completo

Aqui está um exemplo completo de integração:

// credface-integration.js
import { CredFaceModule } from './credface-module.js';

// Configuração
const credFace = new CredFaceModule({
  apiUrl: 'https://api.credsystem.com',
  biometriaUrl: 'https://biometria.credsystem.com',
  authToken: 'seu-token-aqui'
});

// Função principal de venda
const realizarVenda = async () => {
  try {
    // Dados da venda
    const dadosVenda = {
      cartao: '1234567890123456',
      valor: 150.00,
      estabelecimentoId: '12345',
      parcelas: 1
    };
    
    // Exibir loading
    mostrarLoading('Processando venda...');
    
    // Realizar venda com biometria
    const resultado = await credFace.realizarVendaComBiometria(dadosVenda);
    
    // Sucesso
    ocultarLoading();
    mostrarSucesso(`Venda aprovada! NSU: ${resultado.nsu}`);
    imprimirComprovante(resultado);
    
  } catch (error) {
    ocultarLoading();
    
    if (error.message.includes('Biometria não aprovada')) {
      mostrarErro('Biometria não reconhecida. Tente novamente ou use outro método de pagamento.');
    } else {
      mostrarErro(`Erro na venda: ${error.message}`);
    }
  }
};

// Iniciar venda ao clicar no botão
document.getElementById('btn-venda-biometria').addEventListener('click', realizarVenda);

💡 Dicas de Implementação

Performance

• Pré-carregar a WebView de biometria durante a inicialização do PDV
• Cache de tokens de autenticação para reduzir chamadas à API
• Otimizar o tamanho das imagens capturadas sem perder qualidade

Usabilidade

• Feedback imediato ao cliente durante todo o processo
• Opção alternativa caso a biometria falhe (senha, por exemplo)
• Tutorial rápido na primeira utilização do cliente

Conformidade

• Termo de consentimento antes da primeira captura
• Política de privacidade visível e acessível
• Registro de consentimentos para auditoria

🆘 Suporte

Para dúvidas ou problemas com o CredFace:

• 📧 Email: suporte.tecnico@credsystem.com.br
• 📞 Telefone: 0800-XXX-XXXX
• 💬 Chat: Disponível no portal do desenvolvedor
• 📖 Base de Conhecimento: https://docs.credsystem.com.br

---

Última atualização: Dezembro 2024