APIs Nova Gestão de Envelopes

1. Conceito

Nesta página serão detalhadas as APIs da funcionalidade Nova Gestão de Envelopes. Para mais informações sobre a funcionalidade, consulte a documentação.

A Nova Gestão de Envelopes centraliza as operações na API newEnvelope (versão 2), substituindo o fluxo anterior e proporcionando maior flexibilidade na criação e gerenciamento de envelopes. Com essa evolução, é possível:

• criar envelopes como rascunho para posterior revisão e envio.
• criar e enviar envelopes diretamente para assinatura em uma única chamada, sem necessidade de etapa intermediária.
• vincular documentos do GED ao envelope.
• associar contatos previamente cadastrados como signatários, agilizando o preenchimento das informações.

Para realizar o acesso via API, utilize o endpoint:

POST /rest/platform/sign/actions/newEnvelope

2. Pré-requisitos

Os pré-requisitos para utilização das APIs são os mesmos descritos na documentação da Nova Gestão de Envelopes .

3. APIs

3.1 Criar Envelope como Rascunho - newEnvelope

Permite criar um envelope no estado de rascunho para revisão posterior antes do envio para assinatura. Este é o comportamento padrão da API.

Ao criar um envelope como rascunho, o sistema registra todas as informações do envelope (nome, signatários, documentos e configurações), sem iniciar o processo de assinatura. O envelope fica com status DRAFT e pode ser editado livremente antes do envio.

• URL (acesso)
• Parâmetros Principais
• Exemplo
• Resposta
• Multijurisdição ao Criar um Envelope
• Observações

URL

Parâmetros Principais

Exemplo:

{

					"configuration": {

					"name": "Contrato de Prestação de Serviços",

					"daysToExpire": 30,

					"askGeolocation": "DONT_ASK_LOCATION",

					"instructionsToSigner": "Por favor, leia atentamente antes de assinar.",

					"mandatoryView": true,

					"notificateAuthor": true,

					"recurrentNotificationIntervalDays": 7

					},

					"signers": [

					{

					"name": "Maria Silva",

					"email": "maria.silva@empresa.com",

					"signerType": "MANDATORY",

					"signerSubtype": "SIGN",

					"orderSign": 1,

					"communicationChannel": {

					"email": true,

					"platform": true

					}

					},

					{

					"name": "João Souza",

					"email": "joao.souza@empresa.com",

					"signerType": "MANDATORY",

					"signerSubtype": "SIGN_ATTESTANT",

					"orderSign": 2

					}

					],

					"documentsVersions": [

					{

					"documentVersionId": "01cfdf64-b8ca-4a59-a318-5ad84710072e",

					"envelopePosition": 1,

					"documentVersionUrl": "https://ged.exemplo.com/documents/01cfdf64",

					"originalFileName": "contrato-servicos.pdf"

					}

					],

					"draft": true

			}

Resposta

{
					"envelopeId": "772832cf-6922-4670-8bd3-56f3f1dca92d"
			}

Multijurisdição ao Criar um Envelope

Caso o usuário possua a Multijurisdição habilitada, ao criar um envelope, é possível selecionar a qual jurisdição o mesmo pertencerá. É permitido apenas uma jurisdição por envelope:

Ao selecionar uma jurisdição, apenas contatos com aquela jurisdição serão exibidos. O mesmo vale para o cadastro do contato. Será possível cadastrar apenas contatos na jurisdição selecionada e com seus respectivos documentos:

Caso seja criado via API, deve ser feito um POST para a primitiva platform/sign/actions/newEnvelope com o parâmetro competence de acordo com o país da Multijurisdição selecionado.

3.2 Criar e Enviar Envelope Diretamente para Assinatura

Permite criar e enviar o envelope para assinatura em uma única chamada, sem a etapa intermediária de rascunho.

Ao definir o parâmetro draft como false, o envelope é criado e enviado imediatamente para assinatura. Não é necessário informar o campo id. Basta enviar draft: false para que envelope seja criado e enviado diretamente. Os signatários são notificados conforme os canais de comunicação configurados, e o processo de assinatura é iniciado automaticamente.

• URL (acesso)
• Exemplo
• Observações

URL

POST /rest/platform/sign/actions/newEnvelope

Accept: application/json;seniorx.version=2

Exemplo:

{

					"configuration": {

					"name": "Termo de Aceite - Projeto Alpha",

					"daysToExpire": 15,

					"askGeolocation": "ASK_LOCATION",

					"recurrentNotificationIntervalDays": 3,

					"notificateAuthor": true

					},

					"signers": [

					{

					"name": "Ana Costa",

					"email": "ana.costa@parceiro.com",

					"signerType": "MANDATORY",

					"signerSubtype": "SIGN",

					"communicationChannel": {

					"email": true

					}

					}

					],

					"documentsVersions": [

					{

					"documentVersionId": "5ad8d55e-4a5c-4fb7-882e-ae500bca88df",

					"envelopePosition": 1,

					"documentVersionUrl": "https://ged.exemplo.com/documents/5ad8d55e",

					"originalFileName": "termo-aceite.pdf"

					}

					],

					"draft": false

			}

3.3 Editar Envelope - editEnvelope

Permite editar um envelope que já foi enviado para assinatura.

A edição de envelopes na versão 2 permite adicionar ou remover signatários, documentos e permissões de um envelope já enviado para assinatura. Também é possível ajustar o prazo de expiração e os conectores.

• URL (acesso)
• Parâmetros
• Exemplo
• Observações

URL

POST /rest/platform/sign/actions/editEnvelope

Accept: application/json;seniorx.version=2

Parâmetros

Exemplo:

{

					"id": "772832cf-6922-4670-8bd3-56f3f1dca92d",

					"daysToExpire": 60,

					"signersToAdd": [

					{

					"name": "Carlos Lima",

					"email": "carlos.lima@empresa.com",

					"signerType": "MANDATORY",

					"signerSubtype": "SIGN"

					}

					],

					"signersToRemove": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]

			}

3.4 Enviar Rascunho para Assinatura - newEnvelope

Quando um envelope é criado como rascunho ( draft: true), é necessário enviá-lo explicitamente para assinatura.

Para enviar um rascunho, basta chamar novamente o newEnvelope (versão 2) informando o id do envelope existente e definindo draft: false. Isso finaliza o rascunho e inicia o processo de assinatura.

• URL (acesso)
• Exemplo
• Observações

URL

POST /rest/platform/sign/actions/newEnvelope

Accept: application/json;seniorx.version=2

Exemplo:

{

					"id": "772832cf-6922-4670-8bd3-56f3f1dca92d",

					"configuration": {

					"name": "Contrato de Prestação de Serviços"

					},

					"signers": [

					{

					"name": "Maria Silva",

					"email": "maria.silva@empresa.com",

					"signerType": "MANDATORY",

					"signerSubtype": "SIGN"

					}

					],

					"draft": false

			}

3.5 Upload de Documentos via GED

Os documentos devem estar previamente armazenados no GED antes de serem incluídos em um envelope.

O fluxo para vincular documentos do GED ao envelope envolve:

1. Fazer upload do documento no GED, obtendo o documentId.
2. Recuperar a versão do documento (documentVersionId) a partir do documentId.
3. Incluir o documentVersionId no campo documentsVersions da requisição de criação do envelope.

• Estrutura do Objeto documentVersion
• Como obter o parâmetro documentVersionUrl
• Observações

Estrutura do objeto documentVersion

Como obter o parâmetro documentVersionUrl

O Parâmetro documentVersionUrl pode ser obtido através das primitivas requestDocumentVersionDownload e requestDocumentVersionDownload

requestDocumentVersionDownload:

• GET → /ecm_ged/queries/requestDocumentVersionDownload

Os parâmetros são documentVersionUrl e preview (por padrão é true) e o retorno é o campo downloadUrl que corresponde ao parâmetro documentVersionUrl:

requestDocumentDownload:

• GET → /ecm_ged/queries/requestDocumentDownload

Os parâmetros são documentId e preview (por padrão é true) e o retorno é o campo downloadUrl que corresponde ao parâmetro downloadVersionUrl:

3.6 Associação de Contatos aos Signatários

Permite vincular contatos previamente cadastrados na Agenda de Contatos do SIGN como signatários do envelope.

Ao criar um envelope, é possível informar o contactUserId de um contato cadastrado na Agenda de Contatos. Isso preenche automaticamente os dados do signatário (nome, e-mail, telefone, documento) com base no cadastro existente, evitando retrabalho e garantindo consistência de dados.

• Pré-requisitos
• Exemplo
• Documentos Utilizados ao Assinar um Envelope
• Observações

Pré-requisitos

Feature toggle:

• flow/contact/new_contact_service — habilita o novo serviço de contatos.

Exemplo:

{

					"signers": [

					{

					"contactUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",

					"signerType": "MANDATORY",

					"signerSubtype": "SIGN",

					"orderSign": 1

					}

					]

			}

Documentos Utilizados ao Assinar um Envelope:

Ao criar um contato seja na hora da criação do envelope ou anteriormente, é possível adicionar diversos documentos, mas apenas o primeiro da lista será o principal e utilizado na assinatura e para editar o próprio contato:

Os documentos adicionados podem ser arrastados, e o que está em primeiro ao salvar o contato, é o documento principal utilizado em todo o processo de assinatura e liberação da edição do contato.

Caso seja criado via API, deve realizar um POST para a primitiva flow/contact/actions/newContactUser com os parâmetros:

O documento com o campo active = true, é o documento principal. Só pode haver um documento com active = true por contato.

4. Comparativo: Gestão Antiga vs. Nova Gestão

5. FAQ

Qual a diferença entre as versões do newEnvelope?

A versão 2 (acessada via header Accept: application/json;seniorx.version=2) consolida criação e envio em um único endpoint com o parâmetro draft, permite envio direto sem rascunho, e oferece suporte a campos adicionais como notificationTemplateId e envelopeBatchId. A versão 1 foi deprecada em 12/09/2025.

Posso criar um envelope sem documentos?

Sim, o campo documentsVersions é opcional na criação do envelope. Documentos podem ser adicionados posteriormente via edição do rascunho.

Como envio um rascunho para assinatura?

Chame novamente o newEnvelope (versão 2) informando o id do rascunho existente e definindo draft: false. Para criar e enviar diretamente sem rascunho, basta informar draft: false sem necessidade de id.

Posso editar um envelope já enviado para assinatura?

Sim, utilize o endpoint editEnvelope (versão 2, com header Accept: application/json;seniorx.version=2). É possível adicionar ou remover signatários, documentos e permissões, e alterar o prazo de expiração. Signatários que já assinaram não podem ser removidos.

O que acontece ao informar contactUserId junto com dados manuais do signatário?

Os dados do contato cadastrado sobrescrevem todos os campos do signatário (nome, e-mail, CPF, documento, telefone, data de nascimento e login). Valores manuais informados nesses campos serão ignorados.

O que acontece se eu não informar o campo draft?

O valor padrão é true, ou seja, o envelope será criado como rascunho.

É possível enviar notificações por WhatsApp ou SMS?

Sim, configure os canais desejados no objeto communicationChannel de cada signatário (whatsapp: true, sms: true). Os canais devem estar habilitados no tenant.

6. Referência Técnica - Enumerações

• Tipos de Signatário (signerType)
• Subtipos de Signatário (signerSubtype)
• Geolocalização (askGeolocation)
• Jurisdição (envelopeCompetence)
• Certificado Digital (digitalCertificateOption)
• Status do Envelope (envelopeStatus)

Tipos de Signatário (signerType)

Subtipos de Signatário (signerSubtype)

Geolocalização (askGeolocation)

Jurisdição (envelopeCompetence)

Certificado Digital (digitalCertificateOption)

Status do Envelope (envelopeStatus)

7. Páginas Relacionadas

• Criar, Editar e Enviar um Envelope para Assinatura
• Agenda de Contatos
• Caixa de Entrada
• Como enviar um ou mais arquivos para assinatura eletrônica