API de firma electrónica

Envía documentos para firmar directamente desde tus propios sistemas: intercambia una clave de API por un token, crea sobres a partir de plantillas, gestiona contactos y obtén enlaces de firma mediante una API REST sencilla.

La API de firma electrónica permite que tu aplicación haga lo mismo que tu equipo hace en la app: convertir una plantilla en una solicitud de firma, enviarla y seguirla hasta obtener un PDF firmado y con traza de auditoría, sin que nadie abra BunnyDoc.

Es una API REST pequeña y enfocada. JSON de entrada, JSON de salida, un único token de portador y exactamente los mismos permisos que tu equipo ya tiene en la app.

URL base

Todos los endpoints están bajo https://api2.bunnydoc.com/v1. Todas las rutas de estas páginas son relativas a esa base.

Cómo funciona la autenticación

El acceso es un flujo de dos pasos y es lo primero que construirás. Tu clave de API de larga duración se envía una sola vez para obtener un token de acceso de corta duración; todas las demás peticiones llevan solo el token, de modo que la clave nunca vuelve a viajar.

Crea una clave de API

En la app, abre Configuración → Claves de API (solo propietario o administrador) y crea una clave. Tiene el aspecto bd_live_… y se muestra una sola vez, al crearla: cópiala en un lugar seguro. Después no se puede recuperar, solo rotar.

Intercambia la clave por un token de acceso

Envía tu clave a POST /v1/auth/token. Recibirás un token de portador válido durante una hora.

Llama a la API con el token

Envía Authorization: Bearer <token> en todas las demás peticiones. Guarda el token en caché y reutilízalo hasta que caduque; no generes uno nuevo por cada llamada.

Mantén tu clave de API en el servidor

Una clave de API actúa en nombre de toda tu empresa. Nunca la incluyas en un navegador, una app móvil ni ningún cliente que no controles. Si una clave queda expuesta, rótala en Configuración → Claves de API: rotarla (o revocarla) invalida sus tokens vigentes de inmediato.

Empieza aquí

Obtener un token de acceso

La primera llamada de toda integración: intercambia tu clave de API por un token de portador.

Enviar desde una plantilla

Crea un sobre a partir de una de tus plantillas y envíalo en una sola llamada.

Endpoints de un vistazo

Cada petición se autoriza tanto por el scope de tu clave como por el permiso del usuario que la posee: una clave nunca puede hacer más de lo que esa persona puede hacer en la app.

Para hacer esto	Endpoint	Scope
Intercambiar una clave de API por un token	`POST /v1/auth/token`	—
Listar tus plantillas	`GET /v1/templates`	`templates:read`
Obtener una plantilla y sus roles	`GET /v1/templates/{id}`	`templates:read`
Listar contactos	`GET /v1/contacts`	`contacts:read`
Crear un contacto	`POST /v1/contacts`	`contacts:write`
Crear un sobre a partir de una plantilla y enviarlo	`POST /v1/envelopes/from-template`	`envelopes:send`
Obtener los enlaces de firma de un sobre enviado	`GET /v1/envelopes/{id}/signing-links`	`envelopes:send`

| Listar los eventos a los que puedes suscribirte | GET /v1/webhooks/events | webhooks:read | | Listar tus suscripciones de webhook | GET /v1/webhooks | webhooks:read | | Suscribir un endpoint a eventos | POST /v1/webhooks | webhooks:write | | Cancelar la suscripción de un endpoint | DELETE /v1/webhooks/{id} | webhooks:write |

¿Quieres recibir un aviso cuando un documento se firme, se rechace o se anule en lugar de sondear? Usa webhooks — y toma el PDF final directamente del payload de envelope.document_ready.

Convenciones

JSON de entrada, JSON de salida — envía y espera application/json.
Delimitado a tu empresa — cada recurso pertenece a una empresa y las peticiones nunca cruzan los límites entre empresas.
Los mismos permisos que la app — una clave solo puede hacer lo que permite el rol de su propietario. Consulta Usuarios y roles.
Los scopes restringen el acceso — los scopes de una clave (templates:read, contacts:read, contacts:write, envelopes:send, webhooks:read, webhooks:write) solo pueden limitar lo que su propietario ya podía hacer, nunca ampliarlo.

Paginación

Los endpoints de listado aceptan page (desde 1) y per_page (hasta 100, por defecto 25), y devuelven un objeto pagination:

{
  "data": [ /* … */ ],
  "pagination": { "page": 1, "per_page": 25, "total": 134, "total_pages": 6 }
}

Límites de frecuencia

Las peticiones se limitan por clave de API (el endpoint del token, por IP). Superar un límite devuelve 429 rate_limited: espera y reintenta.

Límite	Alcance
20 intercambios de token / 15 min	por IP
100 envíos / 15 min	por clave de API
1000 demás peticiones / 15 min	por clave de API

Errores

Todos los errores tienen la misma forma: ramifica según error.code, nunca según el texto del mensaje. Consulta la referencia de errores completa.

{ "error": { "code": "unknown_signer_role", "message": "…", "details": { } } }