--- title: "Avançar etapa da sessão" method: POST path: "/v1/signing-sessions/{sessionId}/advance" tags: ["SigningSessions"] --- # Avançar etapa da sessão `POST /v1/signing-sessions/{sessionId}/advance` ## Request - Base URL: `https://api.signdocs.com.br` - URL: `https://api.signdocs.com.br/v1/signing-sessions/{sessionId}/advance` - Auth: HTTP bearer Avança a sessão de assinatura através de suas etapas. Suporta as ações: accept, verify_otp, resend_otp, start_liveness, complete_liveness, prepare_signing, complete_signing. Auto-finaliza na última etapa. Autenticação via embedToken (clientSecret). ## Path parameters - `sessionId` string, required ## Request body - AdvanceSessionRequest: Requisição para avançar a sessão de assinatura. Os campos obrigatórios dependem da ação: | Ação | Campos obrigatórios | Descrição | |------|---------------------|-----------| | `confirm_signer` | `cpfCnpj` | Confirma a identidade declarada do signatário | | `accept` | — | Aceita o termo (CLICK_ACCEPT) | | `verify_otp` | `otpCode` | Verifica o código OTP | | `resend_otp` | — | Reenvia o desafio OTP | | `start_liveness` | — | Inicia sessão de liveness biométrico | | `complete_liveness` | `livenessSessionId` | Conclui liveness com resultado Rekognition | | `prepare_signing` | `certificateChainPems` | Prepara assinatura digital (retorna hash) | | `complete_signing` | `signatureRequestId`, `rawSignatureBase64` | Conclui assinatura digital | | `complete_document_photo` | `documentImage` | Conclui a comparação com a foto do documento (DOCUMENT_PHOTO_MATCH) | - `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. - `cpfCnpj` string: 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. - `documentImage` string, 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. - `documentType` string: Tipo do documento enviado em `documentImage`. - `deviceInfo` object: Características do dispositivo do signatário, gravadas na evidência junto da geolocalização. Todos os campos são opcionais. - `screenWidth` integer - `screenHeight` integer - `language` string - `platform` string - `touchPoints` integer - `otpCode` string: 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**. - `livenessSessionId` string: ID da sessão Rekognition (obrigatório para `complete_liveness`). - `certificateChainPems` string[]: Cadeia de certificados PEM (obrigatório para `prepare_signing`). - `signatureRequestId` string: ID da requisição de assinatura (obrigatório para `complete_signing`). - `rawSignatureBase64` string, byte: Assinatura bruta em base64 (obrigatório para `complete_signing`). - `sandboxBrightness` number, 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. - `sandboxSharpness` number, double: Nitidez simulada da captura. Ver `sandboxBrightness`. - `sandboxLivenessConfidence` number, 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. - `sandboxSimilarity` number, 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. - `geolocation` object: Geolocalização do dispositivo. Aceito nas ações `accept`, `verify_otp`, `complete_liveness` e `complete_signing`. Obrigatório em `complete_liveness` quando o tenant possui `biometricRequired` habilitado. - `latitude` number, double: Latitude em graus decimais (-90 a 90). - `longitude` number, double: Longitude em graus decimais (-180 a 180). - `accuracy` number, double: Precisão em metros (>= 0). - `source` 'GPS' | 'IP' | 'WIFI' | 'CELL': Origem da geolocalização. ## Response `200` Etapa avançada com sucesso. - AdvanceSessionResponse: Resposta do avanço da sessão. - `sessionId` string, required - `status` 'ACTIVE' | 'COMPLETED' | 'CANCELLED' | 'EXPIRED' | 'FAILED', required: Status da sessão de assinatura. - `currentStep` object: Etapa atual sendo processada. - `stepId` string - `type` string - `status` string - `nextStep` object: Próxima etapa pendente (se houver). - `stepId` string - `type` string - `evidenceId` string: ID da evidência (presente quando status é COMPLETED). - `redirectUrl` string, uri: URL de redirecionamento (returnUrl + session_id). - `completedAt` string, date-time: Data/hora de conclusão (quando status é COMPLETED). - `hostedUrl` string, uri: URL da página de liveness hospedada (para `start_liveness`). - `livenessSessionId` string: ID da sessão Rekognition (para `start_liveness`). - `signatureRequestId` string: ID da requisição de assinatura (para `prepare_signing`). - `hashToSign` string: Hash a ser assinado pelo certificado (para `prepare_signing`). - `hashAlgorithm` string: Algoritmo do hash (ex. SHA-256). - `signatureAlgorithm` string: Algoritmo de assinatura esperado (ex. SHA256withRSA). - `sandbox` object: Dados de sandbox (apenas em HML). Contém o OTP para testes. - `otpCode` string - `autoPass` boolean: Indica que a etapa biométrica será aprovada automaticamente. - `errorCode` string: 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ódigo | Significado | |---|---| | `BIOMETRIC_MATCH_FAILED` | Similaridade abaixo do limiar exigido | | `LIVENESS_NOT_COMPLETED` | A captura de vivacidade não foi concluída | | `DOCUMENT_QUALITY_LOW` | Brilho ou nitidez abaixo do piso do tenant | | `DOCUMENT_MATCH_FAILED` | A 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. - `errorDetail` string: Texto em pt-BR destinado ao signatário, pronto para ser exibido. Descreve o que fazer, não o que houve internamente. - `retryable` boolean: `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. - `fallback` object: Presente quando a política desviou para uma etapa alternativa em vez de reprovar de vez — por exemplo, biometria que cai para comparação com foto do documento. - `triggered` boolean - `reason` string - `nextStepType` string ## Other responses - `400`: Requisição inválida — parâmetros ausentes ou malformados. - `401`: Autenticação ausente ou inválida. - `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)