DocumentVariable

Un DocumentVariable representa un campo dinámico ({{ placeholder }}) en un template de documento. Cada placeholder del DOCX genera un DocumentVariable que registra quién lo llena y con qué valor.

Attributes

Name
name
Type
string
Description
Nombre exacto del placeholder en el template (ej. arrendador__nombre). Sirve como clave de búsqueda y no cambia una vez creado.
Name
label
Type
string
Description
Nombre legible para mostrar en la UI (ej. "Nombre del Arrendador"). Se deriva del name si no se especifica explícitamente.
Name
type
Type
string
Description
Tipo de dato del campo: "text" (default), "date", "number", "select".
Name
roleId
Type
string (uuid) | null
Description
ID del DocumentRole responsable de llenar esta variable. null cuando la variable es sender-fixed o no tiene asignación todavía.
Name
value
Type
string | null
Description
Valor ingresado por el sender cuando roleId=null y el dueño ya llenó la variable. null si el firmante aún no ha llenado o si la variable está asignada a un rol.
Name
required
Type
boolean
Description
Si true, el documento no puede completarse sin que esta variable tenga valor. Default: true.

THE DOCUMENT VARIABLE OBJECT

{
  "name": "arrendador__nombre",
  "label": "Nombre del Arrendador",
  "type": "text",
  "roleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "value": null,
  "required": true
}

Estados de asignación

Una DocumentVariable puede estar en uno de tres estados, determinados por roleId y value:

Estado	`roleId`	`value`	Quién llena
Asignada a rol	`uuid`	`null`	El firmante del rol durante su sesión de firma
Sender-fixed	`null`	`"valor"`	El dueño ya la llenó; va fija en el documento
Sin asignar	`null`	`null`	Nadie la ha reclamado — el dueño decide

Asignada a rol

{
  "name": "arrendador__nombre",
  "roleId": "dr-uuid-arrendador",
  "value": null
}

El firmante asignado al rol "Arrendador" verá este campo en su interfaz de firma.

Sender-fixed

{
  "name": "sender__fecha_inicio",
  "roleId": null,
  "value": "2026-01-01"
}

El dueño ya llenó el valor antes de enviar. Los firmantes no ven este campo — aparece directamente en el documento.

Sin asignar

{
  "name": "nombre_testigo",
  "roleId": null,
  "value": null
}

La variable existe pero nadie la reclamó. Aparece en el panel de configuración del dueño para asignación manual.

Convención de nombres

La convención role__field en el nombre del placeholder permite que AllSign auto-detecte el rol y pre-asigne la variable al crear el documento:

arrendador__nombre → auto-asignada al rol "Arrendador"
sender__fecha → auto-marcada como sender-fixed
nombre (sin prefijo) → sin asignar, el dueño decide

Consulta la guía de variables y roles para una tabla completa con ejemplos y cómo nombrar variables en Word/LibreOffice.

POST /v2/documents/{id}/add-signer — Pasar variableNames activa el auto-link al agregar firmante
PATCH /v2/documents/{id}/signers/{sig_id} — Retorna autoAssignedVariables[] con los nombres auto-asignados al rol