> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar envelope rascunho

> Cria um novo envelope em rascunho com as configurações gerais (título, vencimento, lembretes).

Inicia a criação de um envelope em etapas. Esta chamada cria o envelope no estado "Enviar arquivos", armazenando apenas as configurações gerais. Ninguém é notificado ainda — o signatário é convidado apenas quando você chama [`POST .../send`](/plataforma/assinatura-digital/api/post-envelope-send) no fim do fluxo.

Use esta abordagem quando quiser um assistente passo a passo na interface (upload, depois signatários, depois revisão). Para criar um envelope completo em uma única chamada, use [`POST /signer/v1/envelopes`](/plataforma/assinatura-digital/api/post-envelope) em vez deste.

**Autenticação**: `x-api-key` no header. A solicitação também aceita `Authorization: Bearer` com headers de projeto/organização (`x-project-id`, `x-organization-id`).

## Parâmetros

<ParamField body="title" type="string" required>
  Título do envelope, ex.: `"Contrato de Serviços 2025"`. Máximo 255 caracteres.
</ParamField>

<ParamField body="dueDate" type="string" required>
  Data limite de assinatura (ISO 8601), ex.: `"2025-12-31T23:59:59Z"`. Deve ser no futuro.
</ParamField>

<ParamField body="reminderEveryHours" type="integer" optional>
  Frequência de lembretes ao signatário (em horas). Mínimo 1, máximo 720 (30 dias). Padrão: 24.
</ParamField>

<ParamField body="signingMode" type="enum" optional>
  Modo de assinatura: `sequential` (fila, um após o outro) ou `parallel` (todos ao mesmo tempo). Padrão: `parallel`.
</ParamField>

## Respostas

<ResponseField name="envelopeUuid" type="string">
  UUID do envelope rascunho recém-criado. Use-o em chamadas subsequentes.
</ResponseField>

<ResponseField name="title" type="string">
  Título do envelope.
</ResponseField>

<ResponseField name="stateId" type="integer">
  ID numérico do estado (1 = "Enviar arquivos"). Útil para interfaces que precisam comparar sem strings com acentuação.
</ResponseField>

<ResponseField name="state" type="string">
  Nome do estado (legível).
</ResponseField>

<ResponseField name="dueDate" type="string">
  Data limite.
</ResponseField>

<ResponseField name="reminderEveryHours" type="integer">
  Frequência de lembretes.
</ResponseField>

<ResponseField name="signingMode" type="string">
  Modo de assinatura escolhido.
</ResponseField>

<ResponseField name="createdAt" type="string">
  Timestamp de criação (ISO 8601).
</ResponseField>

## Erros

Veja [Autenticação e erros](/plataforma/assinatura-digital/api/erros-e-autenticacao).

* **400**: Título vazio, vencimento no passado/inválido, ou frequência de lembretes inválida.
* **401**: API key ou Bearer token inválido.

<ResponseExample>
  ```json theme={"theme":"catppuccin-latte"}
  HTTP/1.1 201 Created
  Content-Type: application/json

  {
    "envelopeUuid": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Contrato de Serviços 2025",
    "stateId": 1,
    "state": "Enviar arquivos",
    "dueDate": "2025-12-31T23:59:59Z",
    "reminderEveryHours": 24,
    "signingMode": "parallel",
    "createdAt": "2025-07-27T10:30:00Z"
  }
  ```

  ```json theme={"theme":"catppuccin-latte"}
  HTTP/1.1 400 Bad Request
  Content-Type: application/json

  {
    "statusCode": 400,
    "message": "Due date must be in the future"
  }
  ```
</ResponseExample>

## Exemplo

```bash theme={"theme":"catppuccin-latte"}
curl -X POST "https://api.valid.com/signer/v1/envelopes/drafts" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contrato de Serviços 2025",
    "dueDate": "2025-12-31T23:59:59Z",
    "reminderEveryHours": 24,
    "signingMode": "parallel"
  }'
```

## Fluxo do assistente

Após criar o rascunho, você está no passo 1 ("Enviar arquivos"):

1. **Passo 1 (Enviar arquivos)**: use [`POST .../:uuid/documents`](/plataforma/assinatura-digital/api/post-envelope-document) para anexar um ou mais PDFs. Depois chame [`POST .../:uuid/advance`](/plataforma/assinatura-digital/api/post-envelope-advance).
2. **Passo 2 (Inserir signatários)**: use [`PUT .../:uuid/signers`](/plataforma/assinatura-digital/api/put-envelope-signers) para definir a lista de signatários. Depois chame `advance` de novo.
3. **Passo 3 (Conferência)**: mostre um resumo ao operador. Depois chame [`POST .../:uuid/send`](/plataforma/assinatura-digital/api/post-envelope-send) para enviar aos signatários.

## Importante

* **Nenhum arquivo ou signatário ainda**: o envelope nasce vazio. Adicione ambos nos passos seguintes.
* **Sem notificações**: nem o operador nem os signatários recebem e-mail até o `send`.
* **Edição até o envio**: você pode revisar e voltar usando [`PATCH .../:uuid/settings`](/plataforma/assinatura-digital/api/patch-envelope-settings) ou [`POST .../:uuid/back`](/plataforma/assinatura-digital/api/post-envelope-back).

## Próximas etapas

1. Anexe documentos: [`POST .../:uuid/documents`](/plataforma/assinatura-digital/api/post-envelope-document)
2. Defina signatários: [`PUT .../:uuid/signers`](/plataforma/assinatura-digital/api/put-envelope-signers)
3. Avance no fluxo: [`POST .../:uuid/advance`](/plataforma/assinatura-digital/api/post-envelope-advance)
4. Finalize enviando: [`POST .../:uuid/send`](/plataforma/assinatura-digital/api/post-envelope-send)

## Relacionado

* [`POST /signer/v1/envelopes`](/plataforma/assinatura-digital/api/post-envelope) — criar envelope completo em uma chamada (atalho, sem wizard)
* [`PATCH .../:uuid/settings`](/plataforma/assinatura-digital/api/patch-envelope-settings) — revisar configurações
* [`POST .../:uuid/documents`](/plataforma/assinatura-digital/api/post-envelope-document) — anexar arquivos
* [`PUT .../:uuid/signers`](/plataforma/assinatura-digital/api/put-envelope-signers) — adicionar signatários


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.