> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whaapy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Funnels

> Gestiona las etapas de tu funnel de ventas y mueve contactos entre ellas

## ¿Qué es el Funnel de Whaapy?

El funnel de Whaapy te permite organizar tus contactos en etapas de tu proceso de ventas. Cada negocio tiene un único funnel con múltiples etapas personalizables.

<Frame>
  ```
  ┌─────────┐    ┌───────────┐    ┌──────────┐    ┌─────────┐
  │  Lead   │ → │ Qualified │ → │ Proposal │ → │ Closed  │
  │  (120)  │    │   (45)    │    │   (20)   │    │  (30)   │
  └─────────┘    └───────────┘    └──────────┘    └─────────┘
  ```
</Frame>

## Conceptos Clave

<AccordionGroup>
  <Accordion title="Etapas (Stages)">
    Cada etapa representa un paso en tu proceso de ventas. Las etapas tienen:

    * **Nombre**: Identificador visible (ej: "Lead", "Qualified")
    * **Posición**: Orden en el funnel (0 = primera)
    * **Color**: Color hex para visualización (#6366f1)
    * **Contactos**: Número de contactos en esa etapa
  </Accordion>

  <Accordion title="Movimiento de Contactos">
    Los contactos pueden moverse entre etapas:

    * Manualmente vía API
    * Automáticamente vía webhooks de sistemas externos
    * Un contacto solo puede estar en una etapa a la vez
    * `stage_id: null` quita al contacto de todas las etapas
  </Accordion>

  <Accordion title="Webhooks">
    Cada acción dispara webhooks para sincronización:

    * `funnel_stage.created` - Nueva etapa creada
    * `funnel_stage.updated` - Etapa modificada
    * `funnel_stage.deleted` - Etapa eliminada
    * `contact.stage_changed` - Contacto movido de etapa
  </Accordion>
</AccordionGroup>

## Autenticación

Todos los endpoints requieren autenticación con API Key:

```bash theme={null}
Authorization: Bearer wha_TU_API_KEY
```

<Info>
  Obtén tu API Key en [Dashboard → Configuración → API](https://app.whaapy.com/settings/api)
</Info>

## Scopes Requeridos

| Endpoint              | Scope           |
| --------------------- | --------------- |
| GET (listar, obtener) | `funnels:read`  |
| POST, PATCH, DELETE   | `funnels:write` |

## Endpoints Disponibles

<CardGroup cols={2}>
  <Card title="Listar Etapas" icon="list" href="/api-reference/funnels/stages-list">
    `GET /funnel/v1/stages`
  </Card>

  <Card title="Obtener Etapa" icon="circle-info" href="/api-reference/funnels/stages-get">
    `GET /funnel/v1/stages/:id`
  </Card>

  <Card title="Crear Etapa" icon="plus" href="/api-reference/funnels/stages-create">
    `POST /funnel/v1/stages`
  </Card>

  <Card title="Actualizar Etapa" icon="pen" href="/api-reference/funnels/stages-update">
    `PATCH /funnel/v1/stages/:id`
  </Card>

  <Card title="Eliminar Etapa" icon="trash" href="/api-reference/funnels/stages-delete">
    `DELETE /funnel/v1/stages/:id`
  </Card>

  <Card title="Reordenar Etapas" icon="arrows-up-down" href="/api-reference/funnels/stages-reorder">
    `PATCH /funnel/v1/stages/reorder`
  </Card>

  <Card title="Mover Contacto" icon="arrow-right" href="/api-reference/funnels/contacts-move">
    `POST /funnel/v1/contacts/:id/move`
  </Card>
</CardGroup>

## Casos de Uso Comunes

### Sincronización con CRM

```javascript theme={null}
// Cuando un lead cambia de etapa en tu CRM, actualiza Whaapy
await fetch('https://api.whaapy.com/funnel/v1/contacts/uuid/move', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wha_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    stage_id: 'qualified-stage-uuid'
  })
});
```

### Automatización con n8n/Zapier

1. **Trigger**: Webhook `contact.stage_changed` de Whaapy
2. **Filter**: Si `new_stage.name === "Qualified"`
3. **Action**: Crear deal en tu CRM con datos del contacto

### Reportes de Pipeline

```javascript theme={null}
// Obtener vista de pipeline con conteos
const response = await fetch('https://api.whaapy.com/funnel/v1/stages', {
  headers: { 'Authorization': 'Bearer wha_xxx' }
});
const { stages } = await response.json();

// stages = [
//   { name: "Lead", contact_count: 120 },
//   { name: "Qualified", contact_count: 45 },
//   ...
// ]
```

## Límites y Consideraciones

<Warning>
  * **Máximo 50 etapas** por negocio
  * **No puedes eliminar** una etapa con contactos (muévelos primero)
  * **Reordenar** actualiza todas las posiciones en una transacción
</Warning>

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Listar Etapas" icon="list" href="/api-reference/funnels/stages-list">
    Empieza listando las etapas existentes
  </Card>

  <Card title="Mover Contacto" icon="arrow-right" href="/api-reference/funnels/contacts-move">
    Aprende a mover contactos entre etapas
  </Card>
</CardGroup>