Transação, sessão de assinatura ou envelope: qual API usar

Quem abre a referência da API pela primeira vez encontra 44 endpoints e três caminhos diferentes que parecem fazer a mesma coisa: POST /v1/transactions, POST /v1/signing-sessions e POST /v1/envelopes. Os três terminam em um documento assinado com evidência, e a documentação de cada um funciona isoladamente — o que torna fácil escolher o primeiro que aparece e descobrir o problema tarde. E o problema tem um formato específico: uma transação carrega um signatário e um documento. Se o segundo signatário aparecer depois que o fluxo estiver pronto, não há campo para acrescentá-lo. Este guia mostra o que cada modelo assume, para você escolher uma vez.

Os quatro modelos

A coluna "Documento" é a que mais surpreende: ela nunca passa de 1. Não existe envelope com vários documentos. Voltaremos a isso.

Transação: o registro do ato

A transação é a unidade fundamental — tudo o mais acaba criando uma. Ela amarra quatro coisas: quem (o signatário), o quê (o documento), como (a política de verificação) e o resultado (as etapas executadas e a evidência).

Repare no singular: signer, não signers. Não é uma limitação a contornar — é o modelo. Não existe campo para acrescentar uma segunda pessoa, nem no momento da criação nem depois.

Escolha transações quando você conduz o fluxo: sua aplicação chama /steps/{id}/start e /steps/{id}/complete, desenha a própria interface e decide o que mostrar a cada passo. É o caminho de maior controle e maior trabalho.

Sessão de assinatura: a porta pronta

A sessão cria a transação por baixo e devolve, na mesma resposta, tudo o que é preciso para colocar a pessoa para assinar:

O link final é a url com o segredo anexado como parâmetro. A partir daí, quem conduz as etapas é a página de assinatura — a sua integração só acompanha por /status ou por webhook.

Note que transactionId vem na resposta. Ele é o que você usa para buscar a evidência e o documento assinado depois: a sessão é a porta, a transação é o registro.

Envelope: vários signatários, um documento

O envelope é criado em duas etapas — primeiro o continente, depois cada pessoa:

Três propriedades que valem conhecer antes de decidir:

A política é por signatário. O comprador pode assinar com clique e código enquanto o avalista assina com biometria e o representante da empresa com certificado ICP-Brasil — no mesmo documento. Isso não é possível com transações avulsas, porque não haveria um documento comum.

O modo é do envelope inteiro. SEQUENTIAL convida um de cada vez, na ordem dos índices; PARALLEL convida todos ao mesmo tempo. Não há modo híbrido por grupos. O detalhamento está em ordem sequencial vs paralela.

O teto é 100 signatários, e o motivo é técnico e vale saber: toda leitura de envelope é feita em uma consulta única e não paginada ao índice, então o conjunto de signatários precisa caber em uma página de 1 MB. Além disso, a consulta truncaria em silêncio — a verificação de índice duplicado deixaria de enxergar signatários já existentes e a validação de ordem passaria a rejeitar alguém cujo antecessor realmente concluiu. O 400 explícito é preferível a essa classe de corrupção invisível.

O limite que não tem contorno: um documento por envelope

Esta é a pergunta que mais aparece, e a resposta é curta: envelope com vários documentos não existe. O envelope resolve muitas pessoas sobre um arquivo, não muitos arquivos.

Para um pacote que deve ser assinado junto — contrato, anexo técnico e procuração —, o padrão é encadear:

É mais trabalho, e tem uma vantagem que quase compensa: cada documento fica com o próprio pacote de evidências, independente dos demais. Se um deles for contestado, a prova daquele ato não depende dos outros. Sobre o consumo de plano, note que cada envelope é um documento para efeito de cota.

Sessão de Confiança: quando não há documento

Nem todo ato que precisa de identidade tem um PDF. Aprovar uma transferência, confirmar uma troca de conta bancária, liberar um acesso privilegiado — são atos, e o que se quer registrar é quem autorizou o quê, quando.

A mesma escada de verificação de identidade se aplica — clique, código, biometria, certificado. A diferença é que o objeto do ato é a descrição, não um arquivo.

Como escolher, na prática

A quarta linha é a recomendação mais útil deste artigo. Na dúvida entre transação e envelope, escolha envelope. Ele aceita um signatário sem cerimônia, e a migração no sentido contrário é barata; a migração de transação para envelope não é.

O custo de descobrir tarde

Vale ser concreto sobre o que muda quando um segundo signatário aparece numa integração feita com transações:

• O endpoint de criação muda, e com ele o formato do corpo.
• Passa a existir um passo novo — criar o envelope antes de criar as sessões — que não tinha equivalente.
• O evento de conclusão deixa de ser TRANSACTION.COMPLETED e passa a ser ENVELOPE.ALL_SIGNED: quem escuta o evento antigo vai processar o fim do primeiro signatário como se fosse o fim do negócio.
• O PDF final deixa de ser o download da transação e passa a ser o carimbo combinado do envelope.
• Aparece a ordenação — sequencial ou paralela — que antes não existia como conceito.

São cinco pontos do código, não uma flag. Meia hora de decisão no começo evita uma refatoração no meio.

Escolhido o modelo, os próximos passos costumam ser entender os prazos que governam cada objeto, quem autentica cada rota em os dois tokens da API, e o mapa de escopos. Para o passo zero, a primeira assinatura em 5 minutos.

Perguntas Frequentes