Múltiplos Signatários: Ordem Sequencial vs Paralela via API

Quase todo contrato relevante envolve mais de uma assinatura: o cliente e o fornecedor, o colaborador e o gestor, o locatário, o locador e duas testemunhas. Orquestrar esses fluxos via API significa decidir quem assina, em que ordem e sob qual condição — e isso muda completamente conforme você adota um modelo paralelo (todos assinam ao mesmo tempo) ou sequencial (roteamento ordenado, um signatário de cada vez).

Este guia mostra como modelar os dois cenários na API do SignDocs: como o signingMode e o signerIndex definem a ordem, como dar a cada signatário um nível de autenticação diferente, como fazer roteamento condicional adicionando sessões dinamicamente, como tratar cancelamentos e como distribuir o documento final a quem não assina. Vamos apresentar o JSON real dos dois modos lado a lado e uma tabela comparativa para ajudar você a escolher o fluxo certo para cada caso de uso.

Se você ainda está conhecendo a plataforma, vale começar pela visão geral da API de assinatura digital e pelo conceito central que sustenta tudo o que veremos aqui: o envelope.

O envelope: a unidade que agrupa múltiplos signatários

Antes de falar de ordem, é preciso entender a peça que torna o multi-signatário possível: o envelope. Em vez de criar uma sessão de assinatura isolada para cada pessoa, você cria um único envelope que agrupa:

• O documento a ser assinado (um PDF em base64, com hash SHA-256 calculado no servidor);
• O modo de assinatura — SEQUENTIAL (ordenado) ou PARALLEL (todos ao mesmo tempo);
• O total de signatários (totalSigners, até 100 por envelope);
• Uma sessão de assinatura por signatário, cada uma com sua própria política de autenticação;
• A expiração (expiresInMinutes) e o remetente (owner) para convites por e-mail;
• O pacote de evidências de cada assinatura, consolidado ao final.

O envelope é a fronteira transacional do fluxo. É ele que garante que, ao final, todas as assinaturas estejam ancoradas ao mesmo documento — o mesmo hash SHA-256 — com trilha de auditoria unificada, e não espalhadas em documentos independentes. Ao final, a API disponibiliza o documento consolidado com o carimbo de cada assinatura e o pacote de evidências de cada signatário — entenda o que vai dentro dele no guia do pacote de evidências .p7m.

Paralelo vs. sequencial: dois modelos de roteamento

A decisão fundamental ao montar um envelope multi-signatário é como os convites de assinatura são distribuídos no tempo. No SignDocs, essa decisão é o campo signingMode, definido na criação do envelope.

Assinatura paralela (todos ao mesmo tempo)

No modo paralelo, todos os signatários recebem o convite simultaneamente, no momento em que o envelope é enviado. Cada um pode assinar quando quiser, independentemente dos demais. A transação só é concluída quando o último signatário pendente assina. Não há dependência de ordem: a testemunha A pode assinar antes ou depois da testemunha B, sem qualquer impacto.

Assinatura sequencial (roteamento ordenado)

No modo sequencial, a API impõe a ordem da fila: cada signatário só consegue concluir a assinatura depois que o anterior termina — quem tenta fora da vez é avisado de que ainda não chegou o seu momento. Você escolhe como distribuir os convites: criar todas as sessões de uma vez (a ordem é imposta na hora de assinar) ou criar cada sessão apenas quando chegar a vez daquele signatário. Esse modelo respeita hierarquias e dependências jurídicas — por exemplo, o colaborador assina primeiro, depois o gestor valida, e só então o diretor formaliza.

E os fluxos híbridos?

No SignDocs, o modo vale para o envelope inteiro: SEQUENTIAL ou PARALLEL — não há grupos mistos dentro de um mesmo envelope. Quando você precisa de uma topologia híbrida (por exemplo, dois sócios assinando em paralelo antes de o representante da outra parte ser acionado), o padrão é encadear envelopes via webhook: crie um envelope paralelo para o primeiro grupo e, ao receber o evento ENVELOPE.ALL_SIGNED, crie o envelope seguinte. Mostramos esse padrão em detalhe mais adiante.

Tabela comparativa: sequencial vs. paralela

A escolha entre os dois modelos depende do caso de uso, do risco jurídico e da experiência que você quer oferecer. A tabela abaixo resume as diferenças práticas.

Modelando o fluxo paralelo via API (JSON)

São duas chamadas: primeiro você cria o envelope com signingMode: "PARALLEL", depois adiciona uma sessão por signatário. No modo paralelo, todas as sessões podem ser assinadas imediatamente, em qualquer ordem. Veja um envelope com três testemunhas:

Cada sessão criada devolve sua própria url de assinatura e clientSecret. Como o envelope tem um owner, a SignDocs envia o convite por e-mail a cada signatário automaticamente (quando o e-mail do signatário difere do e-mail do owner). Cada assinatura concluída gera um evento SIGNING_SESSION.COMPLETED, e quando a terceira sessão conclui, a API emite ENVELOPE.ALL_SIGNED. Para reagir a esses eventos em tempo real, integre o seu sistema via webhooks de eventos da API.

Modelando o fluxo sequencial via API (JSON)

No fluxo sequencial, o signerIndex de cada sessão define a posição na fila: o signatário 2 só consegue assinar depois que o 1 conclui, e assim por diante. Um bônus poderoso do modelo por sessão é que cada signatário pode ter uma política de autenticação diferente. Veja um fluxo de aprovação hierárquica em três níveis:

Aqui, Diego (índice 1) pode assinar imediatamente; Elaine (índice 2) só consegue concluir depois dele — se tentar antes, a página de assinatura avisa que ainda não é a vez dela — e Fábio (índice 3) fecha o fluxo com certificado ICP-Brasil. Repare na gradação de autenticação por nível de responsabilidade: aceite + OTP para o colaborador, biometria facial para a gestora e certificado digital para o diretor. Essa flexibilidade por signatário é nativa do modelo de sessões.

Topologias híbridas: encadeando envelopes via webhook

Como o signingMode vale para o envelope inteiro, topologias mistas são modeladas encadeando envelopes. Considere um contrato onde dois sócios da contratante assinam em paralelo, e só depois o representante da contratada e uma testemunha são acionados — também em paralelo entre si:

A regra é simples: cada grupo paralelo vira um envelope, e a sequência entre grupos é orquestrada pelo seu backend reagindo a ENVELOPE.ALL_SIGNED. A lógica condicional fica no seu lado — o que, na prática, dá mais controle do que um roteamento fixo declarado na criação.

Um nível de autenticação para cada signatário

Nem todo signatário de um envelope precisa do mesmo rigor de autenticação. Como cada sessão carrega sua própria policy, você gradua o método pelo papel de cada pessoa no negócio:

Combinar a ordem do signerIndex com o método de autenticação certo por signatário é o que dá flexibilidade ao fluxo: um colaborador interno via aceite + OTP e o diretor via certificado ICP-Brasil, no mesmo envelope. Veja a lista completa de perfis na seção de métodos de autenticação de o que é uma API de assinatura digital.

Roteamento condicional e lembretes por signatário

Roteamento condicional

Em cenários avançados, a próxima etapa de um fluxo sequencial pode depender de uma condição — por exemplo, acionar um segundo aprovador apenas se o valor do contrato ultrapassar um limite. Como as sessões são adicionadas uma a uma via POST /v1/envelopes/{id}/sessions, você pode adiar a criação das sessões seguintes: anexe metadata ao envelope, aguarde o evento SIGNING_SESSION.COMPLETED do signatário anterior e decida no seu backend se (e com qual política) cria a próxima sessão. Essa orquestração condicional mantém a lógica de negócio no seu lado, enquanto a API cuida da ordem e das evidências.

Lembretes por signatário

A API não tem uma política de lembretes recorrentes configurável — e isso é deliberado: o ritmo de cobrança é seu. O que ela oferece são os sinais e as alavancas certas: o evento TRANSACTION.DEADLINE_APPROACHING avisa quando o prazo de um signatário está apertando; GET /v1/envelopes/{id} lista o status de cada sessão para você saber exatamente quem está pendente; e POST /v1/signing-sessions/{sessionId}/resend-invite reenvia o convite por e-mail ao signatário. Se preferir cobrar por outro canal (WhatsApp, Telegram), a URL de assinatura da sessão permanece válida até a expiração — reenviar o lembrete é simplesmente reenviar o mesmo link.

O que acontece quando alguém não assina

A não-assinatura é um caminho que toda integração multi-signatário precisa tratar. No modelo do SignDocs, ela se manifesta de três formas, cada uma com seu sinal:

• O signatário comunica que não vai assinar: sua aplicação (ou o remetente) cancela a sessão dele via POST /v1/signing-sessions/{sessionId}/cancel — ou cancela o envelope inteiro via POST /v1/envelopes/{envelopeId}/cancel. A API emite SIGNING_SESSION.CANCELLED e, no cancelamento do envelope, ENVELOPE.CANCELLED.
• Uma etapa obrigatória falha: se a verificação biométrica ou o certificado não passam, o evento é STEP.FAILED e a transação daquele signatário pode terminar em FAILED.
• O prazo vence: sessões não concluídas expiram (SIGNING_SESSION.EXPIRED / ENVELOPE.EXPIRED), precedidas do aviso TRANSACTION.DEADLINE_APPROACHING.

Em fluxo sequencial, um cancelamento interrompe a cadeia — quem ainda não chegou à vez não assina. Em fluxo paralelo, outros signatários podem já ter concluído quando o cancelamento acontece. Em ambos os casos, cabe à sua aplicação decidir a próxima ação: corrigir o documento e criar um novo envelope, ou iniciar uma renegociação. Veja como o evento chega ao seu webhook:

Para saber quem já havia assinado antes do cancelamento, consulte GET /v1/envelopes/{envelopeId} — a resposta lista cada sessão com seu status individual. As assinaturas concluídas permanecem com suas evidências preservadas, informação valiosa para decidir se vale recriar o envelope ou recomeçar do zero.

Quem não assina, mas precisa do documento — e o pacote de evidências final

Em ambientes corporativos, sempre há quem precise do documento sem assinar: o jurídico quer arquivar o contrato, o financeiro precisa do gatilho para faturar, o compliance exige rastreabilidade. A API não tem um papel de "observador" — o padrão é a sua aplicação fazer essa distribuição: ao receber o evento ENVELOPE.ALL_SIGNED, seu backend baixa o documento consolidado (via POST /v1/envelopes/{envelopeId}/combined-stamp, que aplica o carimbo de todas as assinaturas) e o encaminha aos interessados pelos seus próprios canais. Se o envelope tem um owner, o remetente também recebe notificações de conclusão por e-mail a cada assinatura.

Independentemente de quantos signatários participaram ou da ordem em que assinaram, o resultado é o documento consolidado com o carimbo de cada assinatura, mais um pacote de evidências .p7m por assinatura que registra cada etapa: quando assinou, de qual IP e geolocalização, sob qual método de autenticação e o carimbo de hora do servidor (timestamps ISO-8601 registrados pelos servidores da SignDocs) de cada ato, ancorados ao hash SHA-256 do documento. Esse pacote é o que confere validade jurídica e auditabilidade ao fluxo multi-signatário — entenda em detalhes no guia sobre o pacote de evidências .p7m como prova jurídica.

Envelope multi-signatário vs. assinatura em lote

Vale distinguir dois conceitos que às vezes se confundem. Um envelope multi-signatário agrupa várias pessoas assinando o mesmo documento, com ordem e roteamento entre elas. Já a assinatura em lote trata de processar muitos documentos independentes de uma só vez — por exemplo, enviar 500 contratos idênticos, cada um para um signatário diferente.

São padrões complementares: no SignDocs, o alto volume é modelado criando uma transação (ou envelope) por documento em um laço no seu backend — cada uma independente, com seus próprios webhooks — como mostramos no exemplo de admissões em escala do guia de API de assinatura para RH. E se você ainda está montando o primeiro envio, comece pelos primeiros passos em 5 minutos.

Boas práticas para fluxos multi-signatário

1. Escolha o modelo pelo risco, não pela velocidade. Se a ordem das assinaturas tem efeito jurídico, use SEQUENTIAL mesmo que seja mais lento. Use PARALLEL apenas quando a ordem for genuinamente irrelevante.
2. Sempre trate os eventos de não-assinatura. SIGNING_SESSION.CANCELLED, STEP.FAILED e ENVELOPE.EXPIRED não tratados deixam o fluxo preso no seu lado. Defina o comportamento de recuperação no seu backend.
3. Implemente idempotência nos webhooks. Eventos podem chegar duplicados; processe cada id de evento uma única vez.
4. Use metadata para correlacionar. Anexe o ID do seu negócio (deal, contrato, processo) ao envelope para roteamento condicional e integração com CRM/ERP.
5. Cobre o signatário da vez. Em fluxos sequenciais longos, reaja a TRANSACTION.DEADLINE_APPROACHING reenviando o convite (resend-invite) ou o link — é a melhor alavanca contra gargalos.
6. Automatize a distribuição final. Ao receber ENVELOPE.ALL_SIGNED, gere o documento consolidado (combined-stamp) e encaminhe ao jurídico/compliance — isso evita reencaminhamentos manuais.