SigningSessions

Criar sessão de assinatura

Cria uma sessão de assinatura expressa (Assinatura Expressa). Cria atomicamente transação, etapas, documento e token de embed. Retorna sessionId, url e clientSecret.

O link entregue ao signatário é {url}?cs={clientSecret} — a url sozinha não abre, porque o clientSecret é a autenticação da sessão. Veja a descrição do campo url.

Requer scope transactions:write.

post/v1/signing-sessions

Request

  • Base URL: https://api.signdocs.com.br
  • URL: https://api.signdocs.com.br/v1/signing-sessions
  • Auth: HTTP bearer

Headers

X-Idempotency-Keystring uuid

Chave de idempotência para evitar criação duplicada. Reenviar a mesma chave com o mesmo corpo dentro de 24h devolve a resposta original, sem consumir cota nem repetir efeitos (e-mails, webhooks). A mesma chave com um corpo diferente responde 409.

A resposta repetida é a original byte a byte, incluindo os cabeçalhos RateLimit-* — eles refletem a cota no momento da chamada original, já que a repetição não consumiu nada.

Request body

purpose'DOCUMENT_SIGNATURE' | 'ACTION_AUTHENTICATION' required

Finalidade da transação.

returnUrlstring uri

URL de retorno após conclusão. O session_id será adicionado como query parameter.

cancelUrlstring uri

URL de retorno em caso de cancelamento pelo signatário.

metadataobject

Metadados livres (chave-valor). Chaves até 256 chars, valores até 1024 chars.

Quatro chaves são interpretadas pela API, todas como string e todas apenas em sandbox — é por elas que se testa a reprovação pela página hospedada, onde quem emite a chamada é a própria página e o integrador não tem outro ponto de injeção:

ChaveEfeitoPadrão
sandboxSimilaritySimilaridade simulada de BIOMETRIC_MATCH / DOCUMENT_PHOTO_MATCH99.5
sandboxLivenessConfidenceConfiança simulada de BIOMETRIC_LIVENESS99.5
sandboxBrightnessBrilho simulado da captura (dispara DOCUMENT_QUALITY_LOW)80
sandboxSharpnessNitidez simulada da captura80

Fora do sandbox são ignoradas. Valores inválidos também são ignorados, mantendo o padrão: elas são fixadas na criação e não podem quebrar o signatário no meio do fluxo.

locale'pt-BR' | 'en' | 'es'

Idioma da página de assinatura.

expiresInMinutesinteger

Tempo de expiração em minutos (5 a 1440). Padrão 60.

deliverViastring[]

Canais pelos quais a SignDocs entrega o link de assinatura a este signatário. Omita para manter o comportamento anterior: apenas o e-mail de convite, sujeito à regra de owner/signer.email. Os canais escolhidos ficam gravados: um resend-invite sem corpo reenvia por eles.

WhatsApp e Telegram são habilitados sob demanda: o tenant pede ao time comercial, e não é algo que se liga pelo painel. Pedir um canal que o tenant não tem retorna 403 antes de qualquer gravação.

whatsapp exige signer.phone em E.164. whatsappInviteSent: true significa que a Meta aceitou a mensagem, não que ela foi entregue ou lida; em qualquer outro caso o campo é omitido da resposta. Se a Meta reportar falha depois e o signatário tiver e-mail, a SignDocs reenvia o convite por e-mail automaticamente, com um link novo, diferente do que veio nesta resposta; nenhum webhook, campo ou endpoint informa esse reenvio. Um número que respondeu "parar", "sair" ou "stop" deixa de receber mensagens da SignDocs por WhatsApp.

telegram exige signer.cpf e só alcança signatários que já registraram o próprio CPF no bot da SignDocs. telegramInviteSent vem na resposta sempre que o convite por Telegram é tentado nesta chamada, false quando não chegou.

Cada envio por WhatsApp ou Telegram consome a cota de mensagens do tenant. Esgotada a cota, a requisição é recusada com 429 antes de qualquer gravação; com o canal suspenso por kill switch, com 503. Credenciais de sandbox também enviam mensagens reais por WhatsApp e consomem a cota de mensagens de sandbox.

Example request

{
  "policy": {
    "minSimilarity": 95,
    "minLivenessConfidence": 90
  },
  "signer": {
    "name": "João da Silva",
    "email": "joao@exemplo.com.br",
    "userExternalId": "usr-12345",
    "displayName": "João",
    "cpf": "12345678901",
    "cnpj": "12345678000199",
    "phone": "+5511999998888"
  },
  "document": {
    "filename": "contrato.pdf"
  },
  "action": {
    "type": "PIX_TRANSFER",
    "description": "Transferência PIX de R$ 5.000,00",
    "reference": "ref-abc-123"
  },
  "returnUrl": "https://app.example.com/done",
  "cancelUrl": "https://app.example.com/cancelled",
  "appearance": {
    "brandColor": "#1a5276",
    "logoUrl": "https://cdn.example.com/logo.png",
    "companyName": "Empresa Exemplo Ltda",
    "backgroundColor": "#ffffff",
    "textColor": "#333333",
    "buttonTextColor": "#ffffff",
    "borderRadius": "12px"
  },
  "owner": {
    "email": "solicitante@empresa.com.br",
    "name": "Maria Souza"
  },
  "deliverVia": [
    "email",
    "whatsapp"
  ]
}

Response

Sessão de assinatura criada com sucesso.

sessionIdstring required

Identificador único da sessão.

transactionIdstring required

Identificador da transação subjacente.

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

Status da sessão de assinatura.

urlstring uri required

Endereço da página de assinatura hospedada. Não é um link utilizável sozinho: o clientSecret é a autenticação da sessão e precisa viajar na query string. O link entregue ao signatário é {url}?cs={clientSecret}, com o clientSecret URL-encoded. Sem o parâmetro cs a página abre em tela de erro. No navegador não é preciso montar nada — o SDK JS deriva a URL do próprio clientSecret (sd.checkout() abre em popup, sd.redirect() redireciona).

clientSecretstring required

Token de sessão para autenticação no widget/redirect. Formato ss_secret_ + JWT.

expiresAtstring date-time required

Data/hora de expiração da sessão (ISO 8601 UTC).

createdAtstring date-time required

Data/hora de criação (ISO 8601 UTC).

inviteSentboolean

Verdadeiro quando a SignDocs enviou um e-mail de convite para signer.email no momento da criação da sessão. Só é populado quando owner foi informado e signer.email é diferente de owner.email (case-insensitive).

whatsappInviteSentboolean

true quando a Meta aceitou a mensagem com o link para signer.phone. Aceitar não é entregar: a entrega é confirmada depois, por webhook da Meta, e não é exposta pela API. Omitido em qualquer outro caso (número que pediu para não receber mensagens, falha no envio) e só considerado quando deliverVia incluiu whatsapp.

telegramInviteSentboolean

Resultado da entrega por Telegram. false significa que o signatário não tem CPF registrado no bot, ou que o envio falhou — em ambos os casos o link não chegou por esse canal. Só é populado quando deliverVia incluiu telegram.

Example response

{
  "sessionId": "ss_01JXYZ...",
  "transactionId": "tx_01JXYZ...",
  "url": "https://sign.signdocs.com.br/s/ss_01JXYZ...",
  "clientSecret": "ss_secret_eyJhbGciOi..."
}

Changes

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