--- title: "Iniciar etapa de verificação" method: POST path: "/v1/transactions/{transactionId}/steps/{stepId}/start" tags: ["Steps"] --- # Iniciar etapa de verificação `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 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`. ## Path parameters - `transactionId` string, required - `stepId` string, required ## Request body - StepStartRequest: Requisição de início de etapa (opcional — necessário apenas para BIOMETRIC_LIVENESS e OTP_CHALLENGE). - `BIOMETRIC_LIVENESS`: envie `captureMode`. - `OTP_CHALLENGE`: opcionalmente envie `otpChannel` para escolher o canal (`email`, `sms`, `whatsapp` ou `telegram`). - `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 `200` Etapa iniciada com sucesso. A resposta varia conforme o tipo. - StepStartResponse: Resposta de início de etapa. Os campos retornados variam conforme o tipo: - `BIOMETRIC_LIVENESS` (BANK_APP): `livenessSessionId` - `BIOMETRIC_LIVENESS` (HOSTED_PAGE): `hostedUrl` - `OTP_CHALLENGE`: `message`, `otpCode` (apenas sandbox) - `OTP_VERIFY`: `message` - `CLICK_ACCEPT`: `message` - `DIGITAL_SIGN_A1`: `message` - `stepId` string, 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. - `livenessSessionId` string: ID da sessão Rekognition (modo BANK_APP). - `hostedUrl` string, uri: URL da página hospedada de liveness (modo HOSTED_PAGE). - `message` string: Mensagem informativa sobre a etapa. - `otpCode` string: 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**. ## Other responses - `400`: Requisição inválida — parâmetros ausentes ou malformados. - `401`: Autenticação ausente ou inválida. - `403`: Permissões insuficientes para a operação solicitada. Inclui `purpose: "ACTION_AUTHENTICATION"` sem `featureFlags.trustSessionsEnabled`. A verificação é pelo `purpose`, não pela rota: vale em `/v1/transactions`, `/v1/signing-sessions` e `/v1/envelopes/{envelopeId}/sessions`, além de `/v1/trust-sessions`. O remédio é habilitar a flag para o tenant e provisionar a cota `monthlyTrustSessions`. - `404`: Recurso não encontrado. - `409`: Conflito de estado — a operação não pode ser realizada no estado atual do recurso. - `429`: Limite de requisições excedido. - `500`: Erro interno do servidor. - `503`: Serviço temporariamente indisponível. --- [API](https://skmtc.dev/signdocs/apis/signdocs-brasil-external-api.md) · [All operations](https://skmtc.dev/signdocs/apis/signdocs-brasil-external-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signdocs/apis/signdocs-brasil-external-api/revisions/2d3805aed161?raw)