Guias de Desenvolvimento

Política e Conformidade

Signing Sessions

Sessão de Confiança

Modelos de Solução

Guias dos SDKs

Modelos de Solução — Fluxos de Assinatura Eletrônica por Cenário de Negócio

Os modelos de solução são guias ponta a ponta que mostram como resolver um fluxo de negócio real com a API da SignDocs Brasil — do problema (contrato parado, consentimento sem registro, aprovação por e-mail sem prova) até o resultado auditável: documento assinado com validade fundada na MP 2.200-2/2001 e pacote de evidências assinado com certificado ICP-Brasil. Cada guia cobre o fluxo completo: autenticação OAuth2, criação da sessão ou envelope, entrega do link ao signatário, acompanhamento por webhooks e download da evidência.

Como usar: escolha o cenário mais próximo do seu processo nas tabelas abaixo, siga o passo a passo em HML (https://api-hml.signdocs.com.br — credenciais de homologação não consomem cota e os dados expiram em 7 dias) e depois adapte os campos de metadata, o perfil de política e a entrega do link à sua realidade. Mesmo que o seu caso não esteja listado, os blocos de construção são sempre os mesmos.

🟠 HML vs Produção — desenvolva sempre em HML (api-hml.signdocs.com.br). Ative credenciais HML em ~3 minutos, self-service, pelo wizard de plano em app.signdocs.com.br — requer conta PJ (CNPJ), via web ou Android.

Como escolher a primitiva

Toda solução combina uma ou mais das três primitivas da API. A escolha depende de quantas pessoas assinam e se existe um documento envolvido:

Primitiva Quando usar Endpoint Guia
Sessão de Assinatura 1 signatário, 1 documento, 1 chamada de API — o caso mais comum POST /v1/signing-sessions Assinatura expressa
Envelope 2 ou mais signatários no mesmo documento, em ordem (SEQUENTIAL) ou simultâneos (PARALLEL) POST /v1/envelopes Envelopes
Sessão de Confiança Autenticar uma ação sem documento: aprovação interna, consentimento LGPD, verificação de identidade (KYC) POST /v1/trust-sessions Sessão de confiança

Em todos os casos, o resultado inclui trilha de auditoria, hash SHA-256 e pacote de evidências verificável — a diferença está no formato do fluxo, não na força da prova.

RH e Departamento Pessoal

Admissões e contratos de trabalho normalmente exigem mais de um signatário (colaborador + representante da empresa), por isso os dois cenários usam envelope sequencial:

Cenário Primitiva Perfil recomendado Guia
Onboarding de Colaboradores Envelope SEQUENTIAL CLICK_PLUS_OTP Ver guia
Contrato de Trabalho CLT Envelope SEQUENTIAL CLICK_PLUS_OTP Ver guia

Imobiliário

Locação e compra e venda envolvem tipicamente três partes — locador/vendedor, locatário/comprador e imobiliária ou fiador — assinando em ordem definida:

Cenário Primitiva Perfil recomendado Guia
Locação e Compra e Venda Envelope SEQUENTIAL (3 signatários) CLICK_PLUS_OTP ou BIOMETRIC Ver guia

Financeiro e Compliance

Nem tudo é assinatura de documento: verificar a identidade de um cliente ou aprovar um cadastro são ações autenticadas por sessão de confiança, que pode ser combinada com um envelope quando há contrato ao final:

Cenário Primitiva Perfil recomendado Guia
KYC de Clientes Sessão de confiança BIOMETRIC Ver guia
Onboarding de Fornecedores Sessão de confiança + envelope CLICK_PLUS_OTP Ver guia

Vendas

Proposta comercial assinada pelo cliente, com aprovação interna do desconto registrada como evidência antes do envio:

Cenário Primitiva Perfil recomendado Guia
Proposta Comercial Sessão de assinatura + sessão de confiança (aprovação) CLICK_ONLY Ver guia

Jurídico

Procurações pedem vínculo forte entre signatário e identidade — biometria facial mais código OTP:

Cenário Primitiva Perfil recomendado Guia
Procuração Particular Sessão de assinatura BIOMETRIC_PLUS_OTP Ver guia

Seguros

Proposta assinada pelo segurado e emissão da apólice condicionada à aprovação da subscrição:

Cenário Primitiva Perfil recomendado Guia
Proposta e Apólice Sessão de assinatura + sessão de confiança (aprovação) CLICK_PLUS_OTP Ver guia

✅ Dica — em dúvida sobre o perfil de política, comece com CLICK_PLUS_OTP e consulte Perfis de assinatura e níveis legais antes de subir ou descer o nível de autenticação.

Sem código

Vários desses fluxos podem ser montados sem escrever uma linha de código:

A própria SignDocs também entrega o link por WhatsApp ou Telegram — veja Entrega do convite, abaixo. Se preferir usar a sua própria conta do WhatsApp Business, os templates de n8n e Make acima continuam valendo; a sessão é sempre criada pela API da SignDocs.

Entrega do convite: e-mail, WhatsApp e Telegram

A SignDocs entrega o link de assinatura por três canais. WhatsApp e Telegram são habilitados sob demanda: peça ao time comercial para provisionar o seu tenant — não é uma chave que se liga pelo painel.

O canal é escolhido por signatário, no campo deliverVia (array, na raiz do corpo da requisição), e fica gravado: um reenvio sem corpo (POST /v1/signing-sessions/{sessionId}/resend-invite) usa os mesmos canais. Omitir o campo mantém o comportamento anterior: apenas e-mail.

Num envelope SEQUENTIAL, cada signatário recebe o convite pelos canais que escolheu, quando chega a vez dele.

whatsappInviteSent: true significa que a Meta aceitou a mensagem, não que ela foi entregue ou lida; em qualquer outro caso o campo é simplesmente omitido da resposta. Se a Meta reportar falha e o signatário tiver e-mail, a SignDocs reenvia o convite por e-mail automaticamente — com um link novo, diferente do que veio na resposta da criação. Não há webhook, campo ou endpoint que informe esse reenvio.

Um signatário que responder "parar", "sair" ou "stop" deixa de receber mensagens da SignDocs por WhatsApp.

Cada envio por WhatsApp e cada código pelo Telegram Gateway consome a cota de mensagens do tenant; esgotada a cota, a requisição é recusada com 429 antes de qualquer envio. As mensagens do bot do Telegram contam num limite próprio.

Não achou seu cenário?

Os blocos de construção são os mesmos em qualquer fluxo: sessões de assinatura, envelopes, sessões de confiança, webhooks e pacote de evidências. Combine-os para o seu caso:

Se o seu processo não se encaixa em nenhum modelo, escreva para enterprise@signdocs.com.br descrevendo o fluxo — ajudamos a desenhar a solução e, se fizer sentido, ela vira o próximo guia desta seção.