DocumentRole

Un DocumentRole representa un rol nombrado dentro de un documento — por ejemplo "Arrendador", "Proveedor" o "Responsable". Los roles conectan las variables del template con los firmantes que deben llenarlas.

Attributes

Name
id
Type
string (uuid)
Description
Identificador único del rol. Permanece igual aunque el rol cambie de nombre o se reclame.
Name
documentId
Type
string (uuid)
Description
ID del documento al que pertenece este rol.
Name
name
Type
string
Description
Nombre del rol (ej. "Arrendador", "Proveedor"). Máximo 255 caracteres. No es case-sensitive para búsquedas internas.
Name
contactEmail
Type
string | null
Description
Email del firmante asignado a este rol. null cuando el rol aún no tiene firmante (orphan).
Name
contactPhone
Type
string | null
Description
Teléfono del firmante en formato E.164 (para firmantes solo WhatsApp). null si no aplica.
Name
signerUserId
Type
string (uuid) | null
Description
Enlace canónico al usuario AllSign asignado. Permite localizar el rol sin depender del email — clave para firmantes WhatsApp-only.
Name
kind
Type
string
Description
"signer" — el firmante asignado llena las variables del rol. "sender" — el dueño del documento las llena de forma fija antes de enviar.

THE DOCUMENT ROLE OBJECT

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "documentId": "doc-uuid",
  "name": "Arrendador",
  "contactEmail": "arrendador@empresa.com",
  "contactPhone": null,
  "signerUserId": "user-uuid",
  "kind": "signer"
}

Auto-creation from templates

Cuando creas un documento desde un template DOCX con variables que siguen la convención role__field, AllSign auto-crea un DocumentRole por cada prefijo único que detecta.

Variable en el DOCX	Rol auto-creado
`{{ arrendador__nombre }}`	`name: "Arrendador"`
`{{ proveedor__rfc }}`	`name: "Proveedor"`
`{{ sender__fecha }}`	No crea rol — se marca como sender-fixed
`{{ nombre }}` (sin prefijo)	No crea rol — queda sin asignar

Los roles auto-creados nacen como orphan (contactEmail=null, signerUserId=null) hasta que el dueño asigna un firmante en la pantalla de configuración.

Orphan roles

Un orphan role es un DocumentRole con contactEmail=null y signerUserId=null. Se crea automáticamente desde el template y espera ser reclamado.

Cuando asignas un firmante a un rol (vía PATCH /v2/documents/{id}/signers/{sig_id} con roleName), el endpoint reclama el orphan en vez de crear un rol duplicado: actualiza contactEmail y signerUserId manteniendo el mismo id.

Orphan role (antes de asignar firmante)

{
  "id": "dr-uuid-responsable",
  "name": "Responsable",
  "contactEmail": null,
  "signerUserId": null,
  "kind": "signer"
}

Claimed role (después de asignar firmante via PATCH)

{
  "id": "dr-uuid-responsable",
  "name": "Responsable",
  "contactEmail": "responsable@empresa.com",
  "signerUserId": "user-uuid",
  "kind": "signer"
}

El id del rol no cambia al reclamarlo. Las variables ya vinculadas al rol conservan su roleId correcto y no requieren reasignación.

POST /v2/documents — Crea documento; participants[].roleName pre-asigna roles
POST /v2/documents/{id}/add-signer — Agrega firmante con roleName para auto-asignar variables coincidentes
PATCH /v2/documents/{id}/signers/{sig_id} — Asigna o cambia el rol de un firmante; reclama orphans automáticamente y retorna autoAssignedVariables