API de firma electrónica

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.

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.

Constrúyelo en este orden

Una integración completa son cinco llamadas. Hazlas en este orden y te encontrarás con los tropiezos en el sitio más barato posible: un 404 en una plantilla que puedes leer, no un 422 en un envío que pretendías entregar.

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.

¿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, users:read) 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 }
}

Cuotas

Las lecturas no consumen nada de tu plan. Hay dos cosas medidas:

• Enviar consume la asignación independiente de solicitudes de firma por API: una unidad por sobre, sin importar cuántos destinatarios tenga. No es la misma bolsa que los sobres enviados desde la app. Cuando se agota, los envíos devuelven 402 quota_exceeded y no se entrega nada.
• Crear un contacto consume la asignación ordinaria de contactos de tu plan y devuelve 403 quota_exceeded cuando está llena. No necesitas crear contactos para enviarles documentos, así que es fácil de evitar.

Consulta ambas en Configuración → Facturación → Recursos.

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 con una cabecera estándar Retry-After en segundos: espera ese tiempo y reintenta.

Contar por clave (y no por IP) implica que una dirección de salida compartida —una plataforma de integración, un NAT— nunca hace que el tráfico de un cliente cuente contra el de otro.

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": { },
    "reference": "0190f3a2-7b6c-7e21-9a3f-2c9b1d4e5f60"
  }
}

reference aparece en los errores que registramos en el servidor (5xx y 422). Guárdalo en tus propios logs: citárnoslo localiza el fallo exacto con una sola consulta.

Guías relacionadas