Enviar desde una plantilla

Crea un sobre a partir de una de tus plantillas y envíalo en una sola llamada; después obtén los enlaces de firma.

Este es el endpoint en torno al que se construyen la mayoría de las integraciones: toma una de tus plantillas, asigna personas reales a sus roles y envíala para firmar, todo en una sola llamada. En la API no hay paso de borrador.

Crear un sobre a partir de una plantilla y enviarlo

Requiere el scope envelopes:send. La creación y el envío ocurren juntos: si el envío falla por cualquier motivo, el sobre se elimina y se devuelve un error, de modo que nunca queda un borrador a medio crear. Cada envío correcto consume una de las solicitudes de firma por API de tu plan.

Endpoint

POST https://api2.bunnydoc.com/v1/envelopes/from-template

Cuerpo

Campo	Tipo	Obligatorio	Notas
`template_id`	string (uuid)	Sí	La plantilla a enviar. Obtenla de `GET /v1/templates`.
`recipients`	array	Sí	De 1 a 50 destinatarios, uno por cada rol desbloqueado de la plantilla.
`sender_email`	string	No	Enviar como este usuario. Debe ser un usuario activo de tu empresa con un asiento de firma electrónica. Por defecto, el propietario de la clave de API.
`title`	string	No	Título del sobre, hasta 250 caracteres. Por defecto, el nombre de la plantilla.
`email_subject`	string	No	Sustituye el asunto del correo de firma. Hasta 300 caracteres. Por defecto, el asunto de la plantilla.
`email_message`	string	No	Sustituye el mensaje que ven los destinatarios en el correo de firma. Hasta 5000 caracteres. Por defecto, el mensaje de la plantilla (o el predeterminado de tu marca activa).

Cada destinatario asigna una persona real a un rol de la plantilla:

Campo del destinatario	Tipo	Obligatorio	Notas
`role`	string	Sí	Debe coincidir con un rol desbloqueado de `GET /v1/templates/{id}`. Hasta 25 caracteres.
`name`	string	Sí	Nombre completo del destinatario, hasta 120 caracteres.
`email`	string	Sí	Correo del destinatario, hasta 150 caracteres.
`contact_number`	string	No	Hasta 20 caracteres.

Haz coincidir los roles con exactitud y omite los bloqueados

Cada role debe ser el nombre de un rol desbloqueado de la plantilla, y cada rol puede aparecer una vez. Un rol que no existe, o un rol bloqueado, se rechaza con unknown_signer_role. Llama siempre antes a GET /v1/templates/{id} para leer los roles válidos.

Ejemplo de petición

Enviar desde una plantilla

curl -X POST https://api2.bunnydoc.com/v1/envelopes/from-template \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "018f2c3d-4e5f-7a8b-9c0d-1e2f3a4b5c6d",
    "title": "Mutual NDA — Acme Corp",
    "sender_email": "sales@yourco.com",
    "email_subject": "Please sign: Mutual NDA",
    "email_message": "Hi Jane — please review and sign our mutual NDA. Thanks!",
    "recipients": [
      { "role": "Client", "name": "Jane Doe", "email": "jane@acme.com" }
    ]
  }'

Enviar desde una plantilla

POST /v1/envelopes/from-template HTTP/1.1
Host: api2.bunnydoc.com
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "template_id": "018f2c3d-4e5f-7a8b-9c0d-1e2f3a4b5c6d",
  "title": "Mutual NDA — Acme Corp",
  "sender_email": "sales@yourco.com",
  "email_subject": "Please sign: Mutual NDA",
  "email_message": "Hi Jane — please review and sign our mutual NDA. Thanks!",
  "recipients": [
    { "role": "Client", "name": "Jane Doe", "email": "jane@acme.com" }
  ]
}

Respuesta

201 Created

{
  "envelope_id": "018f9a0b-1c2d-7e3f-8a4b-5c6d7e8f9a0b",
  "status": "sent",
  "title": "Mutual NDA — Acme Corp",
  "sender": { "email": "sales@yourco.com" },
  "recipients": [
    { "role": "Client", "name": "Jane Doe", "email": "jane@acme.com" }
  ],
  "signing_urls": [
    {
      "recipient_id": "018f9a0b-2c3d-7e4f-8a5b-6c7d8e9f0a1b",
      "name": "Jane Doe",
      "email": "jane@acme.com",
      "recipient_type": "need-to-sign",
      "signing_url": "https://sign.bunnydoc.com/s/eyJhbGciOi…"
    }
  ],
  "created_at": "2026-07-28T10:20:00.000Z"
}

Campo	Tipo	Descripción
`envelope_id`	string	El id del nuevo sobre.
`status`	string	Siempre `sent` cuando tiene éxito.
`sender`	object	El correo del remitente resuelto.
`recipients`	array	Los destinatarios que proporcionaste.
`signing_urls`	array \| null	Presente solo si el sobre comparte enlaces de firma con el remitente; en caso contrario, `null`. Ver más abajo.
`created_at`	string	Marca de tiempo ISO 8601.

¿De dónde salen la caducidad, los recordatorios y los campos?

La caducidad, los recordatorios, el orden de firma y la disposición de los campos se heredan de la plantilla. La API establece los destinatarios, el título, el remitente y —cuando los proporcionas— el asunto y el mensaje del correo; la plantilla (y el predeterminado de tu marca activa) aportan el resto.

Errores

Estado	`error.code`	Cuándo ocurre
`402`	`quota_exceeded`	Tu empresa no tiene solicitudes de firma por API restantes en este periodo.
`404`	`template_not_found`	No existe ninguna plantilla con ese id en tu empresa.
`422`	`unknown_signer_role`	Un rol de destinatario no coincide con la plantilla, o se proporcionó un rol bloqueado.
`422`	`sender_not_found`	`sender_email` no es un usuario activo con asiento de firma electrónica en tu empresa.
`422`	`validation_failed`	El cuerpo está mal formado (falta un campo, rol duplicado, valor fuera de rango).
`429`	`rate_limited`	Más de 100 envíos en 15 minutos para esta clave.

Obtener los enlaces de firma de un sobre enviado

Los enlaces de firma permiten que el sistema del remitente entregue a cada destinatario un enlace directo en lugar de esperar al correo. Están disponibles en cualquier momento tras el envío y también los devuelve la llamada de envío anterior.

Endpoint

GET https://api2.bunnydoc.com/v1/envelopes/{id}/signing-links

Ejemplo de petición

Obtener enlaces de firma

curl https://api2.bunnydoc.com/v1/envelopes/018f9a0b-1c2d-7e3f-8a4b-5c6d7e8f9a0b/signing-links \
  -H "Authorization: Bearer <access_token>"

Obtener enlaces de firma

GET /v1/envelopes/018f9a0b-1c2d-7e3f-8a4b-5c6d7e8f9a0b/signing-links HTTP/1.1
Host: api2.bunnydoc.com
Authorization: Bearer <access_token>

Respuesta

200 OK

{
  "signing_urls": [
    {
      "recipient_id": "018f9a0b-2c3d-7e4f-8a5b-6c7d8e9f0a1b",
      "name": "Jane Doe",
      "email": "jane@acme.com",
      "recipient_type": "need-to-sign",
      "signing_url": "https://sign.bunnydoc.com/s/eyJhbGciOi…"
    }
  ]
}

signing_url es null para los destinatarios que no firman (por ejemplo, uno que "recibe una copia").

Un enlace de firma es una credencial de portador

Cualquiera que tenga un enlace de firma puede firmar como ese destinatario. Entrégalos por canales seguros y trátalos como secretos: no los registres ni los incluyas en URLs que compartas.

Errores

Estado	`error.code`	Cuándo ocurre
`403`	`signing_links_disabled`	Este sobre no tiene activada la opción de "compartir enlaces de firma con el remitente".
`404`	`envelope_not_found`	No existe ningún sobre con ese id en tu empresa.

¿Quieres actualizaciones de estado sin sondear?

La API es de solo escritura para los sobres: no hay endpoint de estado por diseño. Para saber cuándo se ve, se firma o se completa un documento, suscríbete a los webhooks.

Enviar desde una plantilla

En esta página