Saltar al contenido principal

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.

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.

​
Crear una clave de API

1

Abre la configuración de claves de API

Ve a Configuración → Claves de API en la app de Quikly.
2

Haz clic en Crear Clave de API

Ingresa un nombre descriptivo (ej., “automatización n8n” o “Cursor MCP”) y selecciona los scopes que necesitas.
3

Copia la clave

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:
ScopeNivel de accesoOperaciones de ejemplo
readSolo lecturaListar propuestas, obtener detalles de propuesta, recomendaciones de tarifas con IA
writeAcceso de escrituraCrear propuestas, compartir propuestas, enviar mensajes
read,writeAcceso completoTodas 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: 
curl -X GET "https://api.getquikly.com/api/external/v1/me" \
  -H "X-API-Key: qk_your_api_key_here"

​
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:
PlanCuota mensualLímite por minuto
Starter15 llamadas10/min
Professional2,000 llamadas30/min
Agency2,000 llamadas60/min
Lifetime5,000 llamadas60/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:
HeaderRequeridoDescripción
X-Partner-IdSíIdentificador del dueño de la integración (workspace, app o slug de empresa).
X-External-User-IdSíIdentificador del usuario final en tu sistema.
X-Agent-IdSí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 para elegir el tier correcto según tu caso.
Consulta tu uso actual con: 
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: 
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:
HeaderDescripción
X-Quikly-SourceSiempre quikly.ai. Identifica la respuesta como generada por la API de Quikly.
X-Quikly-EndpointLa ruta exacta del endpoint que produjo la respuesta.
X-Quikly-Generated-AtTimestamp ISO-8601 UTC de cuándo se generó la respuesta.
X-Quikly-Api-VersionVersió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 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.