Documentação FaceAuth

Bem-vindo à documentação técnica do FaceAuth. Aqui você encontra tudo para integrar verificação facial com IA ao seu produto em minutos.

O que é o FaceAuth?

FaceAuth é uma API de verificação de identidade por biometria facial com IA. Com ela você pode:

Verificar idade — estimativa de idade por reconhecimento facial em tempo real
KYC de documentos — extração de dados de RG, CNH, Passaporte e CPF com IA Vision
Login por selfie — autenticação de retorno dos seus usuários por reconhecimento facial
Detecção de liveness — detecta se é uma pessoa real (anti-spoofing)

URL Base da API

https://facebio.goodbits.tech/api/v1

Autenticação

Todas as requisições à API exigem uma chave de API enviada no header X-API-Key.

📍 Onde obter sua chave Acesse o painel do cliente → Chaves de API para gerar e gerenciar suas chaves.

# Exemplo com curl
curl -X POST https://facebio.goodbits.tech/api/v1/sessions/create \
  -H "X-API-Key: fa_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "callback_url": "https://seusite.com/callback" }'

Formato da chave

Chaves de API seguem o formato fa_<prefixo>_<hash>. Guarde sua chave em segurança — ela não pode ser recuperada após criação, apenas revogada e recriada.

Quickstart — 5 minutos

Integração mais rápida usando o SDK JavaScript em modo popup:

1. Backend — criar sessão

// PHP (Laravel)
use Illuminate\Support\Facades\Http;

$response = Http::withHeaders(['X-API-Key' => $suaChave])
    ->post('https://facebio.goodbits.tech/api/v1/sessions/create', [
        'callback_url' => 'https://seusite.com/callback?user_id=' . $userId,
        'metadata'     => ['user_id' => $userId],
    ]);

$token = $response->json('token');
// Passe $token para o frontend

2. Frontend — carregar o SDK

<!-- Adicione no <head> -->
<script src="https://facebio.goodbits.tech/sdk/faceauth.js"></script>

<script>
  FaceAuth.init({
    token:    '{{ $token }}',     // token gerado no backend
    apiKey:   'fa_prefix_...',   // prefixo público da chave
    mode:     'popup',
    onSuccess: (result) => {
      console.log('Aprovado!', result.jwt);
    },
    onError: (err) => {
      console.error(err);
    }
  });
</script>

3. Resultado no callback

// GET https://seusite.com/callback?faceauth_jwt=xxx&faceauth_status=approved

// PHP — validar o JWT retornado
$jwt     = $request->query('faceauth_jwt');
$status  = $request->query('faceauth_status'); // 'approved' | 'rejected'

$payload = Http::withHeaders(['X-API-Key' => $suaChave])
    ->post('https://facebio.goodbits.tech/api/v1/sessions/validate', ['token' => $jwt])
    ->json();

// $payload['age_estimate'], $payload['liveness_score'], etc.

SDK JavaScript — Instalação

O SDK FaceAuth é um arquivo JavaScript standalone — sem dependências, sem npm necessário.

Via tag <script> (recomendado)

<script src="https://facebio.goodbits.tech/sdk/faceauth.js"></script>

✅ Sem dependências externas O SDK não requer jQuery, React, Vue ou qualquer outro framework. Funciona em qualquer página HTML.

Modos de Integração

O FaceAuth suporta três modos de integração, cada um adequado a um cenário diferente:

Modo	Descrição	Ideal para
`popup`	Abre uma janela modal sobre o seu site	Sites com SPA ou fluxo inline
`redirect`	Redireciona o usuário para a página hospedada FaceAuth	Sites tradicionais, simplicidade máxima
`iframe`	Incorpora o widget em um <iframe> existente	Fluxos customizados em checkout

Modo Popup

FaceAuth.init({
  token:     'SESSION_TOKEN',
  apiKey:    'fa_prefix',
  mode:      'popup',
  onSuccess: (r) => console.log(r),
  onError:   (e) => console.error(e),
});

Modo Redirect

FaceAuth.init({
  token:   'SESSION_TOKEN',
  apiKey:  'fa_prefix',
  mode:    'redirect',
  // O usuário será redirecionado automaticamente
  // Resultado chega via callback_url
});

Modo iFrame

<div id="faceauth-container"></div>

FaceAuth.init({
  token:       'SESSION_TOKEN',
  apiKey:      'fa_prefix',
  mode:        'iframe',
  containerId: 'faceauth-container',
  onSuccess:   (r) => console.log(r),
});

Opções de Configuração

Opção	Tipo	Obrigatório	Descrição
`token`	string	✅	Token de sessão gerado via `POST /api/v1/sessions/create`
`apiKey`	string	✅	Prefixo público da sua chave de API (formato `fa_prefix`)
`mode`	string	✅	`popup` \| `redirect` \| `iframe`
`lang`	string	❌	Idioma da interface: `pt_BR` (padrão) \| `en` \| `es`
`containerId`	string	❌	ID do elemento para modo `iframe`
`onSuccess`	function	❌	Callback chamado após aprovação/rejeição
`onError`	function	❌	Callback chamado em caso de erro técnico

Eventos & Callbacks

onSuccess

Chamado quando a verificação é concluída (aprovada ou rejeitada).

FaceAuth.init({
  // ...
  onSuccess: (result) => {
    // result.status      → 'approved' | 'rejected'
    // result.jwt         → token JWT RS256 assinado
    // result.session_id  → UUID da sessão
    // result.approved    → boolean
    console.log(result.status);
  }
});

postMessage (para iframe)

Em modo iframe, o resultado também é emitido via window.postMessage:

window.addEventListener('message', (event) => {
  if (event.data.source === 'faceauth') {
    const { status, jwt, session_id } = event.data;
    // processar resultado
  }
});

API — Criar Sessão

Cria uma sessão de verificação que será usada pelo SDK JavaScript.

POST /api/v1/sessions/create

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
`callback_url`	string	❌	URL para redirect após verificação (modo redirect)
`metadata`	object	❌	Dados extras (ex: `user_id`) retornados no JWT e webhook
`expires_in`	integer	❌	Validade em minutos (padrão: 30, máx: 1440)

Resposta

{
  "token":       "uuid-da-sessao",
  "session_url": "https://facebio.goodbits.tech/sdk/verify/uuid-da-sessao",
  "expires_at":  "2026-03-19T14:00:00Z"
}

API — Status da Sessão

GET /api/v1/sessions/{token}

{
  "token":          "uuid-da-sessao",
  "status":         "approved",
  "liveness_score": 0.94,
  "age_estimate":   24,
  "approved":       true,
  "metadata":       { "user_id": 42 },
  "processed_at":   "2026-03-19T13:58:12Z"
}

Status possíveis: pending · approved · rejected · error · expired

API — Verificar (envio direto de imagem)

Envia uma imagem em base64 diretamente para verificação, sem criar sessão. Útil para integrações backend-to-backend.

POST /api/v1/verify

{
  "image":    "data:image/jpeg;base64,...",  // base64 da selfie
  "metadata": { "user_id": 42 }              // opcional
}

Resposta

{
  "status":         "approved",
  "approved":       true,
  "liveness_score": 0.91,
  "age_estimate":   28,
  "jwt":            "eyJhbGciOiJSUzI1NiJ9...",
  "session_id":     "uuid-da-sessao"
}

API — KYC de Documentos

Extrai dados de documentos (RG, CNH, Passaporte, CPF) e opcionalmente compara a foto do documento com uma selfie.

⚠️ Disponível a partir do plano Starter O serviço KYC de documentos precisa estar habilitado no seu painel em Serviços.

POST /api/v1/sessions/create → Use a sessão KYC hospedada

Para KYC completo (documento + selfie + face match), utilize a sessão KYC hospedada:

$response = Http::withHeaders(['X-API-Key' => $suaChave])
    ->post('https://facebio.goodbits.tech/api/v1/kyc/session', [
        'callback_url'           => 'https://seusite.com/kyc/callback',
        'metadata'               => ['user_id' => $userId],
        'allowed_document_types' => ['rg', 'cnh'], // opcional
        'lang'                   => 'pt_BR',
    ]);

$sessionUrl = $response->json('session_url');
// Redirecionar o usuário para $sessionUrl

O usuário passa pelo wizard hospedado (foto do documento + selfie), e ao final é redirecionado para o callback_url com ?kyc_jwt=xxx.

Dados extraídos (retornados no JWT)

Campo	Fonte
`name`	IA Vision (documento)
`birth_date`	IA Vision (documento)
`document_number`	IA Vision (documento)
`cpf`	IA Vision (documento)
`expiry`	IA Vision (documento)
`face_matched`	FaceAuth Engine (comparação)
`face_match_score`	FaceAuth Engine (0.0 – 1.0)

API — Validar JWT

Valida e decodifica um JWT retornado pelo FaceAuth. Use isto no seu backend para verificar autenticidade do token.

POST /api/v1/sessions/validate

{ "token": "eyJhbGciOiJSUzI1NiJ9..." }

Resposta (JWT decodificado)

{
  "valid":          true,
  "session_id":     "uuid",
  "status":         "approved",
  "liveness_score": 0.94,
  "age_estimate":   24,
  "metadata":       { "user_id": 42 },
  "issued_at":      1742390292,
  "expires_at":     1742476692
}

Webhooks — Configuração

⚠️ Disponível nos planos Starter, Pro e Enterprise Webhooks não estão disponíveis no plano Free.

Configure sua URL de webhook no painel em Integração → Webhook. Você também pode definir um segredo para verificar a autenticidade das requisições via HMAC-SHA256.

Dica: use o botão "Testar Webhook" no painel para verificar se seu servidor está recebendo corretamente antes de entrar em produção.

Webhooks — Eventos

Evento	Quando é disparado
`verification.approved`	Verificação facial aprovada
`verification.rejected`	Verificação rejeitada (liveness baixo, menor de idade)
`verification.error`	Erro técnico na verificação
`kyc.approved`	Verificação KYC de documento aprovada
`kyc.rejected`	Verificação KYC rejeitada
`test`	Disparo manual via painel (teste de conectividade)

Webhooks — Payload & Assinatura

Headers enviados

X-FaceAuth-Signature: sha256=<hmac-sha256-hex>
X-FaceAuth-Event: verification.approved
Content-Type: application/json
User-Agent: FaceAuth-Webhooks/1.0

Payload

{
  "event":          "verification.approved",
  "timestamp":      "2026-03-19T14:00:00Z",
  "session_id":     "uuid-da-sessao",
  "status":         "approved",
  "liveness_score": 0.94,
  "age_estimate":   24,
  "metadata":       { "user_id": 42 },
  "jwt":            "eyJhbGciOiJSUzI1NiJ9...",
  "origin_domain":  "seusite.com",
  "processed_at":   "2026-03-19T13:59:58Z"
}

Verificar assinatura

// PHP
function verificarWebhook(string $payload, string $header, string $segredo): bool
{
    $esperado = 'sha256=' . hash_hmac('sha256', $payload, $segredo);
    return hash_equals($esperado, $header);
}

// Uso
$payload = file_get_contents('php://input');
$sig     = $_SERVER['HTTP_X_FACEAUTH_SIGNATURE'];
$ok      = verificarWebhook($payload, $sig, 'seu_segredo');

Webhooks — Exemplo de Handler (Laravel)

use Illuminate\Http\Request;

Route::post('/webhook/faceauth', function (Request $request) {
    $payload   = $request->getContent();
    $signature = $request->header('X-FaceAuth-Signature');
    $segredo   = config('services.faceauth.webhook_secret');

    if ('sha256=' . hash_hmac('sha256', $payload, $segredo) !== $signature) {
        return response('Unauthorized', 401);
    }

    $data  = $request->json()->all();
    $event = $data['event'];

    match ($event) {
        'verification.approved' => handleAprovado($data),
        'verification.rejected' => handleRejeitado($data),
        default                 => null,
    };

    return response()->json(['ok' => true]);
})->withoutMiddleware([\App\Http\Middleware\VerifyCsrfToken::class]);

JWT Payload — Referência

Todos os JWTs do FaceAuth são assinados com RS256 (RSA). Você pode verificar localmente usando a chave pública disponível em GET /api/v1/status.

Campo	Tipo	Descrição
`sub`	string	UUID da sessão
`client_id`	integer	ID do cliente FaceAuth
`status`	string	`approved` \| `rejected`
`liveness_score`	float\|null	Score de liveness (0.0 – 1.0)
`age_estimate`	integer\|null	Idade estimada em anos
`origin_domain`	string\|null	Domínio de origem da verificação
`metadata`	object	Dados passados em `createSession`
`iat`	unix timestamp	Emitido em
`exp`	unix timestamp	Expira em (24h após emissão)

Códigos de Erro

Código	HTTP	Descrição
`INVALID_API_KEY`	401	Chave de API inválida ou revogada
`QUOTA_EXCEEDED`	429	Limite mensal de verificações atingido
`SESSION_EXPIRED`	410	Token de sessão expirado
`SESSION_NOT_FOUND`	404	Token de sessão não encontrado
`NO_FACE_DETECTED`	422	Nenhum rosto detectado na imagem
`LIVENESS_FAILED`	422	Score de liveness abaixo do threshold
`AGE_BELOW_MINIMUM`	422	Idade estimada abaixo do mínimo configurado
`DOMAIN_NOT_ALLOWED`	403	Domínio de origem não autorizado para esta chave
`SERVICE_DISABLED`	403	Serviço não habilitado no plano atual

Rate Limits

Além do limite mensal de verificações por plano, aplicamos rate limiting por API Key:

Plano	Req/minuto (API)	Verificações/mês
Free	5	100
Starter	15	1.000
Pro	30	5.000
Enterprise	60+	50.000+

Quando o rate limit é atingido, a API retorna HTTP 429 com header Retry-After.

Planos & Limites

Recurso	Free	Starter	Pro	Enterprise
Verificações/mês	100	1.000	5.000	50.000+
SDK (popup/redirect/iframe)	✅	✅	✅	✅
API REST	✅	✅	✅	✅
Webhooks	❌	✅	✅	✅
KYC de Documentos	❌	✅	✅	✅
Login por Selfie	❌	❌	✅	✅
SLA & Suporte dedicado	❌	❌	❌	✅

💡 Gerenciar plano Acesse Faturamento no painel para fazer upgrade ou ver o uso atual.