Steps

Concluir etapa de verificação

Submete os dados para conclusão de uma etapa de verificação. O corpo da requisição varia conforme o tipo da etapa:

  • BIOMETRIC_LIVENESS / BIOMETRIC_MATCH: { "livenessSessionId": "..." }
  • BIOMETRIC_MATCH com referência por transação: { "referenceImage": { "source": "BASE64_IMAGE", "data": "<base64>" } } — compara o liveness com a imagem enviada em vez do enrollment do usuário. Requer a flag perTransactionReferenceEnabled no tenant. Exclusivo deste endpoint: em sessões de assinatura, a imagem por transação é enviada em referenceImage.content na criação da sessão.
  • OTP_VERIFY: { "code": "123456" }
  • CLICK_ACCEPT: { "accepted": true }
  • DOCUMENT_PHOTO_MATCH: { "documentImage": "<base64>", "documentType": "CNH" } — Envia a foto do documento (base64, máx. 5MB). O tipo aceito é RG, CNH, PASSPORT ou OTHER. A face é extraída e comparada com a referência biométrica. Retorna similarity score.
  • SERPRO_IDENTITY_CHECK: { "cpf": "12345678901", "name": "João da Silva", "birthDate": "1990-01-15" } — Valida identidade via SERPRO DataValid. Disponível apenas quando o tenant possui serpro.enabled.
  • DIGITAL_SIGN_A1: Não requer corpo (use o fluxo /signing).

Geolocalização condicional

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: { "latitude": -23.5505, "longitude": -46.6333 }.

Requer scope steps:write.

post/v1/transactions/{transactionId}/steps/{stepId}/complete

Request

  • Base URL: https://api.signdocs.com.br
  • URL: https://api.signdocs.com.br/v1/transactions/{transactionId}/steps/{stepId}/complete
  • Auth: HTTP bearer

Path parameters

transactionIdstring required

Identificador único da transação.

stepIdstring required

Identificador único da etapa.

Request body

livenessSessionIdstring

ID da sessão de prova de vida (para etapas biométricas).

sandboxBrightnessnumber double

Brilho simulado da captura, para ensaiar a reprovação por qualidade (DOCUMENT_QUALITY_LOW). Mesmo enquadramento do sandboxSimilarity: só vale em sandbox.

Antes destes campos as ramificações de sandbox fixavam 80/80 e nunca avaliavam o piso de qualidade — ou seja, o erro que mais aparece em campo (luz ruim, reflexo no visor, sujeito em movimento) era o único que o integrador não conseguia reproduzir sob demanda.

sandboxSharpnessnumber double

Nitidez simulada da captura. Ver sandboxBrightness.

sandboxLivenessConfidencenumber double

Confiança de liveness simulada, para ensaiar a reprovação. Mesmo enquadramento do sandboxSimilarity: só vale em sandbox, e nunca aprova uma verificação real.

Substitui o truque antigo de escrever fail no livenessSessionId, que só produzia 99.5 ou 30.0 — nenhum dos dois perto do limiar, que é justamente onde as capturas reais caem. A convenção antiga continua valendo quando nada é informado.

sandboxSimilaritynumber double

Similaridade simulada para as etapas BIOMETRIC_MATCH e DOCUMENT_PHOTO_MATCH em sandbox, usada para exercitar o caminho de reprovação. Padrão 99.5, que aprova; abaixo do limiar do tenant, a etapa reprova como reprovaria em produção.

Só é lida com credenciais de sandbox (credentialMode: SANDBOX) e quando não existe frame real de liveness. Se houve captura real, a comparação real acontece e este campo é ignorado — ele nunca faz uma comparação real passar. Um valor fora de 0-100 ou não numérico retorna 400.

No fluxo de sessões de assinatura, o equivalente é metadata.sandboxSimilarity na criação da sessão (ou sandboxSimilarity no corpo do advance, em integrações headless).

codestring

Código OTP de 6 dígitos (para etapa OTP_VERIFY).

acceptedboolean

Aceite do termo (para etapa CLICK_ACCEPT).

documentImagestring byte

Foto do documento codificada em base64 (máx. 5MB). Para etapa DOCUMENT_PHOTO_MATCH.

documentType'RG' | 'CNH' | 'PASSPORT' | 'OTHER'

Tipo do documento enviado.

cpfstring

CPF do signatário (para etapa SERPRO_IDENTITY_CHECK).

namestring

Nome completo (para etapa SERPRO_IDENTITY_CHECK).

birthDatestring date

Data de nascimento no formato YYYY-MM-DD (para etapa SERPRO_IDENTITY_CHECK).

Example request

{
  "sandboxBrightness": 15,
  "sandboxSharpness": 10,
  "sandboxLivenessConfidence": 79,
  "sandboxSimilarity": 40,
  "code": "123456",
  "cpf": "12345678901",
  "birthDate": "1990-01-15",
  "geolocation": {
    "latitude": -23.5505,
    "longitude": -46.6333
  }
}

Response

Etapa concluída (ou falhou). Verifique o campo status na resposta.

stepIdstring required
type'CLICK_ACCEPT' | 'OTP_CHALLENGE' | 'OTP_VERIFY' | 'BIOMETRIC_LIVENESS' | 'BIOMETRIC_MATCH' | 'DOCUMENT_PHOTO_MATCH' | 'SERPRO_IDENTITY_CHECK' | 'DIGITAL_SIGN_A1' | 'PURPOSE_DISCLOSURE' required

Tipos de etapa de verificação de identidade. Em policy.customSteps a ordem é validada na criação: BIOMETRIC_MATCH, SERPRO_IDENTITY_CHECK e DOCUMENT_PHOTO_MATCH exigem BIOMETRIC_LIVENESS antes de si, OTP_CHALLENGE e OTP_VERIFY vêm sempre em par e nessa ordem, e DIGITAL_SIGN_A1 tem de ser a última etapa.

status'PENDING' | 'STARTED' | 'COMPLETED' | 'FAILED' | 'SKIPPED' | 'DORMANT' required

Status possíveis de uma etapa. SKIPPED e DORMANT aparecem nos perfis com fallback: a etapa dormente é criada junto com a transação e só entra em PENDING se a etapa que ela substitui for pulada.

attemptsinteger required

Número de tentativas realizadas.

Example response

{
  "result": {
    "digitalSignature": {
      "algorithm": "SHA256withRSA",
      "signatureTimestamp": {
        "genTime": "2026-10-05T19:58:39.066Z",
        "tsaName": "C=BR, O=ICP-Brasil, OU=Certificado Carimbo de Tempo, CN=SERVIDOR DE CARIMBO DE TEMPO ACT SERPRO 50103",
        "serial": "78F42C1F9B1D36B9",
        "policyOid": "2.16.76.1.6.2"
      }
    }
  }
}

Changes

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