Guias de Desenvolvimento

Política e Conformidade

Signing Sessions

Sessão de Confiança

Modelos de Solução

Guias dos SDKs

Contrato de Locação e Compra e Venda com Assinatura Eletrônica — Modelo de Solução

Feche contratos de locação e de compra e venda de imóveis em horas, não em semanas: o locatário, o fiador e o locador assinam na ordem certa, de qualquer lugar, com validade jurídica fundada na MP 2.200-2/2001 e tratamento de dados conforme a LGPD. Este guia mostra como implementar assinatura digital imobiliária de ponta a ponta com a API SignDocs Brasil — do upload do contrato ao PDF final carimbado com todas as assinaturas.

Público-alvo: imobiliárias, proptechs e corretores com sistema próprio (CRM imobiliário, ERP de locação, portal de imóveis) que querem embutir assinatura eletrônica no seu fluxo de fechamento.

⚡ Caminho de 20 minutos

Solicite credenciais HML em app.signdocs.com.br/admin/api-clients ou por contato@signdocs.com.br.
Autentique com OAuth2 client_credentials em POST /oauth2/token.
Crie um envelope SEQUENTIAL com o PDF do contrato de locação (POST /v1/envelopes).
Adicione locatário, fiador e locador com signerIndex 1, 2 e 3 (POST /v1/envelopes/{envelopeId}/sessions) e entregue cada link de assinatura.
Ao receber o webhook ENVELOPE.ALL_SIGNED, baixe o PDF final com carimbo combinado (POST /v1/envelopes/{envelopeId}/combined-stamp) e arquive a evidência de cada assinatura.

Resultado: contrato de locação assinado pelas três partes, PDF carimbado no seu bucket e evidência criptográfica pronta para auditoria.

1. O problema de negócio

O fechamento de uma locação em papel é uma corrida de obstáculos: imprimir três vias, colher a assinatura do locatário na loja, mandar motoboy (ou o próprio corretor) atrás do fiador — que costuma morar em outra cidade —, esperar o locador devolver a via assinada e, só então, liberar as chaves. Cada ida e volta custa dias; enquanto isso o imóvel segue vago, o proprietário pressiona e o candidato a locatário pode desistir e alugar com o concorrente. Em compra e venda a dor é ainda maior: mais partes, valores altos e propostas que esfriam a cada dia de espera.

Com um fluxo de contrato de locação com assinatura eletrônica, o contrato sai do seu CRM direto para o celular de cada parte, na ordem que o seu jurídico exige: primeiro o locatário, depois o fiador (que só se compromete depois que o locatário assinou), por último o locador ou a imobiliária como interveniente. Cada assinatura gera evidência criptográfica — hash SHA-256 do documento, trilha de auditoria, timestamp ISO do servidor e pacote de evidências assinado com certificado ICP-Brasil — e o sistema avança o funil sozinho, sem ninguém perseguindo pendências por telefone.

O mesmo fluxo atende o contrato de compra e venda online (promessa ou instrumento particular): basta ajustar os papéis — vendedor, comprador e, quando aplicável, cônjuges e testemunhas — e, por se tratar de operação de alto valor, subir o nível de verificação de identidade para biometria facial.

2. Arquitetura do fluxo

Seu CRM / sistema imobiliário
        │
        ▼
POST /v1/envelopes  (signingMode: SEQUENTIAL, totalSigners: 3)
        │
        ├─ POST /v1/envelopes/{id}/sessions  signerIndex: 1 → locatário
        ├─ POST /v1/envelopes/{id}/sessions  signerIndex: 2 → fiador
        └─ POST /v1/envelopes/{id}/sessions  signerIndex: 3 → locador/imobiliária
        │
locatário assina ──► fiador assina ──► locador assina
        │                 │                  │
        └── webhook STEP.COMPLETED a cada etapa (avança o funil no CRM)
        │
webhook ENVELOPE.ALL_SIGNED
        │
        ▼
POST /v1/envelopes/{id}/combined-stamp ──► downloadUrl do PDF final

Primitiva	Quando usar	Por que aqui
Sessão de assinatura (`POST /v1/signing-sessions`)	1 signatário, 1 documento	Não atende: locação tem no mínimo 3 partes no mesmo contrato
Envelope (`POST /v1/envelopes`)	2+ signatários no mesmo documento, ordem controlada	Escolha deste guia: `SEQUENTIAL` garante locatário → fiador → locador e gera um único PDF carimbado ao final
Sessão de confiança (`POST /v1/trust-sessions`)	Autenticar uma ação sem documento (aprovação, consentimento, KYC)	Útil como complemento (ex.: aprovação da proposta antes do contrato), não para assinar o contrato em si

O modo SEQUENTIAL é o ponto central: o fiador só consegue assinar depois do locatário, e o locador só depois do fiador. Isso espelha a prática de mercado — o fiador não se obriga antes de ver o locatário comprometido — e evita contratos assinados "pela metade" em ordem errada. Se a ordem não importa no seu processo, use PARALLEL e todos assinam ao mesmo tempo (veja envelopes de assinatura expressa).

3. Pré-requisitos

Tenant SignDocs Brasil com acesso à API: solicite pelo painel admin ou por contato@signdocs.com.br.
Escopos OAuth provisionados: transactions:read transactions:write steps:write evidence:read webhooks:write.
PDF do contrato gerado pelo seu sistema (modelo de locação ou compra e venda preenchido com os dados do imóvel e das partes).
Opcional: SDK backend — npm install @signdocs-brasil/api (TypeScript) ou pip install signdocs-brasil (Python). Para Go, Java, PHP e C#, veja o guia de SDKs para envelopes.

🟠 HML vs Produção — desenvolva sempre em HML (https://api-hml.signdocs.com.br); credenciais HML não consomem cota do plano e os dados expiram em 7 dias. Produção: https://api.signdocs.com.br.

4. Autenticação OAuth2

A API usa OAuth2 client_credentials (servidor-a-servidor). Troque client_id + client_secret por um access_token:

export SIGNDOCS_BASE_URL="https://api-hml.signdocs.com.br"

ACCESS_TOKEN=$(curl -s -X POST "$SIGNDOCS_BASE_URL/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=$SIGNDOCS_CLIENT_ID&client_secret=$SIGNDOCS_CLIENT_SECRET" \
  | jq -r '.access_token')

import { SignDocsBrasilClient } from '@signdocs-brasil/api';

const client = new SignDocsBrasilClient({
  clientId: process.env.SIGNDOCS_CLIENT_ID!,
  clientSecret: process.env.SIGNDOCS_CLIENT_SECRET!,
  baseUrl: process.env.SIGNDOCS_BASE_URL, // https://api-hml.signdocs.com.br
});

import os
from signdocs_brasil import SignDocsBrasilClient, ClientConfig

client = SignDocsBrasilClient(ClientConfig(
    client_id=os.environ['SIGNDOCS_CLIENT_ID'],
    client_secret=os.environ['SIGNDOCS_CLIENT_SECRET'],
    base_url=os.environ.get('SIGNDOCS_BASE_URL', 'https://api-hml.signdocs.com.br'),
))

Os SDKs renovam o token automaticamente. Detalhes em autenticação com SDKs.

5. Criar o envelope sequencial

Crie o envelope com o PDF do contrato em base64, modo SEQUENTIAL e totalSigners: 3. Use metadata para amarrar o envelope ao imóvel e ao contrato no seu CRM — esses campos voltam nos webhooks e facilitam a conciliação. expiresInMinutes: 4320 dá 72 horas para as três partes assinarem.

PDF_BASE64=$(base64 -w0 contrato-locacao.pdf)

curl -s -X POST "$SIGNDOCS_BASE_URL/v1/envelopes" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"signingMode\": \"SEQUENTIAL\",
    \"totalSigners\": 3,
    \"document\": { \"content\": \"$PDF_BASE64\", \"filename\": \"contrato-locacao.pdf\" },
    \"metadata\": {
      \"imovelId\": \"imv-8841\",
      \"contratoId\": \"loc-2026-0173\",
      \"tipoContrato\": \"locacao-residencial\"
    },
    \"returnUrl\": \"https://crm.suaimobiliaria.com.br/assinatura/concluida\",
    \"locale\": \"pt-BR\",
    \"expiresInMinutes\": 4320,
    \"owner\": { \"name\": \"Imobiliária Horizonte\", \"email\": \"contratos@suaimobiliaria.com.br\" }
  }"

import { readFileSync } from 'fs';

const pdfBase64 = readFileSync('contrato-locacao.pdf').toString('base64');

const envelope = await client.envelopes.create({
  signingMode: 'SEQUENTIAL',
  totalSigners: 3,
  document: { content: pdfBase64, filename: 'contrato-locacao.pdf' },
  metadata: {
    imovelId: 'imv-8841',
    contratoId: 'loc-2026-0173',
    tipoContrato: 'locacao-residencial',
  },
  returnUrl: 'https://crm.suaimobiliaria.com.br/assinatura/concluida',
  locale: 'pt-BR',
  expiresInMinutes: 4320,
  owner: { name: 'Imobiliária Horizonte', email: 'contratos@suaimobiliaria.com.br' },
});
console.log('Envelope ID:', envelope.envelopeId);

import base64
from signdocs_brasil.models import CreateEnvelopeRequest

with open('contrato-locacao.pdf', 'rb') as f:
    pdf_base64 = base64.b64encode(f.read()).decode()

envelope = client.envelopes.create(CreateEnvelopeRequest(
    signing_mode='SEQUENTIAL',
    total_signers=3,
    document_content=pdf_base64,
    document_filename='contrato-locacao.pdf',
    metadata={
        'imovelId': 'imv-8841',
        'contratoId': 'loc-2026-0173',
        'tipoContrato': 'locacao-residencial',
    },
    return_url='https://crm.suaimobiliaria.com.br/assinatura/concluida',
    locale='pt-BR',
    expires_in_minutes=4320,
))
print('Envelope ID:', envelope.envelope_id)

✅ Dica — informar owner faz a SignDocs enviar automaticamente o e-mail de convite a cada signatário cujo signer.email seja diferente de owner.email, além de notificar a imobiliária a cada assinatura concluída. Omita owner se você mesmo vai entregar os links (ex.: por WhatsApp — veja a etapa 7).

6. Adicionar os signatários na ordem certa

Adicione uma sessão por signatário em POST /v1/envelopes/{envelopeId}/sessions. O campo signerIndex define a ordem de assinatura no modo SEQUENTIAL: o locatário (1) assina primeiro, o fiador (2) em seguida, o locador ou a imobiliária (3) por último. Cada signatário precisa de name, userExternalId e pelo menos um entre cpf e cnpj — use cnpj quando a imobiliária assina como pessoa jurídica.

ENVELOPE_ID="env_01JXYZ..."

# Signatário 1 — locatário (assina primeiro)
curl -s -X POST "$SIGNDOCS_BASE_URL/v1/envelopes/$ENVELOPE_ID/sessions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "signer": { "name": "Ana Pereira", "cpf": "12345678900", "email": "ana@example.com", "userExternalId": "locatario-4402" },
    "policy": { "profile": "CLICK_PLUS_OTP" },
    "purpose": "DOCUMENT_SIGNATURE",
    "signerIndex": 1
  }'

# Signatário 2 — fiador (assina após o locatário)
curl -s -X POST "$SIGNDOCS_BASE_URL/v1/envelopes/$ENVELOPE_ID/sessions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "signer": { "name": "Roberto Dias", "cpf": "98765432100", "email": "roberto@example.com", "userExternalId": "fiador-1188" },
    "policy": { "profile": "CLICK_PLUS_OTP" },
    "purpose": "DOCUMENT_SIGNATURE",
    "signerIndex": 2
  }'

# Signatário 3 — locador / imobiliária (assina por último)
curl -s -X POST "$SIGNDOCS_BASE_URL/v1/envelopes/$ENVELOPE_ID/sessions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "signer": { "name": "Imobiliária Horizonte Ltda", "cnpj": "12345678000199", "email": "contratos@suaimobiliaria.com.br", "userExternalId": "imob-01" },
    "policy": { "profile": "CLICK_PLUS_OTP" },
    "purpose": "DOCUMENT_SIGNATURE",
    "signerIndex": 3
  }'

// 1. Locatário — assina primeiro
const locatario = await client.envelopes.addSession(envelope.envelopeId, {
  signer: { name: 'Ana Pereira', cpf: '12345678900', email: 'ana@example.com', userExternalId: 'locatario-4402' },
  policy: { profile: 'CLICK_PLUS_OTP' },
  purpose: 'DOCUMENT_SIGNATURE',
  signerIndex: 1,
});

// 2. Fiador — assina após o locatário
const fiador = await client.envelopes.addSession(envelope.envelopeId, {
  signer: { name: 'Roberto Dias', cpf: '98765432100', email: 'roberto@example.com', userExternalId: 'fiador-1188' },
  policy: { profile: 'CLICK_PLUS_OTP' },
  purpose: 'DOCUMENT_SIGNATURE',
  signerIndex: 2,
});

// 3. Locador / imobiliária — assina por último
const locador = await client.envelopes.addSession(envelope.envelopeId, {
  signer: { name: 'Imobiliária Horizonte Ltda', cnpj: '12345678000199', email: 'contratos@suaimobiliaria.com.br', userExternalId: 'imob-01' },
  policy: { profile: 'CLICK_PLUS_OTP' },
  purpose: 'DOCUMENT_SIGNATURE',
  signerIndex: 3,
});

console.log('Link locatário:', `${locatario.url}?cs=${locatario.clientSecret}`);
console.log('Link fiador:', `${fiador.url}?cs=${fiador.clientSecret}`);
console.log('Link locador:', `${locador.url}?cs=${locador.clientSecret}`);

from signdocs_brasil.models import AddEnvelopeSessionRequest

# 1. Locatário — assina primeiro
locatario = client.envelopes.add_session(envelope.envelope_id, AddEnvelopeSessionRequest(
    signer_name='Ana Pereira',
    signer_cpf='12345678900',
    signer_email='ana@example.com',
    signer_user_external_id='locatario-4402',
    policy_profile='CLICK_PLUS_OTP',
    purpose='DOCUMENT_SIGNATURE',
    signer_index=1,
))

# 2. Fiador — assina após o locatário
fiador = client.envelopes.add_session(envelope.envelope_id, AddEnvelopeSessionRequest(
    signer_name='Roberto Dias',
    signer_cpf='98765432100',
    signer_email='roberto@example.com',
    signer_user_external_id='fiador-1188',
    policy_profile='CLICK_PLUS_OTP',
    purpose='DOCUMENT_SIGNATURE',
    signer_index=2,
))

# 3. Locador / imobiliária — assina por último
locador = client.envelopes.add_session(envelope.envelope_id, AddEnvelopeSessionRequest(
    signer_name='Imobiliária Horizonte Ltda',
    signer_cnpj='12345678000199',
    signer_email='contratos@suaimobiliaria.com.br',
    signer_user_external_id='imob-01',
    policy_profile='CLICK_PLUS_OTP',
    purpose='DOCUMENT_SIGNATURE',
    signer_index=3,
))

print('Link locatário:', f"{locatario.url}?cs={locatario.client_secret}")
print('Link fiador:', f"{fiador.url}?cs={fiador.client_secret}")
print('Link locador:', f"{locador.url}?cs={locador.client_secret}")

Adaptação para compra e venda: o esqueleto é o mesmo — mude os papéis e o totalSigners. Um contrato de compra e venda típico tem vendedor (signerIndex 1), comprador (2) e, se o seu modelo contratual usar testemunhas, mais duas sessões (3 e 4) com perfil CLICK_PLUS_OTP. Inclua cônjuges como signatários adicionais quando o regime de bens exigir anuência. Para as partes principais de uma operação de alto valor, use policy.profile: "BIOMETRIC" (verificação facial — exige signer.cpf); veja a seção de perfis abaixo.

7. Entregar o link de assinatura

O link que o signatário abre é url + ?cs= + clientSecret. O clientSecret é de uso único e não é armazenado pela SignDocs — monte e entregue o link no momento da criação.

Você tem duas formas de entrega, que podem ser combinadas:

E-mail automático da SignDocs: se o envelope foi criado com owner e o signer.email é diferente do owner.email, cada signatário recebe o convite por e-mail sem código adicional (campo inviteSent: true na resposta).
Seus próprios canais: envie o link por WhatsApp, SMS ou dentro do seu portal. Para WhatsApp, o disparo sai da sua conta WhatsApp Business (via API oficial ou um fluxo n8n/Make) — o WhatsApp é um canal de entrega do link, não uma integração nativa da SignDocs.

No modo SEQUENTIAL, você pode entregar os três links de uma vez: a página de assinatura só libera cada signatário quando chegar a sua vez. Ainda assim, a experiência é melhor quando o seu sistema envia o link do fiador só depois do webhook de conclusão do locatário — ninguém abre link para ver "aguarde sua vez".

⚠️ Cuidado — não registre o link completo (com ?cs=) em logs nem o exiba para quem não é o signatário: quem tem o link consegue abrir a sessão de assinatura.

8. Acompanhar o andamento

Consulte o envelope a qualquer momento para renderizar o status no seu CRM ("aguardando fiador", por exemplo):

curl -s "$SIGNDOCS_BASE_URL/v1/envelopes/$ENVELOPE_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

const status = await client.envelopes.get(envelope.envelopeId);
console.log('Status:', status.status);
console.log('Assinaturas concluídas:', status.completedSessions, '/', status.totalSigners);
for (const s of status.sessions) {
  console.log(`- signerIndex ${s.signerIndex} (${s.signerName}): ${s.status}`);
}

status = client.envelopes.get(envelope.envelope_id)
print('Status:', status.status)
print('Assinaturas concluídas:', status.completed_sessions, '/', status.total_signers)
for s in status.sessions:
    print(f"- signerIndex {s.signer_index} ({s.signer_name}): {s.status}")

Cada sessão concluída traz completedAt e evidenceId. Em produção, prefira webhooks a polling — veja a seção de webhooks abaixo.

9. Baixar o documento final e as evidências

Quando todas as sessões estiverem concluídas, gere o carimbo combinado: um único PDF com o carimbo de todas as assinaturas do envelope. A resposta traz uma downloadUrl pré-assinada e temporária (expiresIn em segundos) — baixe e arquive no seu storage.

STAMP=$(curl -s -X POST "$SIGNDOCS_BASE_URL/v1/envelopes/$ENVELOPE_ID/combined-stamp" \
  -H "Authorization: Bearer $ACCESS_TOKEN")

DOWNLOAD_URL=$(echo "$STAMP" | jq -r '.downloadUrl')
curl -s -o contrato-locacao-assinado.pdf "$DOWNLOAD_URL"

import { writeFileSync } from 'fs';

const stamp = await client.envelopes.combinedStamp(envelope.envelopeId);
console.log('Assinaturas no carimbo:', stamp.signerCount);
console.log('Download (expira em', stamp.expiresIn, 's):', stamp.downloadUrl);

const res = await fetch(stamp.downloadUrl);
writeFileSync('contrato-locacao-assinado.pdf', Buffer.from(await res.arrayBuffer()));

from pathlib import Path
import httpx

stamp = client.envelopes.combined_stamp(envelope.envelope_id)
print('Assinaturas no carimbo:', stamp.signer_count)
print(f'Download (expira em {stamp.expires_in}s):', stamp.download_url)

Path('contrato-locacao-assinado.pdf').write_bytes(httpx.get(stamp.download_url).content)

Além do PDF, cada assinatura gera um pacote de evidências: JSON com a trilha de auditoria completa (aceites, OTP, IP, geolocalização, hash SHA-256 do documento, timestamps ISO do servidor), assinado em PKCS#7/CMS (.p7m) com certificado ICP-Brasil A1. Guarde o evidenceId de cada sessão; qualquer pessoa pode conferir a autenticidade depois via GET /v1/verify/{evidenceId} ou enviando o PDF a POST /v1/verify/document.

Webhooks: reagindo à conclusão

Registre um webhook para avançar o funil do seu CRM sem polling:

curl -s -X POST "$SIGNDOCS_BASE_URL/v1/webhooks" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://crm.suaimobiliaria.com.br/webhooks/signdocs",
    "events": ["ENVELOPE.ALL_SIGNED", "STEP.COMPLETED", "SIGNING_SESSION.EXPIRED"]
  }'

Evento	Uso no fluxo imobiliário
`STEP.COMPLETED`	Uma etapa de assinatura foi concluída — avance o card no funil ("locatário assinou → cobrar fiador") e dispare o link do próximo signatário
`ENVELOPE.ALL_SIGNED`	Todas as partes assinaram — gere o carimbo combinado, arquive o PDF e libere a próxima fase (vistoria, chaves, caução)
`SIGNING_SESSION.EXPIRED`	Um signatário não assinou no prazo — notifique o corretor para reengajar a parte

Guarde o secret retornado no registro: ele é exibido só uma vez e é a chave da validação HMAC-SHA256 de cada payload recebido (recuse requisições com assinatura inválida). Especificação completa, payloads e handlers de exemplo em webhooks.

Escolhendo o perfil de política

Perfil	Verificação	Indicação no imobiliário
`CLICK_ONLY`	Aceite com um clique	Documentos acessórios de baixo risco (termo de visita, autorização de anúncio)
`CLICK_PLUS_OTP`	Aceite + código OTP por e-mail/SMS	Default recomendado para locação: prova posse do e-mail/telefone do locatário e do fiador sem atrito
`BIOMETRIC`	Verificação facial com prova de vida (exige `signer.cpf`)	Recomendado para compra e venda de alto valor: vincula a assinatura ao rosto do signatário
`DIGITAL_CERTIFICATE`	Certificado digital ICP-Brasil (e-CPF/e-CNPJ)	Quando uma das partes exige assinatura com certificado ICP-Brasil (comum em locação comercial corporativa)

Você pode misturar perfis no mesmo envelope: numa compra e venda, vendedor e comprador com BIOMETRIC, testemunhas com CLICK_PLUS_OTP. Existe ainda BIOMETRIC_PLUS_OTP para o rigor máximo sem certificado. Sobre o enquadramento jurídico de cada nível (MP 2.200-2/2001 art. 10 §2º para perfis eletrônicos; ICP-Brasil para DIGITAL_CERTIFICATE), veja perfis de assinatura e níveis legais.

Caminho sem código

Sua operação ainda não tem time de engenharia disponível? Dois atalhos:

n8n: importe o template n8n de pipeline imobiliário — do lead à assinatura: novo lead → proposta gerada no Google Docs → exporta PDF → cria o envelope na SignDocs → envia o link de assinatura pelo WhatsApp Business da sua imobiliária. Guia completo em integração n8n.
Make.com: o app SignDocs Brasil tem módulos prontos de Criar Envelope, Adicionar Sessão ao Envelope e Baixar Carimbo Combinado, além do trigger instantâneo de webhook. Veja integração Make.

⚠️ Sobre WhatsApp — em qualquer variante, o envio por WhatsApp sai da conta WhatsApp Business do seu negócio (API oficial da Meta, ou o nó de WhatsApp do n8n/Make). A SignDocs gera o link de assinatura; o WhatsApp é apenas o canal por onde você o entrega — não há integração nativa SignDocs↔WhatsApp.

Há também integração Zapier e um servidor MCP para operar a API a partir de assistentes de IA.

Erros comuns

1. Signatário sem CPF/CNPJ

{ "status": 422, "title": "Unprocessable Entity",
  "detail": "signer: é obrigatório informar pelo menos um entre cpf e cnpj." }

Toda sessão de envelope exige signer.cpf (11 dígitos, sem pontuação) ou signer.cnpj (14 dígitos). Para BIOMETRIC, o cpf é obrigatório.

2. Carimbo combinado antes da hora

{ "status": 409, "title": "Conflict",
  "detail": "Envelope has pending sessions; combined stamp is available after all sessions complete." }

POST /v1/envelopes/{envelopeId}/combined-stamp só funciona com todas as sessões concluídas. Aguarde o webhook ENVELOPE.ALL_SIGNED antes de chamar.

3. Mais sessões que totalSigners

{ "status": 409, "title": "Conflict",
  "detail": "Envelope already has 3 of 3 sessions." }

O envelope aceita exatamente totalSigners sessões. Numa compra e venda com testemunhas, dimensione totalSigners na criação — não dá para aumentar depois; crie um novo envelope.

4. Perfil de política inválido

{ "status": 400, "title": "Bad Request",
  "detail": "policy.profile: valor inválido. Use CLICK_ONLY, CLICK_PLUS_OTP, BIOMETRIC, BIOMETRIC_PLUS_OTP, DIGITAL_CERTIFICATE ou CUSTOM." }

policy.profile aceita apenas o enum acima — nomes de etapas internas (como DIGITAL_SIGN_A1, que aparece nas respostas como tipo de etapa) não são perfis.

5. Token expirado

{ "status": 401, "title": "Unauthorized",
  "detail": "Token de acesso inválido ou expirado." }

O access_token tem vida curta; renove via POST /oauth2/token em caso de 401 (os SDKs fazem isso sozinhos).

Perguntas frequentes

Contrato de locação assinado eletronicamente tem validade jurídica?

Sim. A assinatura eletrônica tem validade fundada na MP 2.200-2/2001, art. 10 §2º, com base no consentimento das partes quanto ao meio utilizado. O pacote de evidências da SignDocs — hash SHA-256 do documento, trilha de auditoria, timestamps do servidor e assinatura com certificado ICP-Brasil sobre o conjunto — documenta quem assinou, o quê e quando. Detalhes por perfil em perfis de assinatura e níveis legais.

O fiador pode assinar o contrato de locação eletronicamente?

Pode, como qualquer outro signatário do envelope. A vantagem do modo SEQUENTIAL é reproduzir a prática de mercado: o fiador (assinatura eletrônica com OTP ou biometria) só é chamado a assinar depois que o locatário concluiu, e a evidência registra essa ordem. Se o seu jurídico exigir anuência do cônjuge do fiador, adicione-o como signatário extra.

Contrato de compra e venda de imóvel pode ser assinado online?

O instrumento particular (promessa ou contrato de compra e venda) pode ser assinado eletronicamente entre as partes. Exigências de escritura pública e registro em cartório dependem do tipo de operação e do valor — isso não muda com a assinatura eletrônica; valide o enquadramento do seu caso com a assessoria jurídica. Para essas operações, recomendamos o perfil BIOMETRIC para as partes principais.

Posso enviar o link de assinatura por WhatsApp?

Sim — o link (url + ?cs= + clientSecret) é uma URL comum e pode ser entregue por qualquer canal seu: WhatsApp Business da imobiliária, SMS, e-mail ou portal do cliente. O envio parte da sua conta WhatsApp (diretamente ou via n8n/Make); a SignDocs não envia mensagens de WhatsApp.

E se o fiador demorar a assinar?

O envelope vale pelo prazo definido em expiresInMinutes (no exemplo, 72 horas). Use o webhook SIGNING_SESSION.EXPIRED para acionar o corretor, e STEP.COMPLETED para saber exatamente em qual parte o fluxo parou. Expirou de vez? Crie um novo envelope — o PDF e os dados dos signatários já estão no seu sistema, é uma chamada de API.

Como provo depois quem assinou e quando?

Cada assinatura gera um pacote de evidências em PKCS#7/CMS (.p7m) assinado com certificado ICP-Brasil A1, contendo a trilha de auditoria, o hash SHA-256 do documento e os timestamps ISO do servidor. Qualquer terceiro pode verificar via GET /v1/verify/{evidenceId}, ou enviando o PDF assinado a POST /v1/verify/document.

Próximos passos

Envelopes de assinatura expressa — referência completa da primitiva usada neste guia.
Perfis de assinatura e níveis legais — escolha o nível de verificação certo por tipo de contrato.
Webhooks — validação HMAC, reentregas e todos os eventos.
SDKs para envelopes — Go, Java, PHP e C#.
Modelo de solução: proposta comercial — feche a proposta antes do contrato com o mesmo padrão.
Hub de modelos de solução e referência completa da API.