TrustSessions

Avançar etapa da sessão de confiança

Avança a Sessão de Confiança através de suas etapas (idêntico a /v1/signing-sessions/{id}/advance). Ações suportadas: accept, verify_otp, resend_otp, start_liveness, complete_liveness, prepare_signing, complete_signing (este último ainda é relevante quando o tenant exige carimbo ICP-Brasil A1 sobre o hash da ação para evidência reforçada).

Auto-finaliza na última etapa, gera o pacote de evidências (document: null, action preenchido).

Autenticação via embedToken (clientSecret).

post/v1/trust-sessions/{sessionId}/advance

Request

  • Base URL: https://api.signdocs.com.br
  • URL: https://api.signdocs.com.br/v1/trust-sessions/{sessionId}/advance
  • Auth: HTTP bearer

Path parameters

sessionIdstring required

Identificador único da sessão de confiança.

Request body

action'confirm_signer' | 'accept' | 'verify_otp' | 'resend_otp' | 'start_liveness' | 'complete_liveness' | 'prepare_signing' | 'complete_signing' | 'complete_document_photo' required

Ação a executar na sessão.

cpfCnpjstring

CPF ou CNPJ que o signatário digita para confirmar a própria identidade (obrigatório em confirm_signer). Comparado com o valor informado na criação da sessão; divergência reprova a etapa.

documentImagestring byte

Foto do documento de identidade em base64 (obrigatório em complete_document_photo). Máximo 5 MB. O rosto é extraído da imagem e comparado com a referência do cadastro.

documentTypestring

Tipo do documento enviado em documentImage.

otpCodestring

Código OTP de 6 dígitos (obrigatório para verify_otp).

otpChannel'email' | 'sms' | 'whatsapp' | 'telegram'

Canal de entrega do OTP, escolhido por signatário. Independente do canal usado para entregar o link de assinatura: um convite por WhatsApp pode ter OTP por e-mail, e um convite por e-mail pode ter OTP por WhatsApp.

sms e whatsapp exigem signer.phone e o canal habilitado para o tenant (sms.enabled / whatsapp.enabled); caso contrário o passo de OTP falha com 422. No WhatsApp, um número que pediu para não receber mensagens também falha com 422, com uma mensagem que orienta a escolher outro canal.

telegram exige telegram.enabled no tenant. O código chega pelo bot da SignDocs quando o signatário já registrou o próprio CPF nele; sem registro, é enviado por telefone (Telegram Gateway) se o tenant tiver essa opção habilitada, e caso contrário o passo falha com 422 de imediato. Ao criar a sessão, otpChannel: telegram ainda exige signer.email quando a política tem OTP.

Um OTP por WhatsApp ou pelo Telegram Gateway consome a cota de mensagens do tenant; esgotada, o envio é recusado com 429.

livenessSessionIdstring

ID da sessão Rekognition (obrigatório para complete_liveness).

certificateChainPemsstring[]

Cadeia de certificados PEM (obrigatório para prepare_signing).

signatureRequestIdstring

ID da requisição de assinatura (obrigatório para complete_signing).

rawSignatureBase64string byte

Assinatura bruta em base64 (obrigatório para complete_signing).

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 biométricas 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 quando a etapa já resolveu para sandbox — em HML, ou em tenants com mode: SANDBOX — e quando não existe frame real de liveness. Uma captura real sempre vence: a comparação real acontece e este campo é ignorado. Ou seja, ele nunca faz uma comparação real passar.

A página hospedada é quem chama o advance, então o caminho usual não é este campo, e sim metadata.sandboxSimilarity na criação da sessão. Envie aqui apenas em integrações headless, que chamam o advance diretamente; o corpo tem precedência sobre a metadata. Um valor fora de 0-100 ou não numérico retorna 400.

Example request

{
  "cpfCnpj": "11144477735",
  "documentType": "RG",
  "deviceInfo": {
    "language": "pt-BR",
    "platform": "Linux x86_64"
  },
  "otpCode": "123456",
  "sandboxBrightness": 15,
  "sandboxSharpness": 10,
  "sandboxLivenessConfidence": 79,
  "sandboxSimilarity": 40,
  "geolocation": {
    "latitude": -23.5505,
    "longitude": -46.6333,
    "accuracy": 10
  }
}

Response

Etapa avançada com sucesso.

sessionIdstring required
status'ACTIVE' | 'COMPLETED' | 'CANCELLED' | 'EXPIRED' | 'FAILED' required

Status da sessão de assinatura.

evidenceIdstring

ID da evidência (presente quando status é COMPLETED).

redirectUrlstring uri

URL de redirecionamento (returnUrl + session_id).

completedAtstring date-time

Data/hora de conclusão (quando status é COMPLETED).

hostedUrlstring uri

URL da página de liveness hospedada (para start_liveness).

livenessSessionIdstring

ID da sessão Rekognition (para start_liveness).

signatureRequestIdstring

ID da requisição de assinatura (para prepare_signing).

hashToSignstring

Hash a ser assinado pelo certificado (para prepare_signing).

hashAlgorithmstring

Algoritmo do hash (ex. SHA-256).

signatureAlgorithmstring

Algoritmo de assinatura esperado (ex. SHA256withRSA).

errorCodestring

Motivo da reprovação de uma etapa, quando ela falha sem que a requisição falhe. Esta é a parte que mais importa numa integração biométrica: uma etapa reprovada volta 200 com a sessão ainda ACTIVE e o motivo aqui — não como erro HTTP. Quem trata só o status HTTP lê uma reprovação como sucesso.

Valores emitidos hoje:

CódigoSignificado
BIOMETRIC_MATCH_FAILEDSimilaridade abaixo do limiar exigido
LIVENESS_NOT_COMPLETEDA captura de vivacidade não foi concluída
DOCUMENT_QUALITY_LOWBrilho ou nitidez abaixo do piso do tenant
DOCUMENT_MATCH_FAILEDA comparação com a foto do documento não foi aprovada
SERPRO_*Falha na consulta SERPRO — SERPRO_TIMEOUT, SERPRO_RATE_LIMITED, SERPRO_CIRCUIT_OPEN, SERPRO_AUTH_FAILURE, SERPRO_CREDENTIALS_ERROR, SERPRO_INVALID_REQUEST, SERPRO_SERVER_ERROR

CPF_REQUIRED e CPF_MISMATCH não aparecem aqui: são 400, com o código dentro do corpo do problema, não desta resposta 200.

errorDetailstring

Texto em pt-BR destinado ao signatário, pronto para ser exibido. Descreve o que fazer, não o que houve internamente.

retryableboolean

true enquanto restam tentativas na etapa. Quando as tentativas acabam a etapa vai a FAILED e este campo vem false — é o sinal de que insistir não adianta. Cada nova tentativa é cobrada como excedente.

Example response

{
  "sandbox": {
    "otpCode": "123456"
  },
  "errorCode": "BIOMETRIC_MATCH_FAILED",
  "errorDetail": "Não foi possível confirmar seu rosto. Tente novamente."
}

Changes

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