Steps

Iniciar etapa de verificação

Inicia uma etapa de verificação de identidade. A resposta varia conforme o tipo da etapa:

  • BIOMETRIC_LIVENESS: Retorna livenessSessionId (modo BANK_APP) ou hostedUrl (modo HOSTED_PAGE).
  • OTP_CHALLENGE: Envia o código OTP por e-mail e retorna mensagem de confirmação.
  • OTP_VERIFY: Retorna mensagem informando que o código já foi enviado.
  • CLICK_ACCEPT: Retorna mensagem com o termo a ser aceito.
  • DOCUMENT_PHOTO_MATCH: Retorna mensagem indicando prontidão para envio da foto do documento.
  • SERPRO_IDENTITY_CHECK: Retorna mensagem indicando prontidão para verificação SERPRO (requer serpro.enabled).
  • DIGITAL_SIGN_A1: Retorna mensagem indicando prontidão para assinatura digital.

Reenvio de OTP

Ao chamar start em uma etapa OTP_CHALLENGE quando attempts > 1 (reenvio), a etapa pareada OTP_VERIFY é automaticamente resetada caso esteja em status FAILED ou STARTED. Isso permite que o usuário tente novamente com um novo código sem necessidade de intervenção manual.

Requer scope steps:write.

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

Request

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

Path parameters

transactionIdstring required

Identificador único da transação.

stepIdstring required

Identificador único da etapa.

Request body

captureMode'BANK_APP' | 'HOSTED_PAGE'

Modo de captura biométrica.

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.

Response

Etapa iniciada com sucesso. A resposta varia conforme o tipo.

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.

livenessSessionIdstring

ID da sessão Rekognition (modo BANK_APP).

hostedUrlstring uri

URL da página hospedada de liveness (modo HOSTED_PAGE).

messagestring

Mensagem informativa sobre a etapa.

otpCodestring

Código OTP (retornado apenas em ambiente sandbox para facilitar testes).

channel'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.

Changes

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