Envelopes

Criar envelope para múltiplos signatários

Cria um envelope que agrupa sessões de assinatura sobre o mesmo documento. Suporta modo PARALLEL (todos assinam simultaneamente) ou SEQUENTIAL (em ordem).

Com signerConfidentiality, nenhum signatário vê os dados dos demais (requer habilitação do tenant; ver o campo).

Requer scope transactions:write.

post/v1/envelopes

Request

  • Base URL: https://api.signdocs.com.br
  • URL: https://api.signdocs.com.br/v1/envelopes
  • Auth: HTTP bearer

Headers

X-Idempotency-Keystring uuid

Chave de idempotência para evitar criação duplicada. Reenviar a mesma chave com o mesmo corpo dentro de 24h devolve a resposta original, sem consumir cota nem repetir efeitos (e-mails, webhooks). A mesma chave com um corpo diferente responde 409.

A resposta repetida é a original byte a byte, incluindo os cabeçalhos RateLimit-* — eles refletem a cota no momento da chamada original, já que a repetição não consumiu nada.

Request body

signingMode'PARALLEL' | 'SEQUENTIAL' required

Modo de assinatura do envelope.

totalSignersinteger required

Número total de signatários esperados (mínimo 2, máximo 100). Para lotes maiores, divida em vários envelopes.

metadataobject

Metadados livres (chave-valor). Chaves até 256 chars, valores até 1024 chars.

locale'pt-BR' | 'en' | 'es'

Idioma padrão das sessões do envelope.

returnUrlstring uri

URL de retorno padrão após conclusão de cada sessão.

cancelUrlstring uri

URL de retorno padrão em caso de cancelamento.

expiresInMinutesinteger

Prazo de assinatura do envelope, em minutos. Mínimo 5, máximo 10080 (7 dias). Padrão 4320 (72 horas) quando omitido.

signerConfidentialityboolean

Confidencialidade entre signatários. Quando true, nenhum signatário vê identidade, e-mail, CPF/CNPJ, quantidade ou posição dos demais — nem durante o fluxo, nem depois de concluído:

  • GET /v1/verify/{evidenceId} não devolve envelopeId;
  • GET /v1/verify/envelope/{envelopeId} não devolve signatários, contagens nem downloads;
  • GET /v1/verify/{evidenceId}/downloads não devolve o PDF assinado (no certificado digital o PDF de cada signatário carrega as assinaturas dos anteriores);
  • o aviso de "ainda não é a sua vez" não informa posição nem total;
  • o pacote de evidências não grava documentGroup.totalSigners.

O criador do envelope continua vendo tudo pelos endpoints autenticados (GET /v1/envelopes/{envelopeId}, downloads e carimbo combinado). Os metadata da sessão são exibidos ao signatário — não coloque neles dados de outros signatários.

Exige habilitação do tenant pela SignDocs (featureFlags.signerConfidentialityDefault); sem ela, true retorna 403 com code: SIGNER_CONFIDENTIALITY_NOT_ENABLED. Em tenant habilitado, omitir o campo vale true; envie false para desligar neste envelope. Independe de signingMode.

Example request

{
  "signingMode": "PARALLEL",
  "totalSigners": 3,
  "document": {
    "filename": "contrato-multilateral.pdf"
  },
  "returnUrl": "https://app.example.com/done",
  "cancelUrl": "https://app.example.com/cancelled",
  "appearance": {
    "brandColor": "#1a5276",
    "logoUrl": "https://cdn.example.com/logo.png",
    "companyName": "Empresa Exemplo Ltda",
    "backgroundColor": "#ffffff",
    "textColor": "#333333",
    "buttonTextColor": "#ffffff",
    "borderRadius": "12px"
  },
  "owner": {
    "email": "solicitante@empresa.com.br",
    "name": "Maria Souza"
  },
  "signerConfidentiality": true
}

Response

Envelope criado com sucesso.

envelopeIdstring required

Identificador único do envelope.

status'CREATED' | 'ACTIVE' | 'COMPLETED' | 'CANCELLED' | 'EXPIRED' required

Status possíveis de um envelope.

signingMode'PARALLEL' | 'SEQUENTIAL' required

Modo de assinatura configurado.

totalSignersinteger required

Número total de signatários esperados.

documentHashstring required

Hash SHA-256 do documento enviado.

signerConfidentialityboolean required

Valor efetivo da confidencialidade entre signatários, já resolvido com o padrão do tenant.

createdAtstring date-time required

Data/hora de criação (ISO 8601 UTC).

expiresAtstring date-time required

Data/hora de expiração do envelope (ISO 8601 UTC).

Example response

{
  "envelopeId": "env_01JXYZ...",
  "signingMode": "PARALLEL",
  "totalSigners": 3,
  "documentHash": "sha256:a1b2c3d4e5f6..."
}

Changes

No recorded changes to this operation across all 1 revision of this API.