Guias de Desenvolvimento

Política e Conformidade

Signing Sessions

Sessão de Confiança

Guias dos SDKs

Sessão de Confiança — Guia de Visão Geral

Autentique uma ação digital sem precisar de um documento. A Sessão de Confiança usa a mesma máquina de estado, mesma página hospedada e mesmo pacote de evidências da Assinatura Expressa — mas com purpose=ACTION_AUTHENTICATION no lugar de um PDF.

Procurando assinar um documento PDF? Você está no lugar errado — use o Quickstart: Assinar documento (Assinatura Expressa). Esta página cobre o fluxo sem documento.

Quando usar Sessão de Confiança: KYC, reverificação periódica, aprovação de transação, consentimento de teleconsulta, aceite de termos com biometria, autorização de operações em ERP/CRM, liberação de escrow, validação de profissional habilitado (advogado, contador, médico).

Procurando exemplos prontos? Veja Receitas de Sessão de Confiança.

Sumário

  1. Visão Geral
  2. Comparação com Assinatura Expressa
  3. Criar Sessão
  4. Página Hospedada
  5. Polling e Webhook
  6. Pacote de Evidências
  7. Cotas e Feature Flag
  8. Fluxo Completo (Script)

Convenções

Item Valor
Base URL (HML) https://api-hml.signdocs.com.br
Base URL (Prod) https://api.signdocs.com.br
Domínio Hospedado (HML) https://sign-hml.signdocs.com.br
Domínio Hospedado (Prod) https://sign.signdocs.com.br
Autenticação OAuth2 client_credentials — Bearer JWT
Feature flag featureFlags.trustSessionsEnabled no tenant (provisione com seu Customer Success)
Dimensão de cota monthlyTrustSessions + dailyTrustSessions (consulte com seu CS)
Cotas de etapa monthlyOtp, monthlyBiometric, monthlySerproIdentity continuam descontando da mesma forma

1. Visão Geral

A Sessão de Confiança encapsula um fluxo de autenticação verificável em uma única chamada de API. O usuário final é redirecionado para uma página hospedada pelo SignDocs Brasil que coleta as evidências de identidade (OTP, biometria, certificado ICP-Brasil) e gera um pacote de evidências assinado criptograficamente.

A diferença essencial em relação à Assinatura Expressa: não há documento. A "coisa sendo autenticada" é descrita no campo action (type + description) e fica registrada no pacote de evidências.

┌──────────────┐                ┌──────────────────┐                ┌─────────────────┐
│   Seu Server │                │    SignDocs API   │                │  Página Hosted  │
└──────┬───────┘                └────────┬─────────┘                └────────┬────────┘
       │                                  │                                   │
       │  POST /v1/trust-sessions          │                                   │
       │  { action, signer, policy }       │                                   │
       │─────────────────────────────────>│                                   │
       │                                  │                                   │
       │  { sessionId, url, clientSecret }│                                   │
       │<─────────────────────────────────│                                   │
       │                                  │                                   │
       │  Envia url+clientSecret ao usuário│                                   │
       │  (email/SMS/WhatsApp/redirect)   │                                   │
       │                                  │                                   │
       │                                  │  Usuário abre página              │
       │                                  │<──────────────────────────────────│
       │                                  │  Coleta OTP/biometria/cert        │
       │                                  │  (badge "Sessão de Confiança"     │
       │                                  │   exibida no topo)                │
       │                                  │                                   │
       │                                  │  Gera Evidence Pack               │
       │                                  │  (document: null, action: {...})  │
       │                                  │                                   │
       │  Webhook trust-session.completed │                                   │
       │<─────────────────────────────────│                                   │
       │                                  │                                   │
       │  GET /v1/trust-sessions/{id}/    │                                   │
       │      evidence                     │                                   │
       │─────────────────────────────────>│                                   │
       │  Evidence Pack assinado (.p7m)   │                                   │
       │<─────────────────────────────────│                                   │

2. Comparação com Assinatura Expressa

Aspecto Assinatura Expressa Sessão de Confiança
Endpoint POST /v1/signing-sessions POST /v1/trust-sessions
purpose DOCUMENT_SIGNATURE ACTION_AUTHENTICATION (fixo)
Documento PDF Obrigatório (document.content) Não aceito (400 se enviado)
Campo action Opcional Obrigatório (type + description)
Página hospedada Mostra preview do PDF + título "Assine este documento" Esconde preview + título "Confirme sua identidade" + badge "Sessão de Confiança"
Evidence Pack document: { hashAlg, hash }, action: null document: null, action: { type, description }
Cota descontada monthlyTransactions + cotas por etapa monthlyTrustSessions + cotas por etapa
Verificador público https://verificador.signdocs.com.br/{evidenceId} mesma URL, mostra a action no lugar do documento
Ideal para Contratos, termos, NDAs, qualquer documento PDF KYC, aprovação, consentimento, qualquer "ação" sem PDF

Internamente, ambos compartilham o mesmo motor: máquina de estado de etapas (AdvanceSession), executores de OTP/biometria/SERPRO/ICP-Brasil, construtor de evidências, e a mesma página hospedada que detecta o purpose e ajusta o título e a estrutura visual.

3. Criar Sessão

curl -X POST https://api-hml.signdocs.com.br/v1/trust-sessions \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 01JXYZ-uuid-aqui" \
  -d '{
    "action": {
      "type": "approve_disbursement",
      "description": "Aprovar liberação do empréstimo consignado #INSS-2026-007482 no valor de R$ 8.450,00"
    },
    "policy": {
      "profile": "BIOMETRIC"
    },
    "signer": {
      "name": "Maria Souza",
      "cpf": "123.456.789-09",
      "email": "maria.souza@example.com",
      "phone": "+5511999990000",
      "otpChannel": "email"
    },
    "returnUrl": "https://app.example.com/aprovado",
    "cancelUrl": "https://app.example.com/cancelado",
    "metadata": {
      "internal_request_id": "INSS-2026-007482",
      "branch": "SP-001"
    },
    "locale": "pt-BR",
    "expiresInMinutes": 30
  }'

Resposta 201 Created:

{
  "sessionId": "01JXYZ...",
  "transactionId": "01JXYZ...",
  "status": "ACTIVE",
  "url": "https://sign-hml.signdocs.com.br/s/01JXYZ...",
  "clientSecret": "ss_secret_eyJhbGciOi...",
  "expiresAt": "2026-05-08T14:30:00Z",
  "createdAt": "2026-05-08T14:00:00Z"
}

A URL completa para o usuário final é url + "?cs=" + clientSecret. Você pode entregá-la por email, SMS, WhatsApp, ou redirect direto. Para uso embarcado (iframe / popup checkout) use o SDK Embed JS — veja Receitas.

4. Página Hospedada

Quando o usuário abre a URL, a página hospedada:

  1. Exibe a badge "Sessão de Confiança" no topo (diferencia visualmente de uma assinatura de documento).
  2. Não renderiza preview de PDF — pula direto para a confirmação do signatário.
  3. Mostra a action.description em destaque ("Você está prestes a confirmar: Aprovar liberação do empréstimo consignado…").
  4. Conduz as etapas configuradas pela policy.profile (OTP, biometria facial, SERPRO, etc.).
  5. Ao concluir, gera o pacote de evidências e redireciona para o returnUrl.

O domínio é o mesmo da Assinatura Expressa (sign.signdocs.com.br) — não é necessário whitelist adicional no seu firewall.

5. Polling e Webhook

Polling leve (recomendado para fluxos server-side simples):

curl -X GET https://api-hml.signdocs.com.br/v1/trust-sessions/$SESSION_ID/status \
  -H "Authorization: Bearer $JWT"

Resposta:

{
  "sessionId": "01JXYZ...",
  "transactionId": "01JXYZ...",
  "status": "COMPLETED",
  "completedAt": "2026-05-08T14:12:34Z",
  "evidenceId": "ev_01JXYZ..."
}

Webhook (recomendado para alto volume):

Cadastre um webhook com escopo trust_session.* em POST /v1/webhooks. Eventos emitidos:

Evento Quando
trust_session.created Logo após criação
trust_session.completed Usuário completou todas as etapas
trust_session.cancelled Sessão cancelada (pelo usuário ou via API)
trust_session.expired TTL atingido sem conclusão
trust_session.failed Falha definitiva em alguma etapa (ex: biometria)

O payload inclui sessionId, transactionId, status, evidenceId e metadata.

6. Pacote de Evidências

Após COMPLETED, recupere o pacote assinado:

curl -X GET https://api-hml.signdocs.com.br/v1/trust-sessions/$SESSION_ID/evidence \
  -H "Authorization: Bearer $JWT" \
  -o evidence-$SESSION_ID.p7m

Ou consulte o JSON canônico via GET /v1/verify/{evidenceId} (público, sem auth). Estrutura abreviada:

{
  "evidenceId": "ev_01JXYZ...",
  "purpose": "ACTION_AUTHENTICATION",
  "document": null,
  "action": {
    "type": "approve_disbursement",
    "description": "Aprovar liberação do empréstimo consignado #INSS-2026-007482..."
  },
  "signer": { "cpf": "12345678909", "name": "Maria Souza", "email": "..." },
  "steps": [
    { "type": "CLICK_ACCEPT", "status": "COMPLETED", "completedAt": "..." },
    { "type": "BIOMETRIC_LIVENESS", "status": "COMPLETED", "result": { "matchScore": 0.987 } }
  ],
  "timestamps": { "createdAt": "...", "completedAt": "..." },
  "ipAddress": "200.x.x.x",
  "userAgent": "...",
  "geolocation": { "lat": -23.55, "lon": -46.63 }
}

Veja Pacote de Evidências para o detalhamento completo dos campos e como apresentar isso a um juiz/regulador.

7. Cotas e Feature Flag

A criação de Sessão de Confiança requer:

  1. Feature flag ativa. featureFlags.trustSessionsEnabled = true no TENANT_CONFIG. Se desativada, a API retorna 403 Forbidden com type: "feature-not-enabled". Solicite ao seu CS.
  2. Cota disponível. A criação decrementa monthlyTrustSessions + dailyTrustSessions. Quando atingido, a API retorna 429 Too Many Requests com headers RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.
  3. Cotas por etapa. As etapas de OTP, biometria, SERPRO e ICP-Brasil continuam decrementando suas próprias dimensões (monthlyOtp, monthlyBiometric, monthlySerproIdentity, monthlySigning). Uma Sessão de Confiança com perfil BIOMETRIC consome uma unidade de monthlyTrustSessions e uma unidade de monthlyBiometric.

Cotas são não-reembolsáveis em cancelamento (mesma regra das monthlyTransactions).

8. Fluxo Completo (Script)

#!/usr/bin/env bash
set -euo pipefail

API=https://api-hml.signdocs.com.br
CLIENT_ID="${SIGNDOCS_CLIENT_ID:?}"
CLIENT_SECRET="${SIGNDOCS_CLIENT_SECRET:?}"

# 1. Token
JWT=$(curl -s -X POST "$API/oauth2/token" \
  -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&scope=transactions:write transactions:read" \
  | jq -r .access_token)

# 2. Criar sessão
RESP=$(curl -s -X POST "$API/v1/trust-sessions" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "action": {"type":"approve_payment","description":"Aprovar pagamento PIX de R$ 1.500,00"},
    "policy": {"profile":"BIOMETRIC"},
    "signer": {"name":"João","cpf":"123.456.789-09","email":"joao@example.com","otpChannel":"email"}
  }')
SESSION_ID=$(echo "$RESP" | jq -r .sessionId)
URL=$(echo "$RESP" | jq -r .url)
CS=$(echo "$RESP" | jq -r .clientSecret)

echo "Envie ao usuário: ${URL}?cs=${CS}"

# 3. Polling
while true; do
  STATUS=$(curl -s -X GET "$API/v1/trust-sessions/$SESSION_ID/status" \
    -H "Authorization: Bearer $JWT" | jq -r .status)
  echo "status=$STATUS"
  [ "$STATUS" = "COMPLETED" ] && break
  [ "$STATUS" = "FAILED" -o "$STATUS" = "EXPIRED" -o "$STATUS" = "CANCELLED" ] && exit 1
  sleep 5
done

# 4. Recuperar pacote de evidências
EVIDENCE_ID=$(curl -s -X GET "$API/v1/trust-sessions/$SESSION_ID/status" \
  -H "Authorization: Bearer $JWT" | jq -r .evidenceId)

curl -s -X GET "$API/v1/verify/$EVIDENCE_ID" | jq .

Próximos passos