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

# Listar Etapas

> Obtiene todas las etapas del funnel con conteo de contactos

<Info>
  **Scope requerido:** `funnels:read`
</Info>

Obtén todas las etapas de tu funnel ordenadas por posición, incluyendo el número de contactos en cada una.

<Note>
  Las etapas siempre se devuelven ordenadas por `position` (ascendente). El `contact_count` se calcula dinámicamente.
</Note>

***

## Ejemplos

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.whaapy.com/funnel/v1/stages" \
    -H "Authorization: Bearer wha_TU_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.whaapy.com/funnel/v1/stages', {
    headers: { 'Authorization': 'Bearer wha_TU_API_KEY' }
  });
  const data = await response.json();
  console.log(data.stages);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.whaapy.com/funnel/v1/stages',
      headers={'Authorization': 'Bearer wha_TU_API_KEY'}
  )
  print(response.json())
  ```

  ```php PHP theme={null}
  $ch = curl_init('https://api.whaapy.com/funnel/v1/stages');
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer wha_TU_API_KEY'
  ]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  $data = json_decode($response, true);
  print_r($data['stages']);
  ```
</RequestExample>

***

## Respuesta Exitosa

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "stages": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Lead",
        "position": 0,
        "color": "#6366f1",
        "contact_count": 120,
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-28T10:00:00Z"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "Qualified",
        "position": 1,
        "color": "#10b981",
        "contact_count": 45,
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-28T10:00:00Z"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "name": "Closed",
        "position": 2,
        "color": "#f59e0b",
        "contact_count": 30,
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-28T10:00:00Z"
      }
    ],
    "total": 3
  }
  ```
</ResponseExample>

### Campos de Respuesta

| Campo                    | Tipo   | Descripción                            |
| ------------------------ | ------ | -------------------------------------- |
| `stages`                 | array  | Array de etapas ordenadas por posición |
| `stages[].id`            | string | UUID de la etapa                       |
| `stages[].name`          | string | Nombre de la etapa                     |
| `stages[].position`      | number | Posición en el funnel (0 = primera)    |
| `stages[].color`         | string | Color en formato hex                   |
| `stages[].contact_count` | number | Número de contactos en esta etapa      |
| `total`                  | number | Total de etapas                        |

***

## Errores

### 401 Unauthorized

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "error": "unauthorized",
    "message": "API key inválida o expirada"
  }
  ```
</ResponseExample>

### 403 Forbidden

<ResponseExample>
  ```json 403 Forbidden theme={null}
  {
    "error": "forbidden",
    "message": "Scope 'funnels:read' requerido"
  }
  ```
</ResponseExample>

***

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Crear Etapa" icon="plus" href="/api-reference/funnels/stages-create">
    Agregar nueva etapa al funnel
  </Card>

  <Card title="Mover Contacto" icon="arrow-right" href="/api-reference/funnels/contacts-move">
    Mover contacto entre etapas
  </Card>

  <Card title="Reordenar" icon="arrows-up-down" href="/api-reference/funnels/stages-reorder">
    Cambiar orden de etapas
  </Card>

  <Card title="Listar Contactos" icon="users" href="/api-reference/contacts/list">
    Filtrar contactos por etapa
  </Card>
</CardGroup>