{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/signdocs-com-br/json-schema/signdocs-com-br-advance-session-request-schema.json", "title": "AdvanceSessionRequest", "description": "Requisição para avançar a sessão de assinatura. Os campos obrigatórios dependem da ação:\n\n| Ação | Campos obrigatórios | Descrição |\n|------|---------------------|-----------|\n| `confirm_signer` | `cpfCnpj` | Confirma a identidade declarada do signatário |\n| `accept` | — | Aceita o termo (CLICK_ACCEPT) |\n| `verify_otp` | `otpCode` | Verifica o código OTP |\n| `resend_otp` | — | Reenvia o desafio OTP |\n| `start_liveness` | — | Inicia sessão de liveness biométrico |\n| `complete_liveness` | `livenessSessionId` | Conclui liveness com resultado Rekognition |\n| `prepare_signing` | `certificateChainPems` | Prepara assinatura digital (retorna hash) |\n| `complete_signing` | `signatureRequestId`, `rawSignatureBase64` | Conclui assinatura digital |\n| `complete_document_photo` | `documentImage` | Conclui a comparação com a foto do documento (DOCUMENT_PHOTO_MATCH) |\n", "x-generated": "2026-10-31", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/signdocs-com-br-openapi.yaml#/components/schemas/AdvanceSessionRequest", "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "description": "Ação a executar na sessão.", "enum": [ "confirm_signer", "accept", "verify_otp", "resend_otp", "start_liveness", "complete_liveness", "prepare_signing", "complete_signing", "complete_document_photo" ] }, "cpfCnpj": { "type": "string", "description": "CPF ou CNPJ que o signatário digita para confirmar a própria\nidentidade (obrigatório em `confirm_signer`). Comparado com o valor\ninformado na criação da sessão; divergência reprova a etapa.\n" }, "documentImage": { "type": "string", "format": "byte", "description": "Foto do documento de identidade em base64 (obrigatório em\n`complete_document_photo`). Máximo 5 MB. O rosto é extraído da\nimagem e comparado com a referência do cadastro.\n" }, "documentType": { "type": "string", "description": "Tipo do documento enviado em `documentImage`." }, "deviceInfo": { "type": "object", "description": "Características do dispositivo do signatário, gravadas na evidência\njunto da geolocalização. Todos os campos são opcionais.\n", "properties": { "screenWidth": { "type": "integer" }, "screenHeight": { "type": "integer" }, "language": { "type": "string" }, "platform": { "type": "string" }, "touchPoints": { "type": "integer" } } }, "otpCode": { "type": "string", "description": "Código OTP de 6 dígitos (obrigatório para `verify_otp`)." }, "otpChannel": { "allOf": [ { "$ref": "#/$defs/OtpChannel" } ], "description": "Canal escolhido pelo signatário para receber o OTP — na ação `accept` (escolha inicial) ou `resend_otp` (troca de canal). Aceito apenas quando a sessão foi criada com `signer.otpChannelSelectable`; caso contrário a requisição é rejeitada com 400." }, "livenessSessionId": { "type": "string", "description": "ID da sessão Rekognition (obrigatório para `complete_liveness`)." }, "certificateChainPems": { "type": "array", "items": { "type": "string" }, "description": "Cadeia de certificados PEM (obrigatório para `prepare_signing`)." }, "signatureRequestId": { "type": "string", "description": "ID da requisição de assinatura (obrigatório para `complete_signing`)." }, "rawSignatureBase64": { "type": "string", "format": "byte", "description": "Assinatura bruta em base64 (obrigatório para `complete_signing`)." }, "sandboxBrightness": { "type": "number", "format": "double", "minimum": 0, "maximum": 100, "description": "Brilho simulado da captura, para ensaiar a reprovação por qualidade\n(`DOCUMENT_QUALITY_LOW`). Mesmo enquadramento do `sandboxSimilarity`:\nsó vale em sandbox.\n\nAntes destes campos as ramificações de sandbox fixavam 80/80 e nunca\navaliavam o piso de qualidade — ou seja, o erro que mais aparece em\ncampo (luz ruim, reflexo no visor, sujeito em movimento) era o único\nque o integrador não conseguia reproduzir sob demanda.\n" }, "sandboxSharpness": { "type": "number", "format": "double", "minimum": 0, "maximum": 100, "description": "Nitidez simulada da captura. Ver `sandboxBrightness`.\n" }, "sandboxLivenessConfidence": { "type": "number", "format": "double", "minimum": 0, "maximum": 100, "description": "Confiança de liveness simulada, para ensaiar a reprovação. Mesmo\nenquadramento do `sandboxSimilarity`: só vale em sandbox, e nunca\naprova uma verificação real.\n\nSubstitui o truque antigo de escrever `fail` no `livenessSessionId`,\nque só produzia 99.5 ou 30.0 — nenhum dos dois perto do limiar, que é\njustamente onde as capturas reais caem. A convenção antiga continua\nvalendo quando nada é informado.\n" }, "sandboxSimilarity": { "type": "number", "format": "double", "minimum": 0, "maximum": 100, "description": "Similaridade simulada para as etapas biométricas em sandbox, usada\npara exercitar o caminho de reprovação. Padrão 99.5, que aprova;\nabaixo do limiar do tenant, a etapa reprova como reprovaria em\nprodução.\n\nSó é lida quando a etapa já resolveu para sandbox — em HML, ou em\ntenants com `mode: SANDBOX` — e quando não existe frame real de\nliveness. Uma captura real sempre vence: a comparação real acontece\ne este campo é ignorado. Ou seja, ele nunca faz uma comparação real\npassar.\n\nA página hospedada é quem chama o advance, então o caminho usual\nnão é este campo, e sim `metadata.sandboxSimilarity` na criação da\nsessão. Envie aqui apenas em integrações headless, que chamam o\nadvance diretamente; o corpo tem precedência sobre a metadata. Um\nvalor fora de 0-100 ou não numérico retorna 400.\n" }, "geolocation": { "type": "object", "description": "Geolocalização do dispositivo. Aceito nas ações `accept`, `verify_otp`,\n`complete_liveness` e `complete_signing`. Obrigatório em `complete_liveness`\nquando o tenant possui `biometricRequired` habilitado.\n", "properties": { "latitude": { "type": "number", "format": "double", "description": "Latitude em graus decimais (-90 a 90)." }, "longitude": { "type": "number", "format": "double", "description": "Longitude em graus decimais (-180 a 180)." }, "accuracy": { "type": "number", "format": "double", "description": "Precisão em metros (>= 0)." }, "source": { "type": "string", "description": "Origem da geolocalização.", "enum": [ "GPS", "IP", "WIFI", "CELL" ] } } } }, "$defs": { "OtpChannel": { "type": "string", "description": "Canal de entrega do OTP, escolhido por signatário. Independente do canal\nusado para entregar o link de assinatura: um convite por WhatsApp pode ter\nOTP por e-mail, e um convite por e-mail pode ter OTP por WhatsApp.\n\n`sms` e `whatsapp` exigem `signer.phone` e o canal habilitado para o tenant\n(`sms.enabled` / `whatsapp.enabled`); caso contrário o passo de OTP falha com\n**422**. No WhatsApp, um número que pediu para não receber mensagens também\nfalha com 422, com uma mensagem que orienta a escolher outro canal.\n\n`telegram` exige `telegram.enabled` no tenant. O código chega pelo bot da\nSignDocs quando o signatário já registrou o próprio CPF nele; sem registro, é\nenviado por telefone (Telegram Gateway) se o tenant tiver essa opção\nhabilitada, e caso contrário o passo falha com **422** de imediato. Ao criar a\nsessão, `otpChannel: telegram` ainda exige `signer.email` quando a política\ntem OTP.\n\nUm OTP por WhatsApp ou pelo Telegram Gateway consome a cota de mensagens do\ntenant; esgotada, o envio é recusado com **429**.\n", "enum": [ "email", "sms", "whatsapp", "telegram" ], "default": "email" } } }