Criar Envelope

URL: /v2/envelopes/
Método: POST
Autenticação: Bearer JWT (bearerAuth)

Descrição

Este endpoint permite criar um envelope de assinatura, que representa um conjunto de documentos e signatários dentro de um fluxo de assinatura eletrônica.

O envelope é a estrutura principal para gerenciar o processo de assinatura, incluindo:

Documentos que serão assinados;

Signatários e métodos de autenticação (e-mail, SMS ou WhatsApp);

Ordem de assinatura, se necessária;

Observadores, que acompanham o andamento do processo;

Campos de assinatura, rubrica e texto mapeados nos documentos.

Fluxo de utilização

Envie uma requisição POST /v2/envelopes/ com os metadados dos documentos, signatários e campos de assinatura.

Receba como resposta o envelopeId e os uploadUrls para envio dos arquivos binários.

Faça o upload dos arquivos de documento usando os uploadUrls retornados.

Após o upload, o envelope estará pronto para o fluxo de assinatura.

Cabeçalhos

Nome	Tipo	Obrigatório	Descrição
`x-account-id`	string	✅	ID da conta que está criando o envelope.
`Authorization`	string	✅	Token Bearer JWT. Exemplo: `Bearer <token>`.

Corpo da Requisição (`application/json`)

{
  "title": "string",  
  "folderId": "string",
  "deadline": "2025-12-31T23:59:59Z",
  "message": "string (máx. 500 caracteres)",
  "documents": [
    {
      "id": "string",
      "fileName": "string",
      "contentType": "application/pdf"
    }
  ],
  "signatories": [
    {
      "id": "string",
      "name": "string",
      "email": "user@example.com",
      "qualification": "string",
      "authMethod": "EMAIL|SMS|WHATSAPP",
      "phoneNumber": "string (opcional)",
      "signingOrder": 1
    }
  ],
  "observers": [
    {
      "email": "observer@example.com",
      "notifyOnSent": false,
      "notifyOnCompletion": true
    }
  ],
  "fields": [
    {
      "type": "SIGNATURE|INITIALS|TEXT",
      "documentId": "string",
      "signatoryId": "string",
      "pageNumber": 1,
      "position": {
        "x": 100,
        "y": 200,
        "width": 150,
        "height": 50
      },
      "properties": {
        "label": "Texto opcional (para campos TEXT)"
      }
    }
  ]
}

Campos obrigatórios

documents (mínimo 1)

signatories (mínimo 1)

Estrutura dos campos

🗂️ documents

Campo	Tipo	Obrigatório	Descrição
`id`	string	✅	Identificador único temporário do documento utilizado para identificar o documento quando houver `fields`.
`fileName`	string	✅	Nome do arquivo (ex: `contrato.pdf`).
`contentType`	string	✅	Tipo MIME do documento (`application/pdf`).

✍️ signatories

Campo	Tipo	Obrigatório	Descrição
`id`	string	✅	Identificador único temporário do signatário utilizado para identificar o signatário quando houver `fields`.
`name`	string	✅	Nome completo do signatário.
`email`	string	✅	Endereço de e-mail válido.
`qualification`	string	✅	Qualificação (ex: “Representante Legal”).
`authMethod`	string	✅	Método de autenticação (`EMAIL`, `SMS` ou `WHATSAPP`).
`phoneNumber`	string	❌	Necessário se o método for `SMS` ou `WHATSAPP` no formato E.164 (+55119XXXXYYYY).
`signingOrder`	number	❌	Ordem de assinatura (usado se o fluxo for sequencial).

📅 deadline (opcional)

Campo	Tipo	Obrigatório	Descrição
`deadline`	string (datetime)	❌	Data limite para assinaturas.

👀 observers (opcional)

Campo	Tipo	Obrigatório	Descrição
`email`	string	✅	Endereço de e-mail do observador.
`notifyOnSent`	boolean	❌	Notifica quando o envelope é enviado (padrão: `false`).
`notifyOnCompletion`	boolean	❌	Notifica quando o envelope é concluído (padrão: `true`).

🧾 fields (opcional)

Define os campos que serão renderizados nos documentos (assinatura, rubrica ou texto).

Campo	Tipo	Obrigatório	Descrição
`type`	string	✅	Tipo de campo (`SIGNATURE`, `INITIALS` ou `TEXT`).
`documentId`	string	✅	ID do documento onde o campo será inserido.
`signatoryId`	string	✅	ID do signatário vinculado ao campo.
`pageNumber`	integer	✅	Número da página (≥ 1).
`position`	object	✅	Define as coordenadas e dimensões do campo no documento.
`properties`	object	❌	Campos adicionais, como `label` (usado apenas em campos `TEXT`).

Exemplo de campo de assinatura:

{
  "type": "SIGNATURE",
  "documentId": "doc-123",
  "signatoryId": "sig-456",
  "pageNumber": 1,
  "position": { "x": 100, "y": 600, "width": 180, "height": 50 }
}

Exemplo de campo de texto:

{
  "type": "TEXT",
  "documentId": "doc-123",
  "signatoryId": "sig-456",
  "pageNumber": 1,
  "position": { "x": 200, "y": 400, "width": 300, "height": 30 },
  "properties": { "label": "CPF do signatário" }
}

Respostas

✅ 201 Created

Envelope criado com sucesso.
Retorna o ID do envelope e as URLs para upload dos documentos.

{
  "envelopeId": "env_12345",
  "uploadDetails": [
    {
      "documentId": "doc_abc",
      "fileName": "contrato.pdf",
      "uploadUrl": "https://storage-provider/upload/doc_abc"
    }
  ]
}

⚠️ 400 Bad Request

Erros de validação ou inconsistência nos dados enviados.

Exemplos:

{
  "error": {
    "code": "INVALID_FIELD_LINKING",
    "message": "Invalid field linking"
  }
}

{
  "error": {
    "code": "INVALID_FIELD_TYPE",
    "message": "Invalid field type"
  }
}

🚫 403 Forbidden

A conta não possui permissão ou atingiu o limite de envelopes.

Exemplo:

{
  "error": {
    "code": "ENVELOPES_QUOTA_EXCEEDED",
    "message": "Envelopes limit reached for this account"
  }
}

❌ 404 Not Found

Recursos relacionados não foram encontrados (ex: conta, assinatura ou pasta inexistente).

Exemplo:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Subscription not found"
  }
}

Segurança

Este endpoint requer autenticação com token JWT:

Authorization: Bearer <seu_token_jwt>

Observações Importantes

Se deadline não for definido, por padrão a data limite para assinaturas será de 7 dias a partir da data de criação do envelope.

Os uploadUrls retornados devem ser usados para enviar os arquivos binários correspondentes aos documentos informados.

Cada documento listado na requisição deve ter um campo correspondente no array uploadDetails.

É necessário enviar o header x-goog-meta-documentid com o ID do documento correspondente no array uploadDetails ao enviar o arquivo binário com a url assinada.

Se o método de autenticação for SMS ou WHATSAPP, o campo phoneNumber do signatário torna-se obrigatório.

Campos do tipo TEXT permitem adicionar rótulos (label) para exibição no documento.

É possível incluir múltiplos observadores para monitorar o andamento do envelope.

Exemplo Completo de Requisição

{
  "title": "Contrato X",
  "folderId": "fld_123",
  "deadline": "2025-12-31T23:59:59Z",
  "message": "Por favor, revise e assine o contrato.",
  "documents": [
    {
      "id": "doc_001",
      "fileName": "contrato.pdf",
      "contentType": "application/pdf"
    }
  ],
  "signatories": [
    {
      "id": "sig_001",
      "name": "Maria Oliveira",
      "email": "maria@exemplo.com",
      "qualification": "Representante Legal",
      "authMethod": "EMAIL",
      "signingOrder": 1
    }
  ],
  "observers": [
    {
      "email": "juridico@empresa.com",
      "notifyOnSent": true,
      "notifyOnCompletion": true
    }
  ],
  "fields": [
    {
      "type": "SIGNATURE",
      "documentId": "doc_001",
      "signatoryId": "sig_001",
      "pageNumber": 1,
      "position": {
        "x": 100,
        "y": 600,
        "width": 150,
        "height": 50
      }
    }
  ]
}

Descrição#

Fluxo de utilização#

Cabeçalhos#

Corpo da Requisição (application/json)#

Campos obrigatórios#

Estrutura dos campos#

🗂️ documents#

✍️ signatories#

📅 deadline (opcional)#

👀 observers (opcional)#

🧾 fields (opcional)#

Respostas#

✅ 201 Created#

⚠️ 400 Bad Request#

🚫 403 Forbidden#

❌ 404 Not Found#

Segurança#

Observações Importantes#

Exemplo Completo de Requisição#