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

deadline

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`.
`signingOrder`	number	❌	Ordem de assinatura (usado se o fluxo for sequencial).

👀 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

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#

👀 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#