Plantillas

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) — 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

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.

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:

{
  "envelopeId": "envelope_plantilla_123",
  "recipients": [{ "id": 1, "email": "[email protected]", "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:

{
  "envelopeId": "envelope_plantilla_123",
  "recipients": [{ "id": 1, "email": "[email protected]" }],
  "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 — listar plantillas filtrando por type=TEMPLATE
• Campos — tipos de campo y sus opciones
• Guía de Integración — flujo general de creación y firma