> ## 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 a partir de template

> Cria um envelope baseado em um template, semeando valores de campos.

Cria um novo envelope usando um template como base. Você pode pré-preencher valores de campos, atribuir campos a signatários específicos e configurar signatários.

## Parâmetros

<ParamField path="uuid" type="string" required>
  UUID do template.
</ParamField>

<ParamField body="title" type="string" required>
  Título do envelope (ex: `"Contrato do cliente ACME"`).
</ParamField>

<ParamField body="externalCode" type="string">
  Código externo único (ex: `"CONT-2025-ACME"`). Deve ser único por projeto.
</ParamField>

<ParamField body="dueDate" type="string" required>
  Data limite para assinatura (ISO 8601).
</ParamField>

<ParamField body="urlOrigin" type="string">
  URL origem do seu app (para links em e-mails).
</ParamField>

<ParamField body="urlNotification" type="string">
  URL webhook para notificações de status.
</ParamField>

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

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

    <ParamField body="email" type="string" required>
      E-mail.
    </ParamField>

    <ParamField body="cpf" type="string" required>
      CPF (11 dígitos).
    </ParamField>

    <ParamField body="phoneCountryCode" type="string">
      Código de país do telefone.
    </ParamField>

    <ParamField body="phoneNumber" type="string">
      Número de telefone.
    </ParamField>

    <ParamField body="queueOrder" type="integer">
      Ordem na fila (se modo sequencial).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="values" type="object">
  Atalho para pré-preencher campos: `{ key: value }`. Locked (não editável por signatários).
</ParamField>

<ParamField body="fieldValues" type="array">
  Fine-grained field filling com controle de editabilidade.

  <Expandable title="Propriedades de fieldValues[]">
    <ParamField body="key" type="string">
      Identificador do campo.
    </ParamField>

    <ParamField body="value" type="string | string[] | boolean" required>
      Valor.
    </ParamField>

    <ParamField body="editable" type="boolean">
      Se signatário pode editar (padrão: `false`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="fieldAssignments" type="array">
  Atribui campos de dados a signatários.

  <Expandable title="Propriedades de fieldAssignments[]">
    <ParamField body="key" type="string">
      Identificador do campo.
    </ParamField>

    <ParamField body="signerIndex" type="integer">
      Índice do signatário na array `signers` (0-based).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="signatureAssignments" type="array">
  Atribui campos de assinatura a signatários.

  <Expandable title="Propriedades de signatureAssignments[]">
    <ParamField body="key" type="string">
      Identificador do campo de assinatura.
    </ParamField>

    <ParamField body="signerIndex" type="integer">
      Índice do signatário.
    </ParamField>
  </Expandable>
</ParamField>

## Respostas

Retorna envelope criado (mesmo shape de [`POST /v1/envelopes`](/plataforma/assinatura-digital/api/post-envelope)):

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

<ResponseField name="signers" type="array">
  Signatários com `sessionToken`.
</ResponseField>

## Erros

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

* **400**: Campo desconhecido, valor inválido, campo obrigatório sem valor.
* **401**: API key inválido.
* **404**: Template não encontrado.
* **409**: `externalCode` duplicado.

<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=..."
      }
    ],
    "state": "CREATED",
    "createdAt": "2025-07-27T10:30:00.000Z"
  }
  ```
</ResponseExample>

## Exemplo

```bash theme={"theme":"catppuccin-latte"}
curl -X POST "https://signer.vcc-service.com/v1/templates/550e8400-e29b-41d4-a716-446655440000/envelopes" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contrato ACME 2025",
    "externalCode": "CONT-ACME-001",
    "dueDate": "2025-12-31T23:59:59Z",
    "urlOrigin": "https://seu-app.com",
    "signers": [
      {
        "name": "João Cliente",
        "email": "joao@acme.com",
        "cpf": "12345678901"
      }
    ],
    "values": {
      "nome_cliente": "ACME Inc.",
      "data_criacao": "2025-07-27"
    },
    "fieldAssignments": [
      {
        "key": "data_assinatura",
        "signerIndex": 0
      }
    ]
  }'
```

## Fluxo recomendado

1. **Criar template**: [`POST /v1/templates`](/plataforma/assinatura-digital/api/post-template)
2. **Criar envelope**: `POST /v1/templates/:uuid/envelopes` (pré-preenche valores)
3. **Signatário assina**: [`POST /signature/envelope-sessions/:sessionToken/submit`](/plataforma/assinatura-digital/api/post-sign-submit)
4. **Obter assinado**: [`GET /v1/sign/:sessionToken/signed-document`](/plataforma/assinatura-digital/api/get-sign-session-signed-document)

## Relacionado

* [`POST /v1/templates/:uuid/fill`](/plataforma/assinatura-digital/api/post-template-fill) — pré-visualizar preenchido sem criar envelope
* [`POST /v1/envelopes`](/plataforma/assinatura-digital/api/post-envelope) — criar envelope avulso (sem template)