> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getquikly.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Claves de API
> Crea y gestiona claves de API para autenticarte con la API REST de Quikly desde herramientas externas, scripts y automatizaciones.
Las claves de API te permiten acceder a la API REST de Quikly de forma programática. Úsalas con n8n, scripts personalizados, pipelines CI/CD o cualquier cliente HTTP. El mismo tipo de clave autentica la extensión de navegador **Discovery Copilot** — ver [Discovery Copilot](/es/guides/discovery-copilot-extension).
## Crear una clave de API
Ve a **Configuración → Claves de API** en la app de Quikly.
Ingresa un nombre descriptivo (ej., "automatización n8n" o "Cursor MCP") y selecciona los scopes que necesitas.
La clave completa se muestra **solo una vez**. Cópiala y guárdala en un lugar seguro — no podrás recuperarla después.
## Scopes
Cada clave de API tiene uno o más scopes que controlan lo que puede hacer:
| Scope | Nivel de acceso | Operaciones de ejemplo |
| ------------ | ------------------- | ----------------------------------------------------------------------------------- |
| `read` | Solo lectura | Listar propuestas, obtener detalles de propuesta, recomendaciones de tarifas con IA |
| `write` | Acceso de escritura | Crear propuestas, compartir propuestas, enviar mensajes |
| `read,write` | Acceso completo | Todas las operaciones (predeterminado) |
Sigue el principio de mínimo privilegio. Si una integración solo necesita leer datos, crea una clave con scope `read` solamente.
## Autenticar solicitudes
Incluye tu clave de API en el header `X-API-Key` en cada solicitud:
```bash cURL theme={null}
curl -X GET "https://api.getquikly.com/api/external/v1/me" \
-H "X-API-Key: qk_your_api_key_here"
```
```javascript Node.js theme={null}
const response = await fetch("https://api.getquikly.com/api/external/v1/me", {
headers: {
"X-API-Key": "qk_your_api_key_here",
},
});
const user = await response.json();
console.log(user);
```
```python Python theme={null}
import requests
response = requests.get(
"https://api.getquikly.com/api/external/v1/me",
headers={"X-API-Key": "qk_your_api_key_here"},
)
print(response.json())
```
## Límites de tasa y cuota
Las llamadas a la API tienen límites de tasa por minuto y un tope mensual dependiendo de tu plan:
| Plan | Cuota mensual | Límite por minuto |
| ------------ | -------------- | ----------------- |
| Starter | 15 llamadas | 10/min |
| Professional | 2,000 llamadas | 30/min |
| Agency | 2,000 llamadas | 60/min |
| Lifetime | 5,000 llamadas | 60/min |
Cuando excedes la cuota mensual, la API devuelve `402 Payment Required`.
Cuando excedes el límite por minuto, la API devuelve `429 Too Many Requests` e incluye el header `Retry-After`.
### Límites por usuario final (`X-External-User-Id`)
Cuando `X-External-User-Id` está presente (tras normalización), la API aplica **límites adicionales** encima de los totales de tu cuenta:
* **Por usuario final por minuto:** por defecto 12 solicitudes/minuto por `X-External-User-Id` distinto (configurable en servidor).
* **Por usuario final por mes calendario UTC:** por defecto `min(cuota mensual de API de tu plan, 250)` llamadas para ese mismo `X-External-User-Id`.
Si se supera el slice del usuario final, las respuestas usan `402` con `error: external_user_quota_exceeded` o `429` con `error: external_user_rate_limit_exceeded`.
Estos límites usan contadores en memoria (se reinician al reiniciar el servidor y al cambiar el mes UTC en el contador mensual). Mitigan que un único tenant aguas abajo consuma todo el pool de una API key.
### Límites por agente / workflow (`X-Agent-Id`)
Cuando `X-Agent-Id` está presente (tras normalización), aplica el **mismo patrón** de forma **independiente** de `X-External-User-Id`:
* **Por agente por minuto:** por defecto 12 solicitudes/minuto (configurable en servidor).
* **Por agente por mes calendario UTC:** por defecto `min(cuota mensual de API de tu plan, 250)` llamadas para ese `X-Agent-Id`.
Errores: `402` con `error: agent_id_quota_exceeded` o `429` con `error: agent_id_rate_limit_exceeded`.
Si van tanto `X-External-User-Id` como `X-Agent-Id`, aplican **los tres** límites: cuenta, usuario final y agente.
## Headers de trazabilidad para integraciones
Para integraciones externas, envía estos headers en cada solicitud:
| Header | Requerido | Descripción |
| -------------------- | --------- | ----------------------------------------------------------------------------- |
| `X-Partner-Id` | Sí | Identificador del dueño de la integración (workspace, app o slug de empresa). |
| `X-External-User-Id` | Sí | Identificador del usuario final en tu sistema. |
| `X-Agent-Id` | Sí | Identificador del agente o workflow que disparó la solicitud. |
Las solicitudes sin estos headers pueden ser rechazadas con `400 Bad Request`.
Las API keys self-serve son para integraciones propias directas. La reventa multi-tenant o usar Quikly como backend oculto para clientes de terceros está restringido y puede activar suspensión de la key. Consulta [Self-serve vs Partner tier](/es/integrations/pricing-and-tiers) para elegir el tier correcto según tu caso.
Consulta tu uso actual con:
```bash theme={null}
curl -H "X-API-Key: qk_your_api_key_here" \
"https://api.getquikly.com/api/external/v1/usage"
```
También puedes pre-verificar antes de una operación:
```bash theme={null}
curl -H "X-API-Key: qk_your_api_key_here" \
"https://api.getquikly.com/api/external/v1/usage/precheck?operation=proposal_create"
```
## Headers de respuesta
Cada respuesta de la API pública incluye estos headers de atribución. Los clientes pueden ignorarlos sin problema, pero son útiles para logging, debugging y probar que un dato vino efectivamente de Quikly:
| Header | Descripción |
| ----------------------- | -------------------------------------------------------------------------------- |
| `X-Quikly-Source` | Siempre `quikly.ai`. Identifica la respuesta como generada por la API de Quikly. |
| `X-Quikly-Endpoint` | La ruta exacta del endpoint que produjo la respuesta. |
| `X-Quikly-Generated-At` | Timestamp ISO-8601 UTC de cuándo se generó la respuesta. |
| `X-Quikly-Api-Version` | Versión de la API que sirvió el request (actualmente `v1`). |
Quitar o enmascarar estos headers antes de reenviar contenido generado por Quikly a usuarios finales es una violación de los [Términos de Servicio §5.3.2](https://getquikly.com/legal/terms) en planes self-serve. Las integraciones Partner pueden negociar reglas de atribución en su acuerdo.
## Gestionar claves existentes
En **Configuración → Claves de API**, puedes:
* **Renombrar** una clave para mantener tu lista organizada
* **Desactivar** una clave temporalmente sin eliminarla
* **Revocar** una clave permanentemente — las claves revocadas no se pueden reactivar
## Mejores prácticas de seguridad
Nunca subas claves de API al control de versiones ni las expongas en código del lado del cliente.
* **Usa variables de entorno** para almacenar claves en tu entorno de despliegue.
* **Rota claves periódicamente** — crea una nueva clave, actualiza tus integraciones, luego revoca la anterior.
* **Usa el scope más restrictivo** que tu integración requiera.
* **Establece expiración** al crear claves para integraciones temporales. Puedes especificar `expires_in_days` durante la creación.
* **Monitorea el uso** consultando el endpoint de usage o la página de Claves de API en el dashboard. Cada clave muestra su marca de tiempo del último uso.
* **Revoca inmediatamente** si una clave se ve comprometida.
## Formato de clave
Las claves de API de Quikly siguen el formato `qk_` seguido de una cadena aleatoria. Cuando ves claves en el dashboard, solo el prefijo es visible (ej., `qk_abc1...`) — la clave completa solo se muestra al momento de crearla.