> ## 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.

# Integración con n8n

> Automatiza tu pipeline de pre-venta con flujos de n8n que se conectan a la API REST de Quikly.

[n8n](https://n8n.io) es una plataforma de automatización de flujos de trabajo open-source. Puedes usarla para construir automatizaciones sin código que creen propuestas a partir de leads entrantes, te notifiquen cuando los clientes respondan o sincronicen datos de Quikly con tu CRM.

## Configura tu clave de API en n8n

<Steps>
  <Step title="Crea una clave de API en Quikly">
    Ve a **Configuración → Claves de API** y crea una clave con scope `read,write`. Copia la clave completa.
  </Step>

  <Step title="Agrega un nodo HTTP Request en n8n">
    En tu flujo de n8n, agrega un nodo **HTTP Request**.
  </Step>

  <Step title="Configura la autenticación">
    Establece la autenticación como **Generic Credential Type → Header Auth**:

    * **Name**: `X-API-Key`
    * **Value**: `qk_your_api_key_here`
  </Step>

  <Step title="Establece la URL base">
    Usa `https://api.getquikly.com/api/external/v1` como URL base para todas las solicitudes.
  </Step>
</Steps>

<Tip>
  Crea una credencial de Header Auth reutilizable en n8n para no tener que ingresar tu clave de API en cada nodo.
</Tip>

## Plantillas de flujos

Quikly proporciona plantillas de flujos listas para importar en n8n.

### Lead a propuesta

Este flujo convierte un envío de formulario o trigger de webhook en una propuesta de Quikly:

1. **Trigger de webhook** — recibe datos del lead (nombre, email, descripción del proyecto)
2. **Analizar brief** — llama a `POST /ai/analyze-brief` para extraer requerimientos estructurados
3. **Obtener recomendación de tarifa** — llama a `POST /ai/rate-recommendation` para precios calibrados por mercado
4. **Crear propuesta** — llama a `POST /proposals` con los requerimientos y tarifa
5. **Compartir propuesta** — llama a `POST /proposals/{id}/share` para generar un enlace para el cliente
6. **Enviar notificación** — te envía el enlace de compartir por email o lo publica en Slack

```json Ejemplo: Nodo de análisis de brief theme={null}
{
  "method": "POST",
  "url": "https://api.getquikly.com/api/external/v1/ai/analyze-brief",
  "headers": {
    "X-API-Key": "qk_your_api_key_here",
    "Content-Type": "application/json"
  },
  "body": {
    "brief": "{{ $json.projectDescription }}",
    "language": "en"
  }
}
```

### Telegram a propuesta

Este flujo recibe mensajes de un bot de Telegram y crea propuestas a través del Agent Mode de Quikly:

1. **Trigger de Telegram** — recibe mensajes de tu bot de BotFather
2. **Crear o reanudar sesión de lead** — llama a `POST /lead-sessions` o `PATCH /lead-sessions/{id}`
3. **Chat del agente** — llama a `POST /agent/chat` para ejecutar el flujo conversacional de propuesta
4. **Responder en Telegram** — envía la respuesta del agente de vuelta al chat
5. **Cuando la propuesta está lista** — recibe un callback de webhook y envía el enlace de compartir a Telegram

### Monitor de estado de propuestas

Un flujo de polling que verifica las respuestas de los clientes:

1. **Trigger programado** — se ejecuta cada 15 minutos
2. **Listar propuestas** — llama a `GET /proposals?status=sent` para encontrar propuestas compartidas
3. **Verificar estado** — llama a `GET /proposals/{id}/status` para cada una
4. **Filtrar cambios** — compara con la ejecución anterior para detectar nuevas respuestas
5. **Notificar** — envía un mensaje a Slack o email cuando un cliente acepta, rechaza o solicita revisiones

## Triggers de webhook en n8n

En lugar de polling, puedes usar webhooks de Quikly para disparar flujos de n8n instantáneamente:

<Steps>
  <Step title="Crea un nodo de webhook en n8n">
    Agrega un nodo **Webhook** en n8n. Copia la URL generada (ej., `https://your-n8n.com/webhook/abc123`).
  </Step>

  <Step title="Registra el webhook en Quikly">
    Llama a `POST /webhooks` con la URL de n8n y los eventos que quieres escuchar.
  </Step>

  <Step title="Procesa el payload">
    El nodo de webhook recibe el payload del evento de Quikly. Úsalo para disparar acciones downstream.
  </Step>
</Steps>

```json Ejemplo: Registrar webhook para respuestas de clientes theme={null}
{
  "name": "n8n - Client responses",
  "url": "https://your-n8n.com/webhook/abc123",
  "events": [
    "proposal.accepted",
    "proposal.rejected",
    "proposal.revision_requested"
  ]
}
```

## Llamadas API comunes para n8n

| Acción                          | Método | Endpoint                                    |
| ------------------------------- | ------ | ------------------------------------------- |
| Listar propuestas               | `GET`  | `/proposals`                                |
| Crear propuesta                 | `POST` | `/proposals`                                |
| Obtener estado de propuesta     | `GET`  | `/proposals/{id}/status`                    |
| Analizar un brief               | `POST` | `/ai/analyze-brief`                         |
| Obtener recomendación de tarifa | `POST` | `/ai/rate-recommendation`                   |
| Compartir con el cliente        | `POST` | `/proposals/{id}/share`                     |
| Obtener parámetros de tarifa    | `GET`  | `/ai/rate-params`                           |
| Verificar cuota antes de actuar | `GET`  | `/usage/precheck?operation=proposal_create` |
| Crear sesión de lead            | `POST` | `/lead-sessions`                            |
| Turno de chat del agente        | `POST` | `/agent/chat`                               |

<Note>
  Todos los endpoints usan la URL base `https://api.getquikly.com/api/external/v1`. Consulta la [referencia de API](/api-reference) para los esquemas completos de solicitud y respuesta.
</Note>