Guias de Desenvolvimento

Signing Sessions

Guias dos SDKs

Enrollment Biométrico

Cadastre imagens de referência facial para verificação biométrica em transações futuras.

Visão Geral

O enrollment biométrico permite pré-cadastrar a imagem de referência facial de um usuário. Essa imagem é utilizada nas etapas BIOMETRIC_MATCH e DOCUMENT_PHOTO_MATCH para comparar o rosto capturado em tempo real com a referência armazenada.

O enrollment é versionado — cada chamada incrementa a versão, permitindo atualizar a foto de referência sem perder o histórico.

Endpoint

PUT /v1/users/{userExternalId}/enrollment
Content-Type: application/json
Authorization: Bearer {access_token}

Campos da Requisição

Campo Tipo Obrigatório Descrição
image string (base64) Sim Imagem facial em base64 (JPEG). Para DOCUMENT_PHOTO, envie a foto completa do documento.
cpf string Sim CPF do titular (11 dígitos, sem pontuação). Vincula o enrollment à identidade do usuário.
source string Não Origem da imagem. Padrão: BANK_PROVIDED.

Fontes de Enrollment

1. BANK_PROVIDED (padrão)

Selfie ou foto fornecida diretamente pelo banco/integrador. A imagem deve conter exatamente um rosto visível.

curl -X PUT "$BASE_URL/v1/users/usr_maria_001/enrollment" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "'$(base64 -w0 selfie.jpg)'",
    "cpf": "12345678909",
    "source": "BANK_PROVIDED"
  }'

2. FIRST_LIVENESS

Imagem capturada na primeira sessão de liveness do usuário. Útil quando o banco não possui foto prévia e deseja utilizar a primeira verificação facial como referência.

curl -X PUT "$BASE_URL/v1/users/usr_maria_001/enrollment" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "'$(base64 -w0 liveness-frame.jpg)'",
    "cpf": "12345678909",
    "source": "FIRST_LIVENESS"
  }'

3. DOCUMENT_PHOTO

Foto de documento de identidade (CNH, RG ou passaporte). O sistema extrai automaticamente a face do documento e a utiliza como imagem de enrollment.

Feature flag requerida: Esta fonte requer que a flag documentExtractionEnabled esteja habilitada no tenant. Solicite a ativação ao seu gerente de conta. 
curl -X PUT "$BASE_URL/v1/users/usr_maria_001/enrollment" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "'$(base64 -w0 cnh-frente.jpg)'",
    "cpf": "12345678909",
    "source": "DOCUMENT_PHOTO"
  }'

Neste fluxo, o servidor:

  1. Recebe a foto completa do documento
  2. Detecta e extrai a face do documento via DetectFaces
  3. Valida que exatamente um rosto foi encontrado
  4. Armazena a face extraída (crop) como imagem de enrollment
  5. Retorna os campos adicionais documentImageHash e extractionConfidence

Campos da Resposta

Campo Tipo Descrição
userExternalId string Identificador externo do usuário.
enrollmentHash string Hash SHA-256 da imagem de enrollment (face crop quando DOCUMENT_PHOTO).
enrollmentVersion integer Versão do enrollment (incrementada a cada atualização).
enrollmentSource string Origem do enrollment: BANK_PROVIDED, FIRST_LIVENESS ou DOCUMENT_PHOTO.
enrolledAt string (ISO 8601) Data/hora do enrollment.
cpf string CPF do titular.
faceConfidence number Confiança da detecção facial (0-100%).
documentImageHash string Hash SHA-256 do documento original. Presente apenas quando enrollmentSource é DOCUMENT_PHOTO.
extractionConfidence number Confiança da extração facial do documento (0-100%). Presente apenas quando enrollmentSource é DOCUMENT_PHOTO.

Exemplo de resposta (BANK_PROVIDED)

{
  "userExternalId": "usr_maria_001",
  "enrollmentHash": "a1b2c3d4e5f6...",
  "enrollmentVersion": 1,
  "enrollmentSource": "BANK_PROVIDED",
  "enrolledAt": "2026-02-28T10:30:00.000Z",
  "cpf": "12345678909",
  "faceConfidence": 99.8
}

Exemplo de resposta (DOCUMENT_PHOTO)

{
  "userExternalId": "usr_maria_001",
  "enrollmentHash": "f6e5d4c3b2a1...",
  "enrollmentVersion": 2,
  "enrollmentSource": "DOCUMENT_PHOTO",
  "enrolledAt": "2026-02-28T10:35:00.000Z",
  "cpf": "12345678909",
  "faceConfidence": 98.5,
  "documentImageHash": "9a8b7c6d5e4f...",
  "extractionConfidence": 97.2
}

Validação de Qualidade Facial

Todas as imagens passam por validação via DetectFaces para garantir:

Caso a validação falhe, a API retorna 422 Unprocessable Entity com o motivo específico.

Erros Comuns

Código Tipo Causa Solução
400 Bad Request Campo image ou cpf ausente/inválido Verifique se ambos os campos obrigatórios estão presentes e no formato correto
422 Unprocessable Entity Nenhum rosto detectado na imagem ou mais de um rosto Envie uma imagem com exatamente um rosto visível e bem iluminado
422 Feature Not Enabled source: "DOCUMENT_PHOTO" sem documentExtractionEnabled Solicite a ativação da feature flag ao gerente de conta
401 Unauthorized Token inválido ou expirado Obtenha um novo token via POST /oauth2/token

Boas Práticas