Verificação de Identidade

Guia completo dos tipos de etapa de verificação de identidade disponíveis na API SignDocs Brasil.

Tipos de Etapa

Cada transação inclui uma ou mais etapas de verificação de identidade, determinadas pelo perfil de política (policyProfile) escolhido na criação. Os tipos disponíveis são:

Tipo	Descrição	Feature Flag
`CLICK_ACCEPT`	Aceite por clique em termo de uso	—
`OTP_CHALLENGE`	Envio de código OTP por e-mail	—
`OTP_VERIFY`	Verificação do código OTP	—
`BIOMETRIC_LIVENESS`	Prova de vida facial via Amazon Rekognition	—
`BIOMETRIC_MATCH`	Comparação facial com imagem de enrollment	—
`DOCUMENT_PHOTO_MATCH`	Extração e comparação facial com foto de documento	`documentExtractionEnabled`
`SERPRO_IDENTITY_CHECK`	Validação de identidade via SERPRO DataValid	`serpro.enabled`
`DIGITAL_SIGN_A1`	Assinatura digital com certificado ICP-Brasil A1	—

Perfis de Política

Cada perfil define um conjunto de etapas:

Perfil	Etapas incluídas
`CLICK_ONLY`	CLICK_ACCEPT
`CLICK_PLUS_OTP`	CLICK_ACCEPT, OTP_CHALLENGE, OTP_VERIFY
`BIOMETRIC`	BIOMETRIC_LIVENESS, BIOMETRIC_MATCH
`BIOMETRIC_PLUS_OTP`	BIOMETRIC_LIVENESS, BIOMETRIC_MATCH, OTP_CHALLENGE, OTP_VERIFY
`DIGITAL_CERTIFICATE`	CLICK_ACCEPT, DIGITAL_SIGN_A1
`CUSTOM`	Qualquer combinação via `customSteps`

Para incluir DOCUMENT_PHOTO_MATCH ou SERPRO_IDENTITY_CHECK, utilize o perfil CUSTOM com customSteps:

{
  "purpose": "DOCUMENT_SIGNATURE",
  "policy": {
    "profile": "CUSTOM",
    "customSteps": [
      "BIOMETRIC_LIVENESS",
      "DOCUMENT_PHOTO_MATCH",
      "SERPRO_IDENTITY_CHECK"
    ]
  },
  "signer": {
    "name": "Maria Silva Santos",
    "userExternalId": "usr_maria_001",
    "cpf": "12345678909",
    "email": "maria@exemplo.com.br"
  }
}

Fluxo OTP (Challenge + Verify)

O fluxo OTP utiliza duas etapas pareadas:

OTP_CHALLENGE — envia o código por e-mail
OTP_VERIFY — valida o código informado pelo usuário

Enviar o código

curl -X POST "$BASE_URL/v1/transactions/$TX_ID/steps/$OTP_CHALLENGE_STEP_ID/start" \
  -H "Authorization: Bearer $TOKEN"

Verificar o código

curl -X POST "$BASE_URL/v1/transactions/$TX_ID/steps/$OTP_VERIFY_STEP_ID/complete" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

Reenvio de OTP

Para reenviar o código OTP, basta chamar start novamente na etapa OTP_CHALLENGE. Quando attempts > 1:

Um novo código OTP é gerado e enviado
A etapa pareada OTP_VERIFY é automaticamente resetada se estiver em status FAILED ou STARTED
O usuário pode tentar novamente com o novo código sem intervenção manual

# Reenviar OTP (segunda tentativa)
curl -X POST "$BASE_URL/v1/transactions/$TX_ID/steps/$OTP_CHALLENGE_STEP_ID/start" \
  -H "Authorization: Bearer $TOKEN"
# A etapa OTP_VERIFY é automaticamente resetada

Document Photo Match

O tipo DOCUMENT_PHOTO_MATCH permite verificar a identidade do usuário comparando uma foto de documento de identidade com a referência biométrica armazenada.

Requer: Feature flag documentExtractionEnabled habilitada no tenant.

Fluxo

Inicie a etapa via POST .../steps/{stepId}/start
Envie a foto do documento no complete:

curl -X POST "$BASE_URL/v1/transactions/$TX_ID/steps/$STEP_ID/complete" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documentImage": "'$(base64 -w0 cnh-frente.jpg)'",
    "documentType": "CNH"
  }'

Tipos de documento aceitos

Valor	Documento
`RG`	Registro Geral
`CNH`	Carteira Nacional de Habilitação
`PASSPORT`	Passaporte
`OTHER`	Outro documento com foto

Resposta

O servidor extrai a face do documento, compara com a referência biométrica e retorna:

{
  "stepId": "01HWXYZ...",
  "type": "DOCUMENT_PHOTO_MATCH",
  "status": "COMPLETED",
  "result": {
    "documentPhotoMatch": {
      "similarity": 95.7,
      "documentType": "CNH",
      "extractionConfidence": 98.2
    }
  }
}

SERPRO Identity Check

O tipo SERPRO_IDENTITY_CHECK valida a identidade do usuário contra a base de dados governamental SERPRO DataValid.

Requer: Feature flag serpro.enabled habilitada no tenant.

Dados necessários

Campo	Tipo	Descrição
`cpf`	string	CPF do signatário (11 dígitos, sem pontuação)
`name`	string	Nome completo conforme cadastro
`birthDate`	string (date)	Data de nascimento no formato `YYYY-MM-DD`

curl -X POST "$BASE_URL/v1/transactions/$TX_ID/steps/$STEP_ID/complete" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cpf": "12345678909",
    "name": "Maria Silva Santos",
    "birthDate": "1990-01-15"
  }'

Resposta

{
  "stepId": "01HWXYZ...",
  "type": "SERPRO_IDENTITY_CHECK",
  "status": "COMPLETED",
  "result": {
    "serproIdentityCheck": {
      "verified": true,
      "cpfMatch": true,
      "nameMatch": true,
      "birthDateMatch": true
    }
  }
}

Geolocalização

Quando o tenant possui a flag biometricRequired habilitada, o campo geolocation é obrigatório para etapas biométricas:

BIOMETRIC_LIVENESS
BIOMETRIC_MATCH
DOCUMENT_PHOTO_MATCH

Formato

{
  "documentImage": "<base64>",
  "documentType": "CNH",
  "geolocation": {
    "latitude": -23.5505,
    "longitude": -46.6333
  }
}

Caso o campo esteja ausente quando obrigatório, a API retorna 422 com o tipo geolocation-required.

Erros Comuns

Código	Tipo	Causa
`409`	Conflict	Etapa já concluída ou transação em estado inválido
`422`	Feature Not Enabled	`SERPRO_IDENTITY_CHECK` sem `serpro.enabled` ou `DOCUMENT_PHOTO_MATCH` sem `documentExtractionEnabled`
`422`	Geolocation Required	Campo `geolocation` ausente em etapa biométrica com `biometricRequired` ativo
`422`	Unprocessable Entity	Nenhum rosto detectado na foto do documento ou dados SERPRO inválidos
`400`	Bad Request	Campos obrigatórios ausentes (`documentImage`, `cpf`, etc.)