Users

Cadastrar ou atualizar enrollment biométrico

Registra ou atualiza a imagem de referência biométrica de um usuário. A imagem deve ser enviada em base64 (JPEG). O enrollment é versionado — cada chamada incrementa a versão.

Fontes de enrollment

  • ORGANIZATION_PROVIDED (padrão): foto vinda dos registros da organização — crachá, ficha de RH. O antigo BANK_PROVIDED continua aceito e é normalizado na gravação.
  • FIRST_LIVENESS: Imagem capturada na primeira sessão de liveness.
  • DOCUMENT_PHOTO: Foto de documento (CNH/RG/passaporte). O rosto é extraído automaticamente. Requer a feature flag documentExtractionEnabled habilitada no tenant.

CPF obrigatório

O campo cpf é obrigatório e utilizado para vincular o enrollment à identidade do titular.

Requer scope transactions:write.

put/v1/users/{userExternalId}/enrollment

Request

  • Base URL: https://api.signdocs.com.br
  • URL: https://api.signdocs.com.br/v1/users/{userExternalId}/enrollment
  • Auth: HTTP bearer

Path parameters

userExternalIdstring required

Identificador externo do usuário no sistema do integrador.

Request body

dryRunboolean

Inspeciona sem gravar. Devolve o mesmo veredito que o endpoint de lote — usable / marginal / rejected com as métricas — e não persiste nada: nenhuma imagem no S3, nenhum registro, e o prazo de 90 dias não começa a correr.

Mesma função dos dois lados, de propósito: uma foto não pode ser julgada de um jeito no lote e de outro aqui.

imagestring byte required

Imagem facial de referência codificada em base64 (JPEG).

cpfstring required

CPF do titular (11 dígitos, sem pontuação).

source'ORGANIZATION_PROVIDED' | 'FIRST_LIVENESS' | 'DOCUMENT_PHOTO' | 'BANK_PROVIDED'

Origem da imagem de enrollment — quem responde por aquele rosto e se o titular estava presente na captura. É o que separa, numa auditoria anos depois, a foto que a organização entregou da captura ao vivo e da que veio de um documento oficial.

  • ORGANIZATION_PROVIDED (padrão): foto vinda dos registros da própria organização — crachá, ficha de RH, folha. O titular não estava presente; quem responde pela imagem é a organização.
  • FIRST_LIVENESS: imagem capturada na primeira sessão de liveness do titular. Captura ao vivo, com o titular presente.
  • DOCUMENT_PHOTO: foto de documento (CNH/RG/passaporte). O rosto é extraído automaticamente. Requer documentExtractionEnabled.

BANK_PROVIDED continua aceito como sinônimo de ORGANIZATION_PROVIDED e é normalizado na gravação — o valor devolvido e o que vai para a evidência são sempre o canônico. O nome antigo é de quando o único cliente era um banco; quem cadastra operadores de fábrica não deveria precisar enviá-lo.

Example request

{
  "cpf": "12345678901",
  "source": "ORGANIZATION_PROVIDED"
}

Response

Enrollment realizado com sucesso.

userExternalIdstring required
enrollmentHashstring required

Hash SHA-256 da imagem de enrollment (face crop quando DOCUMENT_PHOTO).

enrollmentVersioninteger required

Versão do enrollment (incrementada a cada atualização).

enrollmentSource'BANK_PROVIDED' | 'FIRST_LIVENESS' | 'DOCUMENT_PHOTO' required

Origem do enrollment.

enrolledAtstring date-time required
cpfstring required

CPF do titular.

faceConfidencenumber required

Confiança da detecção facial (0-100%).

documentImageHashstring

Hash SHA-256 do documento original. Presente apenas quando enrollmentSource é DOCUMENT_PHOTO.

referenceQuality'usable' | 'marginal' | 'rejected'

A foto serve como referência? É este o campo a ler — não deduza do array warnings.

usable limpa; marginal guardou normalmente mas é referência fraca; rejected não seria guardada. Numa gravação bem-sucedida só aparecem usable e marginal.

Deliberadamente não é o status: no lote, status diz o que aconteceu com a gravação (enrolled/failed), que é outra pergunta. Uma foto ruim que gravou bem é status: enrolled com referenceQuality: marginal — e é essa a combinação que interessa.

É o mesmo campo que o dryRun devolve, então um único trecho de código julga a foto tenha ela vindo de qual chamada for.

faceCoveragenumber double

Área do rosto como fração do quadro (0-1).

warningsstring[]

Ressalvas de qualidade. Vêm também numa gravação bem-sucedida — a foto é guardada de qualquer jeito, e é melhor saber que ela é fraca agora do que por uma assinatura reprovada daqui a três meses. Array vazio quando não há ressalva.

extractionConfidencenumber

Confiança da extração facial do documento. Presente apenas quando enrollmentSource é DOCUMENT_PHOTO.

Example response

{
  "faceConfidence": 99.8,
  "faceCoverage": 0.4318
}

Changes

No recorded changes to this operation across all 1 revision of this API.