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

> Cria um template de PDF com campos dinâmicos posicionados.

Cria um novo template de PDF com campos dinâmicos (texto, assinatura, checkbox, radio, date, select) em posições específicas. Templates são reutilizáveis — crie um template uma vez e gere múltiplos envelopes a partir dele.

## Parâmetros

<ParamField body="title" type="string" required>
  Nome do template (ex: `"Contrato de Serviços Padrão"`).
</ParamField>

<ParamField body="file" type="object" required>
  Arquivo PDF.

  <Expandable title="Propriedades de file">
    <ParamField body="url" type="string">
      URL pública do PDF. Não use se enviar `content`.
    </ParamField>

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

    <ParamField body="filename" type="string" required>
      Nome do arquivo (ex: `"contrato.pdf"`).
    </ParamField>

    <ParamField body="mime" type="string">
      MIME type (ex: `"application/pdf"`). Opcional, padrão: `application/pdf`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="pages" type="array" required>
  Metadados das páginas do PDF (dimensões do documento original).

  <Expandable title="Propriedades de pages[]">
    <ParamField body="index" type="integer" required>
      Índice da página (0-based).
    </ParamField>

    <ParamField body="nativeW" type="number" required>
      Largura nativa da página em pixels ou pontos.
    </ParamField>

    <ParamField body="nativeH" type="number" required>
      Altura nativa da página.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="fields" type="array" required>
  Lista de campos dinâmicos.

  <Expandable title="Propriedades de fields[]">
    <ParamField body="key" type="string" required>
      Identificador único do campo (ex: `"nome_cliente"`). Padrão: `^[a-z][a-z0-9_]*$`, máx 64 chars. **Imutável após criação.**
    </ParamField>

    <ParamField body="type" type="enum" required>
      Tipo: `text`, `signature`, `checkbox`, `radio`, `date`, `select`.
    </ParamField>

    <ParamField body="label" type="string" required>
      Rótulo do campo (visível ao signatário, ex: `"Nome Completo"`).
    </ParamField>

    <ParamField body="required" type="boolean">
      Se é obrigatório. Padrão: `false`.
    </ParamField>

    <ParamField body="pageIndex" type="integer" required>
      Índice da página onde o campo aparece (0-based).
    </ParamField>

    <ParamField body="x" type="number" required>
      Coordenada X normalizada (0 a 1, origem no topo-esquerdo).
    </ParamField>

    <ParamField body="y" type="number" required>
      Coordenada Y normalizada (0 a 1).
    </ParamField>

    <ParamField body="width" type="number" required>
      Largura normalizada (0 a 1).
    </ParamField>

    <ParamField body="height" type="number" required>
      Altura normalizada (0 a 1).
    </ParamField>

    <ParamField body="options" type="array">
      Para `radio`/`select`, lista de opções (`{ label, value }`).
    </ParamField>

    <ParamField body="defaultValue" type="string | string[] | boolean">
      Valor padrão do campo.
    </ParamField>
  </Expandable>
</ParamField>

## Respostas

<ResponseField name="uuid" type="string">
  UUID do template criado.
</ResponseField>

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

<ResponseField name="filename" type="string">
  Nome do arquivo.
</ResponseField>

<ResponseField name="pageCount" type="integer">
  Número de páginas.
</ResponseField>

<ResponseField name="pages" type="array">
  Metadados das páginas.
</ResponseField>

<ResponseField name="fields" type="array">
  Campos (mesmo shape da requisição).
</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**: Arquivo inválido, PDF não legível, campo com `key` duplicado ou inválido.
* **401**: API key/Bearer token inválido.
* **422**: Payload inválido (campos obrigatórios faltando).

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

  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Contrato de Serviços Padrão",
    "filename": "contrato-servicos.pdf",
    "pageCount": 2,
    "pages": [
      { "index": 0, "nativeW": 595, "nativeH": 842 },
      { "index": 1, "nativeW": 595, "nativeH": 842 }
    ],
    "fields": [
      {
        "key": "nome_cliente",
        "type": "text",
        "label": "Nome Completo",
        "required": true,
        "pageIndex": 0,
        "x": 0.1,
        "y": 0.2,
        "width": 0.8,
        "height": 0.05
      },
      {
        "key": "data_assinatura",
        "type": "date",
        "label": "Data de Assinatura",
        "required": true,
        "pageIndex": 0,
        "x": 0.1,
        "y": 0.3,
        "width": 0.4,
        "height": 0.05
      }
    ],
    "createdAt": "2025-07-27T10:30:00.000Z"
  }
  ```
</ResponseExample>

## Exemplo

```bash theme={"theme":"catppuccin-latte"}
curl -X POST "https://signer.vcc-service.com/v1/templates" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contrato de Serviços",
    "file": {
      "url": "https://seu-servidor.com/templates/contrato-base.pdf",
      "filename": "contrato-servicos.pdf"
    },
    "pages": [
      { "index": 0, "nativeW": 595, "nativeH": 842 },
      { "index": 1, "nativeW": 595, "nativeH": 842 }
    ],
    "fields": [
      {
        "key": "nome_cliente",
        "type": "text",
        "label": "Nome Completo",
        "required": true,
        "pageIndex": 0,
        "x": 0.1,
        "y": 0.2,
        "width": 0.8,
        "height": 0.05
      },
      {
        "key": "assinatura",
        "type": "signature",
        "label": "Sua Assinatura",
        "required": true,
        "pageIndex": 1,
        "x": 0.1,
        "y": 0.85,
        "width": 0.8,
        "height": 0.1
      }
    ]
  }'
```

## Próximas etapas

1. **Listar templates**: [`GET /v1/templates`](/plataforma/assinatura-digital/api/get-templates)
2. **Criar envelope a partir do template**: [`POST /v1/templates/:uuid/envelopes`](/plataforma/assinatura-digital/api/post-template-envelope)
3. **Pré-visualizar preenchido**: [`POST /v1/templates/:uuid/fill`](/plataforma/assinatura-digital/api/post-template-fill)