Sobres y destinatarios

Un sobre es un contrato en camino a ser firmado: una versión de plantilla generada con sus variables, los destinatarios que actúan sobre ella y la evidencia de todo lo que sucede. Cree uno con POST /v1/envelopes.

Creación de un sobre

Campo	Tipo	Notas
`template`	`tpl_…`	Obligatorio
`version`	número o `"latest"`	`latest` de forma predeterminada; se resuelve y se fija al crear el sobre. Debe estar publicada
`variables`	objeto	Se valida con el JSON Schema de la versión
`recipients`	array	Uno por rol (`role`, `name`, `email`; opcionalmente `externalUserId`, `verification`, `fields` para prellenar por ID de campo y `order` para cambiar el orden de firma)
`subject`, `message`	string	Se usan en los correos de firma y se muestran en la página de firma
`delivery`	`email` · `embedded` · `none`	`email` de forma predeterminada
`expiresAt`	RFC 3339	Debe ser una fecha futura; el sobre vence en ese momento y los enlaces de firma y de observador dejan de funcionar
`cc`	array	Destinatarios CC adicionales (`name`, `email`) además de los roles CC de la plantilla; hasta 50
`viewers`	array	Personas que siguen el sobre sin firmar (`name`, `email`, opcionalmente `notifyOnSignature`); cantidad por sobre limitada según el plan
`viewerDocumentAccess`	boolean	Permite que los observadores abran el documento en su página de estado. `false` de forma predeterminada (solo el estado); plan Team o superior
`reminders`	objeto	`{ "enabled": false }` desactiva los recordatorios; `{ "enabled": true, "intervalHours": 24 }` cambia el intervalo (de 1 a 720)
`externalId`	string	Su propio ID, de hasta 200 caracteres
`dedupeOn`	`"external_id"`	Devuelve el sobre existente con este `externalId` en lugar de crear otro
`metadata`	objeto de strings	Hasta 500 caracteres por valor; se devuelve en el sobre y en los webhooks

Cada destinatario necesita un rol de la versión; cada rol que no sea CC necesita exactamente un destinatario. Los errores se informan todos juntos, con punteros como /recipients/1/role o /recipients/0/fields/start_date.

Respuestas: 201 con el sobre y un encabezado Location; 200 con el sobre existente y x-deduplicated: true cuando dedupeOn encontró una coincidencia; 200 con un resumen de la simulación para ?dry_run=true; 402 cuando un espacio de trabajo Free usó sus sobres incluidos; 403 plan-upgrade-required cuando los observadores superan lo que permite el plan o viewerDocumentAccess no está incluido en el plan (Planes y límites). Las simulaciones también comprueban los límites del plan.

Todos los campos agregados después de la primera versión son opcionales: una solicitud sin ellos se comporta exactamente igual que antes.

Opciones de envío

La plantilla define quién firma y en qué orden. Para un sobre concreto, puede cambiarlo sin modificar la plantilla:

{
  "template": "tpl_9fK2mQ7xLp",
  "variables": { "client": { "name": "Jane Doe" } },
  "recipients": [
    { "role": "client", "name": "Jane Doe", "email": "jane@acme.dev", "order": 2 },
    { "role": "company", "name": "Sam Lee", "email": "sam@bonafide.dev", "order": 1 },
    { "role": "witness", "name": "Kim Park", "email": "kim@acme.dev", "order": 1 }
  ],
  "cc": [{ "name": "Legal", "email": "legal@acme.dev" }],
  "viewers": [{ "name": "Alex Chen", "email": "alex@acme.dev", "notifyOnSignature": true }],
  "reminders": { "enabled": true, "intervalHours": 48 },
  "expiresAt": "2026-11-30T23:59:59Z"
}

Orden: recipients[].order es el paso en el que firma el destinatario; los destinatarios con el mismo número firman al mismo tiempo. Si no se indica, se aplica el order del rol definido en la plantilla. Los órdenes son enteros positivos; los roles CC no se pueden ordenar; cada rol sigue necesitando su destinatario (para que los campos de la plantilla conserven su firmante); al menos un destinatario debe firmar. El evento envelope.created registra routingOverridden: true.
CC: los destinatarios CC adicionales reciben el correo del documento completado y nunca firman. Aparecen en recipients con kind: "cc" y el rol _cc.
Recordatorios: a quien le toca firmar se le envía un recordatorio cada intervalHours (de forma predeterminada, el REMINDER_INTERVAL_HOURS de la implementación, 72), como máximo tres veces; enabled: false no envía ninguno. Los recordatorios se aplican a la entrega por email.
La autenticación del firmante es por destinatario: verification reemplaza el método del rol. Hoy están disponibles none (solo el enlace de firma único, el valor predeterminado para los roles que no definen uno) y email_otp (el enlace más un código enviado por correo); passkey y id_check se rechazan porque todavía no están disponibles. Consulte verificación del firmante.
Idioma: locale en un destinatario, CC u observador (o en el sobre, para todos los que no tengan uno propio) define el idioma de su página de firma y de sus correos, uno de los 50 idiomas de firma. Si no se indica, la página de firma sigue el idioma del navegador y los correos se envían en inglés.

La pantalla de envío del panel ofrece las mismas opciones: adelantar o atrasar pasos, marcar Firmar al mismo tiempo, agregar CC y observadores, elegir la autenticación (Solo enlace por correo o Enlace por correo + código) y el idioma de cada firmante, y definir una fecha de vencimiento y un calendario de recordatorios.

Entrega

email: cada destinatario recibe por correo un enlace a la página de firma alojada cuando es su turno. Los destinatarios que no firmaron reciben un recordatorio cada pocos días (hasta tres), y todos reciben un correo cuando el sobre se completa.
embedded: no se envían correos a los firmantes. Genere una sesión de firma cuando el firmante esté en su producto. Los observadores siguen recibiendo por correo su enlace de estado.
none: no se envía ningún correo (tampoco a los observadores); úselo cuando usted mismo entrega los enlaces (sesiones alojadas).

POST /v1/envelopes/{id}/recipients/{recipient}/resend envía por correo un enlace nuevo a un destinatario al que le toca firmar (como máximo una vez por minuto).

Ciclo de vida

          ┌──────────── declined (a signer declined)
          │
sent ─────┼──────────── voided   (POST /v1/envelopes/{id}/void)
          │
          ├──────────── expired  (expiresAt passed)
          │
          └──────────── completed ──► seal: pending ──► sealed

`status`	Significado
`rendering`	En preparación
`sent`	En curso: los destinatarios firman en el orden de enrutamiento
`completed`	Todos los destinatarios terminaron. Comienza el sellado
`declined`	Un destinatario rechazó la firma; el sobre finaliza
`voided`	Usted lo anuló (`{ "reason": "…" }`); las sesiones de firma abiertas dejan de funcionar
`expired`	`expiresAt` pasó antes de completarse

seal indica el estado del PDF sellado: not_started, pending (completado, en proceso de sellado), sealed o failed. El sellado nunca bloquea la finalización: primero se completa el sobre y justo después se sella.

Destinatarios y enrutamiento

{
  "id": "rcp_5Jw0pLs9Xe",
  "role": "client",
  "name": "Jane Doe",
  "email": "jane@acme.dev",
  "order": 1,
  "status": "viewed",
  "verification": "email_otp",
  "completedAt": null
}

El status del destinatario es pending (todavía no es su turno), sent, viewed, completed o declined, y kind es el tipo del rol: signer, approver, form_filler o cc. El enrutamiento sigue el order (el del rol, o el que se define al enviar): todos los destinatarios del orden más bajo sin terminar actúan en paralelo, y el grupo siguiente comienza cuando ellos terminan. Los destinatarios CC nunca bloquean el enrutamiento.

Observadores

Un observador sigue un sobre sin firmarlo: un gerente, un asistente legal, el responsable de la cuenta del lado del cliente. Los observadores no son destinatarios. No tienen rol ni turno, nunca bloquean ni completan nada y nunca aparecen en la lista de firmantes del certificado.

Cuando se envía el sobre (o cuando los agrega más tarde con POST /v1/envelopes/{id}/viewers), cada observador recibe un correo con su marca con un enlace a una página de estado de solo lectura: el título del sobre, el remitente y cada paso con los nombres, roles, estados y marcas de tiempo de sus destinatarios, actualizados en vivo a medida que las personas firman. No se muestran las direcciones de correo de los destinatarios.
Los observadores vuelven a recibir un correo cuando el sobre se completa, se rechaza o se anula, y después de cada firma si notifyOnSignature es true (desactivado de forma predeterminada).
El documento solo aparece en la página cuando usted define viewerDocumentAccess: true (plan Team o superior): el original mientras está en curso y el PDF sellado una vez sellado. De lo contrario, los observadores solo ven el estado.
DELETE /v1/envelopes/{id}/viewers/{viewer} revoca a un observador: todos los enlaces que se le enviaron dejan de funcionar de inmediato.
Los enlaces son URL de capacidad personales. Solo se almacena un SHA-256 del token de cada enlace. Un enlace funciona hasta que vence el sobre (como máximo 90 días), durante 30 días después de que el sobre finalizó, y nunca una vez que se revoca al observador.
La incorporación, la apertura (primera vista de la página y del documento) y la revocación se registran en el registro de auditoría como viewer.added, viewer.viewed, viewer.document_viewed y viewer.revoked, y por lo tanto en el certificado.

Las respuestas de un solo sobre (crear, obtener, anular) los enumeran:

{
  "viewers": [
    {
      "id": "vwr_2Hc8sQ1nVt",
      "name": "Alex Chen",
      "email": "alex@acme.dev",
      "notifyOnSignature": true,
      "status": "active",
      "invitedAt": "2026-10-13T13:58:04.512Z",
      "firstViewedAt": "2026-10-13T14:05:41.090Z",
      "lastViewedAt": "2026-10-13T15:12:09.337Z",
      "revokedAt": null,
      "createdAt": "2026-10-13T13:58:04.512Z"
    }
  ],
  "viewerDocumentAccess": false
}

La cantidad de observadores por sobre depende del plan (Free 1, Pay-as-you-go 2, Team 5, Business 20, Platform ilimitados); los destinatarios CC no cuentan. Los observadores revocados liberan su lugar.

Documentos

GET /v1/envelopes/{id}/document?version=… descarga un PDF, con su SHA-256 en x-document-sha256:

`version`	Archivo
`original` (predeterminado)	El documento generado tal como se envió para firmar
`sealed`	El PDF final: valores aplanados, certificado de finalización anexado y sello de tiempo del documento. Después de `envelope.sealed`
`certificate`	Solo el certificado de finalización

El documentHash del sobre es el SHA-256 del original y sealedDocumentHash, el del archivo sellado; esos son los valores que busca la verificación.

Registro de auditoría

Cada acción es un evento en una cadena de hashes por sobre: hash = SHA-256(prevHash ‖ canonical JSON of the event), donde el primer prevHash son 64 ceros. GET /v1/envelopes/{id}/events devuelve los eventos y comprueba la cadena:

{
  "data": [
    {
      "id": "evt_…",
      "envelope": "env_8Gm2kQ4rT1",
      "seq": 1,
      "type": "envelope.created",
      "createdAt": "2026-10-13T13:58:04.512Z",
      "recipient": null,
      "actor": { "kind": "api_key", "id": "…", "name": null, "email": null },
      "ip": "203.0.113.7",
      "userAgent": null,
      "data": { "template": "tpl_…", "templateVersion": 3, "documentHash": "9f2c…" },
      "hash": "4b1d…",
      "prevHash": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "chain": { "valid": true, "brokenAt": null }
}

Además de los tipos de eventos de webhook, el registro tiene entradas exclusivas de auditoría, como session.created, recipient.verified, recipient.reminded y los eventos de observadores (tipo de actor viewer cuando un observador abre su página).

Para mostrar el estado en vivo en una interfaz, GET /v1/envelopes/{id}/events/stream es un flujo de eventos enviados por el servidor (SSE): el nombre del evento de cada trama es el type del evento y su ID, el seq; vuelva a conectarse con Last-Event-ID para reanudar.

Enumeración

GET /v1/envelopes filtra por status, seal, template y q (texto libre sobre los nombres y correos de los destinatarios, el externalId y el ID del sobre). Como todas las listas, se pagina con cursor:

{ "data": [ … ], "hasMore": true, "nextCursor": "…" }

Vuelva a pasar nextCursor como cursor; limit va de 1 a 100 (20 de forma predeterminada).