--- title: "Criar envelope para múltiplos signatários" method: POST path: "/v1/envelopes" tags: ["Envelopes"] --- # Criar envelope para múltiplos signatários `POST /v1/envelopes` ## Request - Base URL: `https://api.signdocs.com.br` - URL: `https://api.signdocs.com.br/v1/envelopes` - Auth: HTTP bearer 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`. ## Headers - `X-Idempotency-Key` string, uuid ## Request body - CreateEnvelopeRequest: Requisição para criar um envelope para múltiplos signatários. - `signingMode` 'PARALLEL' | 'SEQUENTIAL', required: Modo de assinatura do envelope. - `totalSigners` integer, required: Número total de signatários esperados (mínimo 2, máximo 100). Para lotes maiores, divida em vários envelopes. - `document` object, required: Documento inline (base64). Máximo 10 MB. Suporta PDF e outros formatos. - `content` string, byte, required: Conteúdo do documento em base64. - `filename` string: Nome do arquivo. - `metadata` object: 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. - `returnUrl` string, uri: URL de retorno padrão após conclusão de cada sessão. - `cancelUrl` string, uri: URL de retorno padrão em caso de cancelamento. - `expiresInMinutes` integer: Prazo de assinatura do envelope, em minutos. Mínimo 5, máximo 10080 (7 dias). Padrão 4320 (72 horas) quando omitido. - `appearance` SigningSessionAppearance: Configuração visual da página de assinatura hospedada. - `brandColor` string: Cor primária da marca (hex). - `logoUrl` string, uri: URL HTTPS do logotipo da empresa. - `companyName` string: Nome da empresa exibido na página. - `backgroundColor` string: Cor de fundo (hex). - `textColor` string: Cor do texto (hex). - `buttonTextColor` string: Cor do texto dos botões (hex). - `borderRadius` string: Raio de borda dos elementos (formato "Npx"). - `headerStyle` 'full' | 'minimal' | 'none': Estilo do cabeçalho da página. - `fontFamily` 'system-ui' | 'Inter' | 'Roboto' | 'Open Sans' | 'Lato' | 'Montserrat' | 'Source Sans Pro' | 'Nunito' | 'Poppins' | 'Raleway' | 'Ubuntu': Família tipográfica. - `owner` Owner: Identidade do solicitante da assinatura (quem cria a sessão/envelope), distinta do signatário. Quando informado, a SignDocs: 1. **Envia automaticamente um e-mail de convite** para `signer.email` no momento da criação da sessão, se `signer.email` for diferente de `owner.email` (case-insensitive). Em envelopes, cada signatário recebe seu próprio convite. 2. **Notifica o solicitante por e-mail** quando cada signatário concluir a assinatura, com o protocolo de evidência e link para o verificador. Omitir `owner` mantém o comportamento padrão: o integrador entrega a URL de assinatura por seus próprios canais e usa webhooks para acompanhar o status. - `email` string, email: E-mail do solicitante. Recebe notificações de conclusão. - `name` string: Nome do solicitante (usado na saudação dos e-mails). - `signerConfidentiality` boolean: 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`. ## Response `201` Envelope criado com sucesso. - CreateEnvelopeResponse: Resposta da criação de envelope. - `envelopeId` string, 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. - `totalSigners` integer, required: Número total de signatários esperados. - `documentHash` string, required: Hash SHA-256 do documento enviado. - `signerConfidentiality` boolean, required: Valor efetivo da confidencialidade entre signatários, já resolvido com o padrão do tenant. - `createdAt` string, date-time, required: Data/hora de criação (ISO 8601 UTC). - `expiresAt` string, date-time, required: Data/hora de expiração do envelope (ISO 8601 UTC). ## Other responses - `400`: Requisição inválida — parâmetros ausentes ou malformados. - `401`: Autenticação ausente ou inválida. - `403`: Permissões insuficientes para a operação solicitada. Inclui `purpose: "ACTION_AUTHENTICATION"` sem `featureFlags.trustSessionsEnabled`. A verificação é pelo `purpose`, não pela rota: vale em `/v1/transactions`, `/v1/signing-sessions` e `/v1/envelopes/{envelopeId}/sessions`, além de `/v1/trust-sessions`. O remédio é habilitar a flag para o tenant e provisionar a cota `monthlyTrustSessions`. - `409`: Conflito de estado — a operação não pode ser realizada no estado atual do recurso. - `422`: Entidade não processável — a requisição é sintaticamente válida mas semanticamente incorreta. Inclui o perfil de política não autorizado para o tenant. As rotas de criação (`/v1/transactions`, `/v1/signing-sessions` e `/v1/envelopes/{envelopeId}/sessions`) verificam a mesma regra, antes de cota, convite e gravação — a recusa não consome documento. As flags envolvidas são `featureFlags.customPolicyEnabled` (perfil `CUSTOM`), `serpro.enabled` (perfis SERPRO), `featureFlags.documentExtractionEnabled` (fallback por documento; `BIOMETRIC_SERPRO_AUTO_FALLBACK` exige as duas últimas) e `featureFlags.biometricRequired`. O remédio é habilitar a flag para o tenant. `signer.cpf` e `signer.birthDate`, exigidos pelos perfis SERPRO, são validados como **400** e não aqui: requisição malformada, corrigível na mesma chamada. - `429`: Limite de requisições excedido. - `500`: Erro interno do servidor. --- [API](https://skmtc.dev/signdocs/apis/signdocs-brasil-external-api.md) · [All operations](https://skmtc.dev/signdocs/apis/signdocs-brasil-external-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signdocs/apis/signdocs-brasil-external-api/revisions/2d3805aed161?raw)