TrustSessions

Criar sessão de confiança

Cria uma Sessão de Confiança — autenticação verificável sem necessidade de documento. Cria atomicamente transação (com purpose=ACTION_AUTHENTICATION), etapas e token de embed. Retorna sessionId, url e clientSecret. O link entregue ao usuário final é {url}?cs={clientSecret} — a url sozinha não abre.

Diferenças em relação a /v1/signing-sessions:

  • action (tipo + descrição) é obrigatório e descreve a ação sendo autenticada
  • document não é aceito — para fluxos com documento, use /v1/signing-sessions
  • O purpose é fixado em ACTION_AUTHENTICATION (não precisa ser informado)
  • O pacote de evidências retorna document: null e action preenchido

Requer scope transactions:write e a flag featureFlags.trustSessionsEnabled no tenant. A cota consumida é monthlyTrustSessions + dailyTrustSessions; as etapas (OTP, biometria, SERPRO, ICP-Brasil) continuam descontando das mesmas dimensões por-etapa já existentes.

post/v1/trust-sessions

Request

  • Base URL: https://api.signdocs.com.br
  • URL: https://api.signdocs.com.br/v1/trust-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

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 usuário.

metadataobject

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

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

Idioma da página de autenticação hospedada.

expiresInMinutesinteger

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

deliverViastring[]

Canais pelos quais a SignDocs entrega o link da sessão ao signatário. Mesmas regras e respostas de deliverVia em CreateSigningSessionRequest: omita para manter apenas o e-mail de convite; whatsapp e telegram são habilitados sob demanda (403 se o tenant não tem o canal), consomem a cota de mensagens (429) e respeitam o kill switch (503).

Example request

{
  "action": {
    "type": "PIX_TRANSFER",
    "description": "Transferência PIX de R$ 5.000,00",
    "reference": "ref-abc-123"
  },
  "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"
  },
  "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"
  }
}

Response

Sessão de confiança criada com sucesso.

sessionIdstring required

Identificador único da sessão de confiança.

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 autenticação hospedada (mesmo domínio sign.signdocs.com.br usado pela Assinatura Expressa — o widget detecta automaticamente o purpose e ajusta o título, esconde a visualização do PDF e exibe a etiqueta "Sessão de Confiança"). 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 usuário final é {url}?cs={clientSecret}, com o clientSecret URL-encoded. Sem o parâmetro cs a página abre em tela de erro. No navegador 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. Só é populado quando owner foi informado e signer.email é diferente de owner.email (case-insensitive).

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.