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
variableName
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. En las respuestas de la API v2 este campo se serializa como variableName (no name).
Name
label
Type
string
Description
Nombre legible para mostrar en la UI (ej. "Nombre del Arrendador"). Se deriva del variableName si no se especifica explícitamente.
Name
type
Type
string
Description
Tipo de dato del campo. El endpoint de creación acepta: "text" (default), "date", "currency", "number", "select", "textarea", "rfc", "curp", "email", "phone". El modelo además contempla checkbox, radio_group y attachment_request.
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.
Name
filledAt
Type
string (date-time) | null
Description
Momento en que se llenó la variable. null mientras siga vacía.
Name
documentPdfIds
Type
array
Description
IDs de los document_pdf en los que aparece esta variable (relevante para documentos compuestos de varios PDFs). Vacío si no aplica.

THE DOCUMENT VARIABLE OBJECT

{
  "variableName": "arrendador__nombre",
  "label": "Nombre del Arrendador",
  "type": "text",
  "roleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "value": null,
  "required": true,
  "filledAt": null,
  "documentPdfIds": []
}

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

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

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

Sender-fixed

{
  "variableName": "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

{
  "variableName": "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 roleName vincula al firmante con ese rol; las variables del rol se auto-asignan vía el roleName (no existe un campo variableNames)
PATCH /v2/documents/{id}/signers/{sig_id} — Asigna o cambia el rol de un firmante. Retorna { success, roleId, roleName, roleContactEmail } (no devuelve una lista autoAssignedVariables)