Vocabulario de Signing Flows
Primera versión, contrastada por lectura del código en a93224a. Los nombres ingleses permiten encontrar el concepto en la interfaz y la API; no sustituyen sus identificadores. Este capítulo define objetos y acciones. Para garantías, consultar los estado de referencias de la fuente única.
Documento, circuito e instancia
Documento (Document). En la conversación con el usuario, el PDF que se prepara y envía. En la integración conviene precisar si se habla del archivo, del circuito o de una instancia: sus identificadores no son intercambiables.
Archivo (File). El recurso que contiene los bytes de un PDF. Un archivo base puede intervenir en más de una instancia. No usar su identificador como identificador de circuito.
Circuito (Workflow). La organización de un envío: título, participantes, modo, configuración y estado. Se prepara como borrador y luego se despacha. En la API inglesa se encuentra bajo workflows.
Instancia (Document instance). Un ejemplar dentro de un circuito. La descarga /api/v1/documents/{id}/file usa el identificador de instancia. En modo copias hay un ejemplar por destinatario; el identificador del circuito identifica el conjunto, no una de esas copias.
Modo del circuito (Mode). Organización del trabajo:
| Concepto | API inglesa | Organización |
|---|---|---|
| Serie | sequential | Los participantes se agrupan por turnos sucesivos |
| Paralelo | parallel | Los participantes comparten turno sobre la misma instancia |
| Copias | copies | Cada destinatario trabaja sobre su propia instancia |
Paralelo describe la organización del envío. No debe usarse como resultado de una prueba de concurrencia del motor.
Turno (Order). Número que determina cuándo se notifica a una participación. El servicio elige el menor orden pendiente.
Posición (Position). Lugar estable del participante, usado para asignar campos. Dos participantes pueden compartir turno y tener posiciones diferentes. No reasignar campos por el orden alfabético de sus correos.
Fuentes: circuito.ts, Instancia en el esquema, OpenAPI.
Personas, cuentas y permisos
Identidad (Identity). Registro de una persona reconocido por el sistema. No equivale a una membresía en una empresa.
Cuenta (Account). Espacio de una persona o empresa. La cuenta elegida determina dónde trabaja el usuario.
Membresía (Membership). Relación de una identidad con una cuenta. Invitar a una persona a un circuito no equivale a incorporarla como miembro de la empresa.
Emisor (Sender). Persona que prepara y despacha el circuito desde una cuenta.
Participación (Participation). Relación de una identidad con un circuito y una instancia, con papel, turno y estado propios. Una persona puede participar en varios circuitos.
Firmante (Signer). Papel de una participación a la que se solicita la acción de firmar. El invitado normalmente llega por un enlace; no necesita ser miembro de la empresa emisora.
Veedor / copia (Reviewer / CC). Otros papeles del circuito. Son distintos del firmante; para los valores exactos de entrada consultar OpenAPI. No confundir el papel cc con el modo copies.
Carácter (Capacity). Si la persona actúa personalmente o en representación de una cuenta. Es distinto del rol de acceso a la consola.
Otorgamiento (Grant). Registro de acceso asociado a una invitación. No es una membresía. El enlace de firma se emite al despachar y debe usarse tal como fue entregado.
Rol (Role). Agrupación de capacidades de una cuenta, administrada en Roles. No es el papel de una plantilla ni el carácter de una participación.
Capacidad (Permission). Acción autorizable, como crear documentos. Sus códigos internos no son nombres recomendados para explicarle el producto a un cliente.
Operador (Operator). Usuario del plano de administración del servicio, con entrada /operador. No es un sinónimo de administrador de una empresa en /app.
Fuentes: circuito.ts, esquema, autorización, enlaces.
Preparación y reutilización
Campo (Field). Dato ubicado en una página: tiene código, etiqueta, tipo, posición, tamaño, obligatoriedad y, cuando corresponde, una posición de firmante asignada.
Código / etiqueta. El código identifica el campo; la etiqueta es el texto que se presenta. No cambiar códigos para traducir una etiqueta.
Firma visual (My signature). Nombre de la pantalla donde el usuario prepara su representación gráfica. Las propiedades de una firma sobre un PDF deben consultarse en la fuente de garantías y su alcance documentado; este término sólo identifica la función de interfaz.
Plantilla (Template). Preparación reutilizable con archivo base, papeles y campos. Al guardar un circuito como plantilla se nombran los papeles; algunas posiciones pueden conservar un destinatario fijo si se elige esa opción.
Papel de plantilla. Lugar nombrado, como «Solicitante» o «Representante de la empresa», que se asigna a una persona al usar la plantilla. No es un rol de permisos.
Carpeta (Folder). Organización de documentos y ámbito de permisos en la consola. Los nombres elegidos por una empresa son contenido del cliente, no claves traducibles del sistema.
Fuentes: campos.ts, plantillas.ts, consola.
Estados y seguimiento
Cada estado pertenece a un objeto. No comparar directamente el estado de una participación con el de todo el circuito.
| Objeto | Valores de la API inglesa |
|---|---|
| Circuito | draft, sent, completed, cancelled, expired |
| Instancia | pending, in_progress, signed, declined, cancelled, expired |
| Participación | pending, notified, opened, signed, declined, delegated, not_required, expired, cancelled |
Estos son nombres de estado del flujo, no dictámenes de validez del PDF. Consultar la traducción del contrato para su correspondencia con el dominio interno.
Despachar (Dispatch). Acción de enviar un circuito preparado e iniciar sus notificaciones. Es distinta de subir el archivo.
Aviso enviado / apertura. Datos de seguimiento separados. Un participante pendiente puede estar esperando turno o tener un problema de notificación; no deducir entrega ni apertura sólo de ese estado.
Evidencia, expediente, sello, certificado de finalización y paquete de entrega. Términos reservados a la fuente única y su revisión. Esta versión no les atribuye propiedades por analogía con otros productos.
Un ejemplo completo
Una empresa ficticia, Empresa Ejemplo, prepara un contrato para Ana y Beto. El envío es un circuito. Si ambos participan sobre el mismo ejemplar, comparten una instancia. Ana ocupa la posición 1 y Beto la 2; en paralelo ambos pueden tener turno 1. El campo «Nombre del solicitante» se asigna por posición, no por turno. Si la empresa reutiliza la preparación, crea una plantilla con papeles nombrados. Si elige copias, cada destinatario recibe una instancia propia del circuito.