Obtener un token de acceso
Intercambia tu clave de API por un token de portador de corta duración: la primera llamada de toda integración con la API de firma electrónica.
Toda integración con la API de firma electrónica empieza aquí. Envías tu clave de API una sola vez a este endpoint y recibes un token de acceso de corta duración. A partir de ahí, todas las demás peticiones llevan solo el token: tu clave no vuelve a viajar.
Endpoint
POST https://api2.bunnydoc.com/v1/auth/token
Petición
La clave se envía en una cabecera. No hay cuerpo de petición.
| Cabecera | Obligatoria | Valor |
|---|---|---|
X-API-Key | Sí | Tu clave de API, p. ej. bd_live_a1b2c3d4e5f6…. Crea una en Configuración → Claves de API. |
Ejemplo de petición
curl -X POST https://api2.bunnydoc.com/v1/auth/token \
-H "X-API-Key: bd_live_a1b2c3d4e5f6g7h8"POST /v1/auth/token HTTP/1.1
Host: api2.bunnydoc.com
X-API-Key: bd_live_a1b2c3d4e5f6g7h8const res = await fetch("https://api2.bunnydoc.com/v1/auth/token", {
method: "POST",
headers: { "X-API-Key": process.env.BUNNYDOC_API_KEY },
});
const { access_token, expires_in } = await res.json();
// Cache access_token and reuse it for the next `expires_in` seconds.import os, requests
res = requests.post(
"https://api2.bunnydoc.com/v1/auth/token",
headers={"X-API-Key": os.environ["BUNNYDOC_API_KEY"]},
)
token = res.json()["access_token"]
# Cache the token and reuse it until it expires.Respuesta
Un 200 OK devuelve el token y los scopes que incluye.
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlfaWQiOiI…",
"token_type": "Bearer",
"expires_in": 3600,
"scopes": ["templates:read", "contacts:read", "contacts:write", "envelopes:send"]
}| Campo | Tipo | Descripción |
|---|---|---|
access_token | string | El token de portador. Envíalo como Authorization: Bearer <access_token> en todas las demás peticiones. |
token_type | string | Siempre Bearer. |
expires_in | integer | Segundos hasta que el token caduca: siempre 3600 (una hora). |
scopes | string[] | Los permisos que incluye el token, heredados de la clave. |
Usar el token
Envía el token en la cabecera Authorization en todas las demás llamadas. Por ejemplo, para listar
tus plantillas:
curl https://api2.bunnydoc.com/v1/templates \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"Errores
Todos los errores tienen la misma forma: ramifica según error.code, nunca según el texto del
mensaje.
{
"error": {
"code": "invalid_api_key",
"message": "The API key is invalid, revoked, expired, or not a live-mode key."
}
}| Estado | error.code | Cuándo ocurre |
|---|---|---|
401 | missing_api_key | No se envió la cabecera X-API-Key. |
401 | invalid_api_key | La clave es desconocida, revocada, caducada o no es de modo real. Las cuatro devuelven el mismo cuerpo: no revelamos cuál. |
403 | forbidden | El acceso a la API no está incluido en el plan actual de tu empresa. |
429 | rate_limited | Más de 20 peticiones de token en 15 minutos desde una IP. Solicita un token por hora, no uno por llamada. |
Consulta la referencia de errores completa con todos los códigos que puede devolver la API.
Bueno saberlo
Los tokens duran una hora: guárdalos en caché y reutilízalos
expires_in siempre es 3600 segundos. Solicita un token, consérvalo e intercambia tu clave de
nuevo solo cuando el token esté a punto de caducar. El endpoint de intercambio de tokens tiene un
límite de 20 peticiones por 15 minutos por IP precisamente porque una integración sana necesita
alrededor de un token por hora, no uno por petición.
Revocar o rotar una clave invalida sus tokens de inmediato
No hace falta esperar a que caduque un token. En cuanto se rota o revoca una clave en Configuración → Claves de API, todos los tokens generados a partir de ella dejan de funcionar en su siguiente petición.
Siguientes pasos
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.
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.