# Plantillas

> Crear envelopes reutilizables y generar documentos a partir de ellos.

En Legaldoc, una plantilla no es un recurso aparte: es un envelope con `type: "TEMPLATE"`. Se crea, se le agregan destinatarios y campos, y se distribuye igual que cualquier envelope (ver [Guía de Integración](/guides/integration-guide/)) — la diferencia es que un envelope tipo `TEMPLATE` no se firma directamente, sino que se usa como base para generar documentos reales.

## Crear un documento a partir de una plantilla

```http
POST /envelope/use
```

Toma el `envelopeId` de una plantilla y crea un nuevo envelope tipo `DOCUMENT` a partir de ella.

| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| `envelopeId` | string | Sí | ID de la plantilla a usar. |
| `recipients` | array | Sí | Destinatarios reales, mapeados por `id` a los destinatarios definidos en la plantilla. |
| `distributeDocument` | boolean | No | Si es `true`, distribuye el documento de inmediato tras crearlo. |
| `externalId` | string | No | Identificador propio para el documento generado. |
| `folderId` | string | No | Carpeta donde crear el documento. |
| `customDocumentData` | array | No | Reemplaza uno o más PDF de la plantilla por archivos nuevos (ver abajo). |
| `prefillFields` | array | No | Precarga valores en campos de la plantilla (ver abajo). |

Cada destinatario en `recipients` requiere `id` (el ID del destinatario en la plantilla) y `email`; `name` y `signingOrder` son opcionales y sobrescriben lo definido en la plantilla.

Ver la especificación completa en la [Referencia de la API](/api/operations/envelope-use/).

### Reemplazar el PDF de la plantilla

Si necesitas generar el PDF dinámicamente pero reutilizar los destinatarios y campos ya configurados en la plantilla, usa `customDocumentData` para mapear cada archivo de la plantilla (por su `envelopeItemId`) a un archivo nuevo:

```jsonc
{
  "envelopeId": "envelope_plantilla_123",
  "recipients": [{ "id": 1, "email": "firmante@ejemplo.cl", "name": "Nombre Real" }],
  "customDocumentData": [
    { "identifier": "envelope_item_xyz", "envelopeItemId": "envelope_item_xyz" }
  ]
}
```

El PDF de reemplazo debe mantener el mismo diseño de página que el original — los campos de la plantilla se posicionan según las coordenadas originales, y un cambio de layout los desalinea.

### Precargar valores en los campos

`prefillFields` permite completar campos de la plantilla antes de distribuir — útil cuando ya conoces el dato (por ejemplo, tomándolo de tu propio sistema) y no quieres pedírselo al firmante:

```jsonc
{
  "envelopeId": "envelope_plantilla_123",
  "recipients": [{ "id": 1, "email": "firmante@ejemplo.cl" }],
  "prefillFields": [
    { "id": 101, "type": "text", "value": "Ingeniero de Software Senior" },
    { "id": 102, "type": "number", "value": "1200000" },
    { "id": 103, "type": "checkbox", "value": ["salud", "seguro-vida"] }
  ]
}
```

El `type` de cada `prefillField` debe coincidir con el tipo real del campo en la plantilla.

---

## Ver también

- [Envelopes](/resources/envelopes/) — listar plantillas filtrando por `type=TEMPLATE`
- [Campos](/resources/fields/) — tipos de campo y sus opciones
- [Guía de Integración](/guides/integration-guide/) — flujo general de creación y firma