Autenticación

Cada solicitud a la API de clientes se autentica con una API key de tu empresa, enviada en el header x-api-key. Tú mismo creas, rotas y revocas tus claves desde Pruff, sin pedirle nada a nadie.

Enviar la clave

Envía el valor completo de la clave, tal como lo viste al crearla, en el header x-api-key de cada solicitud:

curl https://api.pruff.com/api/clients/invoices \
  -H "x-api-key: pruff_sk_<tu-clave>"

Las claves nuevas empiezan con pruff_sk_ y siguen con 64 caracteres. Las claves que tu empresa ya usaba tienen otro formato y funcionan igual, con el mismo valor, sin que tengas que hacer nada. Guarda la clave en tu servidor, por ejemplo en un gestor de secretos o en una variable de entorno. Nunca la expongas en un navegador ni en una aplicación móvil.

Crear una clave

En Pruff, entra a Configuración → Otros → Claves de API.
Elige Crear clave.
Escribe un Nombre de 3 a 120 caracteres. Usa el nombre del sistema que la va a usar, por ejemplo ERP producción.
Elige la Expiración: 30 días, 90 días, 1 año o Sin expiración.
Confirma con Crear clave y copia la clave completa.

Pruff muestra la clave completa una sola vez. Después solo verás sus últimos cuatro caracteres, y no hay forma de recuperar el valor completo. Si lo pierdes, rota la clave.

Crea una clave por sistema. Así, si una se filtra, revocas solo esa y los demás sistemas siguen funcionando. Para administrar claves tu usuario necesita permiso para ello; si no ves la sección o los botones, pídele acceso a un administrador de tu empresa. La lista muestra para cada clave su nombre, sus últimos cuatro caracteres, su estado, cuándo expira y cuándo se usó por última vez. Ese último dato se actualiza como máximo una vez cada 5 minutos.

Estado	Significado
Activa	Funciona.
Expira pronto	Funciona, pero expira en 7 días o menos.
En rotación	Es la clave nueva de una rotación, y la anterior todavía funciona.
Revocada	Dejó de funcionar porque alguien la revocó.
Expirada	Dejó de funcionar porque llegó su fecha de expiración.

Expiración

Una clave con expiración deja de funcionar en el instante en que se cumple su plazo, contado desde su creación. Desde ese momento responde 401 y queda en la lista de claves inactivas. Una clave Sin expiración funciona hasta que la revoques. Una clave expirada no se puede renovar. Crea una nueva o rota la clave antes de que expire: la clave nueva recibe una expiración nueva, del mismo plazo que la original, contado desde la rotación. Una clave sin expiración sigue sin expirar después de rotarla.

Rotar una clave

Rota una clave para cambiar su valor sin cortar tu integración, o cuando sospeches que se filtró.

En Claves de API, elige Rotar en la fila de la clave.
Elige cuánto tiempo sigue funcionando la clave actual:
- Deja de funcionar ahora: úsalo si la clave se filtró.
- 24 horas: para cambiarla sin corte.
- 7 días: si tu despliegue necesita más tiempo.
Confirma con Rotar clave y copia la clave nueva, que se muestra una sola vez.

La clave nueva conserva el nombre de la actual y recibe una expiración nueva, del mismo plazo que la original, contado desde la rotación. Si la actual no expira, la nueva tampoco. Durante el margen que elegiste, ambas claves funcionan: cambia tu sistema a la clave nueva y, al terminar el margen, la anterior responde 401. La clave nueva aparece como En rotación hasta entonces, junto con la fecha en que la anterior deja de funcionar. La clave anterior sale de la lista en cuanto existe la nueva. Para cortar la clave anterior antes de que termine su margen, revoca la clave nueva: eso termina ambos márgenes y las dos dejan de funcionar de inmediato. Si rotas una clave que todavía tiene una anterior en margen, ese margen termina de inmediato. Puedes rotar tanto claves nuevas como las que tu empresa ya tenía.

Revocar una clave

Revoca una clave cuando un sistema deja de usarla o cuando se filtró y no necesitas un margen.

En Claves de API, elige Revocar en la fila de la clave.
Confirma con Revocar clave.

La revocación es inmediata y no se puede deshacer: toda solicitud con esa clave recibe 401 desde ese momento. La clave queda en la lista de claves inactivas, con la fecha y la persona que la revocó.

Respuesta 401

Una clave que no se puede usar recibe siempre la misma respuesta, sin indicar el motivo:

{
  "message": "Unauthorized: Invalid API Key"
}

Recibes este 401 cuando:

falta el header x-api-key;
el valor no corresponde a ninguna clave;
la clave fue revocada;
la clave expiró;
la clave fue rotada y terminó su margen;
la cuenta de API de tu empresa no está habilitada.

Para saber cuál es tu caso, revisa el estado de la clave en Configuración → Otros → Claves de API. La clave anterior de una rotación ya no aparece en la lista, así que, si tu sistema sigue usándola, cambia a la clave nueva. Reintentar la misma solicitud no sirve: usa una clave activa.

Límite de solicitudes

Todas las claves de tu empresa comparten un límite de 500 solicitudes por minuto. Las solicitudes rechazadas con 401 no cuentan, porque el límite se aplica después de autenticar. Algunos endpoints tienen además un límite propio, que aparece en su referencia. Al superar el límite recibes 429, con el header Retry-After y un body que indica cuánto esperar:

{
  "message": "Rate limit exceeded: 501 requests in the current 60s window, limit is 500. Retry in 12s.",
  "displayMessage": "Superaste el límite de 500 solicitudes cada 60 segundos. Vuelve a intentarlo en 12 segundos.",
  "data": {
    "code": "RATE_LIMIT_EXCEEDED",
    "scope": "All API keys of your company share this budget.",
    "limit": 500,
    "used": 501,
    "windowSeconds": 60,
    "retryAfterSeconds": 12,
    "resetAt": "2026-11-12T13:01:00.000Z",
    "hint": "Wait until resetAt (or honor the Retry-After header) before retrying. Avoid repeating identical requests: reuse responses you already fetched, use filters and larger pageSize values instead of one request per item, and cap your client concurrency."
  }
}

Espera hasta resetAt, o los segundos de Retry-After, antes de reintentar. Crear más claves no aumenta el límite, porque se comparte entre todas.

Inicio

API de clientes

Webhooks

Conector MCP

Enviar la clave

Crear una clave

Expiración

Rotar una clave

Revocar una clave

Respuesta 401

Límite de solicitudes