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
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
sortOrder
Type
integer
Description
Orden del rol dentro del documento. Default 0.
Name
kind
Type
string
Description
Tipo de rol. Valores admitidos: "signer", "witness", "notary", "carbon_copy", "approver", "in_person_signer". Default "signer" — el firmante asignado llena las variables del rol.
No existe un kind "sender": las variables que llena el dueño de forma fija antes de enviar (sender-fixed) se modelan con roleId=null en la variable, no con un rol aparte.

documentId y signerUserId existen en el modelo de base de datos pero no forman parte del contrato de respuesta de la API v2. La representación del rol en las respuestas (CompoundRoleSummary, dentro de compound.roles) solo incluye los campos listados arriba.

THE DOCUMENT ROLE OBJECT

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Arrendador",
  "contactEmail": "arrendador@empresa.com",
  "contactPhone": null,
  "sortOrder": 0,
  "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 }}`	`name: "Sender"` (el prefijo se titula como cualquier otro rol)
`{{ nombre }}` (sin prefijo)	No crea rol — queda sin asignar

El prefijo sender__ no recibe un trato especial en la auto-creación de roles al crear el documento: el inferidor (_infer_role) titula cualquier prefijo, así que sender__fecha produce un rol llamado "Sender". El reconocimiento de sender__ como "sender-fixed" solo ocurre como sugerencia en el endpoint de detección de variables (POST /v2/documents/{id}/detect-variables), que clasifica pero no persiste nada. Para fijar realmente una variable a nivel sender, define la variable con roleId=null y un value.

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 por el dueño en la pantalla de configuración.

PATCH /v2/documents/{id}/signers/{sig_id} con roleName no reclama estos orphans por nombre. El handler busca un rol existente únicamente por el firmante:

Por signer_user_id — enlace canónico, funciona para email y WhatsApp.
Fallback por contact_email — para roles creados antes de que se propagara signer_user_id.

Como un orphan auto-creado desde el template tiene ambos campos en null, ninguna de las dos búsquedas lo encuentra. En ese caso el endpoint crea un rol nuevo ligado al firmante (con su signer_user_id, contact_email y contact_phone), en lugar de reescribir el orphan. El roleName solo se usa como nombre del rol — nunca como criterio de búsqueda.

Rol existente del firmante → se renombra (mismo id)

// El firmante ya tiene un rol ligado por signer_user_id/contact_email:
// PATCH con roleName solo actualiza el nombre, manteniendo el mismo id.
{
  "id": "dr-uuid-responsable",
  "name": "Responsable",
  "contactEmail": "responsable@empresa.com",
  "kind": "signer"
}

Sin rol del firmante → se crea uno nuevo

// No existe rol ligado a este firmante (incluido el caso de un orphan
// con signer_user_id=null y contact_email=null): se crea un rol nuevo.
{
  "id": "dr-uuid-nuevo",
  "name": "Responsable",
  "contactEmail": "responsable@empresa.com",
  "kind": "signer"
}

Para asignar un firmante al orphan auto-creado desde el template, usa la pantalla de configuración del documento (no el PATCH de firmantes). Si un rol ya está ligado al firmante, el PATCH solo lo renombra conservando su id y las variables vinculadas 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 (matchea por signer_user_id/contact_email, o crea un rol nuevo). Retorna { success, roleId, roleName, roleContactEmail }