Plantillas

Lista tus plantillas de firma electrónica y consulta los roles de una plantilla concreta: el punto de partida para enviar un sobre desde la API.

Las plantillas son los documentos reutilizables que tu equipo ya ha configurado en la app, con sus campos y roles de firmante definidos. Para enviar un sobre por la API parte de una de ellas, así que los dos endpoints de lectura de aquí suelen ser las primeras llamadas tras la autenticación.

Ambos requieren el scope templates:read, y una clave solo ve las plantillas que su propietario puede ver en la app.

Listar plantillas

Endpoint

GET https://api2.bunnydoc.com/v1/templates

Parámetros de consulta

Parámetro	Tipo	Descripción
`page`	integer	Número de página, desde `1`. Por defecto `1`.
`per_page`	integer	Resultados por página, `1`–`100`. Por defecto `25`.
`search`	string	Opcional. Filtra por nombre de plantilla, hasta 200 caracteres.

Ejemplo de petición

Listar plantillas

curl "https://api2.bunnydoc.com/v1/templates?per_page=25&search=nda" \
  -H "Authorization: Bearer <access_token>"

Listar plantillas

GET /v1/templates?per_page=25&search=nda HTTP/1.1
Host: api2.bunnydoc.com
Authorization: Bearer <access_token>

Respuesta

200 OK

{
  "data": [
    {
      "id": "018f2c3d-4e5f-7a8b-9c0d-1e2f3a4b5c6d",
      "name": "Mutual NDA",
      "description": "Standard two-way non-disclosure agreement",
      "file_count": 1,
      "role_count": 2,
      "created_at": "2026-06-01T09:30:00.000Z",
      "updated_at": "2026-07-10T14:12:00.000Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

Campo	Tipo	Descripción
`id`	string	El id de la plantilla: pásalo a `POST /v1/envelopes/from-template`.
`name`	string	Nombre de la plantilla.
`description`	string \| null	Descripción opcional.
`file_count`	integer	Número de documentos de la plantilla.
`role_count`	integer	Número de roles de firmante.
`created_at` / `updated_at`	string	Marcas de tiempo ISO 8601.

Obtener una plantilla

Devuelve una plantilla incluidos sus roles. Llama a este endpoint antes de enviar: el array roles te indica exactamente qué nombres de rol debes proporcionar y cuáles están bloqueados.

Endpoint

GET https://api2.bunnydoc.com/v1/templates/{id}

Ejemplo de petición

Obtener una plantilla

curl https://api2.bunnydoc.com/v1/templates/018f2c3d-4e5f-7a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer <access_token>"

Obtener una plantilla

GET /v1/templates/018f2c3d-4e5f-7a8b-9c0d-1e2f3a4b5c6d HTTP/1.1
Host: api2.bunnydoc.com
Authorization: Bearer <access_token>

Respuesta

200 OK

{
  "id": "018f2c3d-4e5f-7a8b-9c0d-1e2f3a4b5c6d",
  "name": "Mutual NDA",
  "description": "Standard two-way non-disclosure agreement",
  "file_count": 1,
  "role_count": 2,
  "created_at": "2026-06-01T09:30:00.000Z",
  "updated_at": "2026-07-10T14:12:00.000Z",
  "roles": [
    {
      "role": "Client",
      "recipient_type": "need-to-sign",
      "signing_order": 1,
      "locked": false
    },
    {
      "role": "Account manager",
      "recipient_type": "need-to-sign",
      "signing_order": 2,
      "locked": true,
      "name": "Dana Lee",
      "email": "dana@yourco.com"
    }
  ],
  "fields": [
    {
      "id": "018f2c3d-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
      "role": "Client",
      "file_id": "018f2c3d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "page_number": 1,
      "type": "signature",
      "label": "Client signature",
      "required": true,
      "locked": false,
      "position": { "x": 72, "y": 540, "width": 180, "height": 48 }
    }
  ],
  "files": [
    { "file_id": "018f2c3d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "order": 1, "excluded_pages": [] }
  ],
  "settings": {
    "signing_order": true,
    "email_subject": "Please sign: Mutual NDA",
    "email_message": "<p>Please review and sign the enclosed NDA.</p>",
    "expiry_date": "2026-12-31T23:59:59.000Z",
    "timezone": "Australia/Sydney",
    "signed_date_format": "DD/MM/YYYY",
    "envelope_date_time_format": "DD/MM/YYYY HH:mm",
    "brand_id": "018f2c3d-9c0d-7e1f-8a2b-3c4d5e6f7a8b"
  }
}

`roles`

Campo de rol	Tipo	Descripción
`role`	string	El nombre del rol. Proporciónalo en `recipients[].role` al enviar.
`recipient_type`	string	Cómo participa el destinatario, p. ej. `need-to-sign`, `receives-a-copy`.
`signing_order`	integer	El orden en que firma este rol.
`locked`	boolean	Si es `true`, el nombre y el correo están fijados en la plantilla: omite este rol en tu petición de envío.
`name` / `email`	string \| null	Presentes solo en roles bloqueados: el destinatario fijo.

Los roles bloqueados no se pueden reasignar

Un rol bloqueado ya tiene una persona asignada (o es el propio remitente de la plantilla). Enviar un destinatario para un rol bloqueado se rechaza con unknown_signer_role. Proporciona destinatarios solo para los roles con locked en false.

`fields`

Todos los campos colocados en la plantilla, para que puedas mostrar a tus usuarios qué pedirá el documento antes de enviarlo.

Campo	Tipo	Descripción
`id`	string \| null	El id del campo.
`role`	string	El rol de firmante al que pertenece el campo: únelo con `roles[].role`.
`file_id`	string	Sobre cuál de los `files` de la plantilla se sitúa el campo.
`page_number`	integer	Página (desde 1) dentro de ese archivo.
`type`	string	Tipo de campo: `signature`, `initials`, `text`, `date`, `date_signed`, `checkbox`, `radio`, `dropdown`, `multi_select`, `email`, `phone`, `number`, `amount`, `address`, `company`, `job_title`, `title`, `full_name`, `first_name`, `last_name`, `masked_text`, `image` o `file_attachment`.
`label`	string \| null	La etiqueta del campo.
`required`	boolean	Si un firmante debe completarlo.
`locked`	boolean	Si el valor está fijado en la plantilla.
`position`	object	`x`, `y`, `width`, `height` en la página.

Los valores preparados no se exponen

La geometría de los campos es legible; los valores preparados por el remitente no. Un valor del lado del remitente puede ser una referencia de firma o texto sensible precargado, así que nunca sale de la app por esta API.

`files`

Solo metadatos, en orden de documento.

Campo	Tipo	Descripción
`file_id`	string	El id del archivo. Úsalo para unirlo con `fields[].file_id`.
`order`	integer	Posición en el conjunto de documentos.
`excluded_pages`	integer[]	Páginas excluidas de la plantilla, si hay alguna.

Los archivos de plantilla no se pueden descargar

Aquí no hay URL de descarga ni ruta de almacenamiento, y no existe ningún endpoint para obtener el documento de una plantilla. Esto te dice qué archivos están adjuntos y en qué orden, nada más. El PDF final firmado se entrega mediante el webhook envelope.document_ready.

`settings`

Lo que heredará el sobre cuando envíes desde esta plantilla. Leerlo es la forma fiable de saber qué no necesitas pasar.

Campo	Tipo	Descripción
`signing_order`	boolean	Si los destinatarios firman de forma secuencial.
`email_subject`	string \| null	Asunto por defecto. Sobrescríbelo por envío con `email_subject`.
`email_message`	string \| null	Mensaje por defecto, como HTML seguro. Sobrescríbelo por envío con `email_message`.
`expiry_date`	string \| null	ISO 8601. Lo hereda el sobre; no se puede fijar desde la API.
`timezone`	string	Zona IANA usada para las fechas del documento y los correos.
`signed_date_format`	string	Cómo se muestran las fechas de firma en el PDF.
`envelope_date_time_format`	string	Cómo se muestran las fechas y horas.
`brand_id`	string \| null	La marca aplicada a los correos y a la página de firma.

Errores

Estado	`error.code`	Cuándo ocurre
`404`	`template_not_found`	No existe ninguna plantilla con ese id en tu empresa.

Siguiente paso

Enviar desde una plantilla

Asigna destinatarios a los roles desbloqueados y envía el sobre.

Enviar desde una plantilla

En esta página