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

> Cria um novo envelope com um documento e signatários.

Cria um novo envelope, abre sessões de assinatura para cada signatário e retorna as URLs/tokens para compartilhamento.

<ParamField body="title" type="string" required>
  Título do envelope (ex: `"Contrato de Serviços 2025"`).
</ParamField>

<ParamField body="signingMode" type="enum" required>
  Modo de assinatura: `sequential` (signatários assinam um de cada vez) ou `parallel` (todos podem assinar simultaneamente).
</ParamField>

<ParamField body="document" type="object" required>
  Documento a ser assinado (PDF).

  <Expandable title="Propriedades de document">
    <ParamField body="url" type="string">
      URL pública do PDF (ex: `https://exemplo.com/documento.pdf`). Não use `url` se enviar `content`.
    </ParamField>

    <ParamField body="content" type="string">
      PDF em base64. Não use `content` se enviar `url`.
    </ParamField>

    <ParamField body="filename" type="string">
      Nome do arquivo (usado nos downloads, ex: `"contrato.pdf"`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="signers" type="array" required>
  Lista de signatários.

  <Expandable title="Propriedades de signers[]">
    <ParamField body="name" type="string" required>
      Nome completo do signatário.
    </ParamField>

    <ParamField body="email" type="string" required>
      E-mail do signatário (recebe link para assinar).
    </ParamField>

    <ParamField body="cpf" type="string" required>
      CPF do signatário (11 dígitos, sem formatação).
    </ParamField>

    <ParamField body="phoneCountryCode" type="string">
      Código de país do telefone (ex: `"55"` para Brasil).
    </ParamField>

    <ParamField body="phoneNumber" type="string">
      Número de telefone (ex: `"11987654321"`).
    </ParamField>

    <ParamField body="queueOrder" type="integer">
      Ordem na fila (apenas para `signingMode: sequential`). Signatários com ordem menor assinam primeiro.
    </ParamField>

    <ParamField body="livenessSessionId" type="string">
      ID de uma sessão de liveness já realizada (para PAdES avançado). Opcional.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="externalCode" type="string">
  Código único externo do seu sistema (ex: `"FAT-2025-001"`). Deve ser único por projeto. Opcional.
</ParamField>

<ParamField body="templateId" type="string">
  UUID de um template para usar como base. Se enviado, o documento do template é ignorado; use o documento enviado aqui ou deixe vazio para usar o do template.
</ParamField>

<ParamField body="dueDate" type="string">
  Data/hora limite para assinatura (ISO 8601, ex: `"2025-12-31T23:59:59Z"`). Signatários que não acessarem até essa data verão `410 Gone`.
</ParamField>

<ParamField body="urlOrigin" type="string">
  URL origem do seu app (ex: `"https://app.seu-dominio.com"`). Usado para construir links no e-mail de convite.
</ParamField>

<ParamField body="urlNotification" type="string">
  URL webhook para notificação de mudanças de estado (ex: `"https://seu-backend.com/webhooks/status"`). Opcional. Veja [Notificações via webhook](/plataforma/assinatura-digital/api/notificacoes-webhook).
</ParamField>

<ParamField body="auth" type="object">
  Dados de autenticação/verificação (usado para escolher estratégia de assinatura).

  <Expandable title="Propriedades de auth">
    <ParamField body="mfaTransactionId" type="string">
      ID de uma transação MFA já aprovada (para assinatura eletrônica simples, não PAdES).
    </ParamField>
  </Expandable>
</ParamField>

## Respostas

<ResponseField name="envelopeUuid" type="string">
  UUID único do envelope criado.
</ResponseField>

<ResponseField name="fileUuid" type="string">
  UUID do arquivo (PDF) do envelope.
</ResponseField>

<ResponseField name="signers" type="array">
  Lista de signatários com sessões abertas.

  <Expandable title="Propriedades de signers[]">
    <ResponseField name="signerUuid" type="string">
      UUID do signatário.
    </ResponseField>

    <ResponseField name="sessionToken" type="string">
      Token de sessão único para este signatário. **Use este token para construir o link de assinatura.**
    </ResponseField>

    <ResponseField name="signUrl" type="string">
      URL sugerida para assinatura (ex: `https://seu-app.com/sign?token={sessionToken}`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="state" type="string">
  Estado inicial do envelope: `CREATED`.
</ResponseField>

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

## Erros comuns

Veja [Autenticação e erros](/plataforma/assinatura-digital/api/erros-e-autenticacao) para detalhes sobre `401`, `400`, `409`, etc.

* **400**: CPF inválido, email malformado, documento não encontrado (URL inválida).
* **401**: API key inválida ou expirada.
* **409**: `externalCode` duplicado no projeto.

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

  {
    "envelopeUuid": "550e8400-e29b-41d4-a716-446655440000",
    "fileUuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "signers": [
      {
        "signerUuid": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
        "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "signUrl": "https://seu-app.com/sign?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
      },
      {
        "signerUuid": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
        "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "signUrl": "https://seu-app.com/sign?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
      }
    ],
    "state": "CREATED",
    "createdAt": "2025-07-27T10:30:00.000Z"
  }
  ```

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

  {
    "statusCode": 400,
    "message": "Unique constraint violation on field(s): externalCode"
  }
  ```

  ```json theme={"theme":"catppuccin-latte"}
  HTTP/1.1 401 Unauthorized
  Content-Type: application/json

  {
    "statusCode": 401,
    "message": "Invalid or expired API key"
  }
  ```
</ResponseExample>

## Exemplo completo

```bash theme={"theme":"catppuccin-latte"}
curl -X POST "https://signer.vcc-service.com/v1/envelopes" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contrato de Serviços",
    "signingMode": "sequential",
    "externalCode": "CONT-2025-001",
    "document": {
      "url": "https://exemplo.com/contrato.pdf",
      "filename": "contrato.pdf"
    },
    "signers": [
      {
        "name": "João Silva",
        "email": "joao@empresa.com",
        "cpf": "12345678901",
        "phoneCountryCode": "55",
        "phoneNumber": "11987654321"
      },
      {
        "name": "Maria Santos",
        "email": "maria@empresa.com",
        "cpf": "98765432100",
        "phoneCountryCode": "55",
        "phoneNumber": "11912345678"
      }
    ],
    "dueDate": "2025-12-31T23:59:59Z",
    "urlOrigin": "https://seu-app.com",
    "urlNotification": "https://seu-backend.com/webhooks/envelope-status"
  }'
```

## Próximas etapas

1. **Compartilhe os links**: Envie cada `signUrl` para o signatário correspondente (ou extraia o `sessionToken` e construa seu próprio link).
2. **Signatário assina**: Veja [`GET /v1/sign/:sessionToken`](/plataforma/assinatura-digital/api/get-sign-session) para entender o fluxo do signatário.
3. **Acompanhe o status**: Use [`GET /v1/envelopes/:uuid`](/plataforma/assinatura-digital/api/get-envelope-by-id) para verificar mudanças de estado.