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

# Reordenar Etapas

> Cambia el orden de las etapas del funnel

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

Reorganiza las etapas de tu funnel en un nuevo orden. La operación es atómica: todas las posiciones se actualizan en una sola transacción.

<Tip>
  Usa este endpoint cuando el usuario arrastre etapas en tu UI de Kanban.
</Tip>

***

## Body Parameters

<ParamField body="stage_ids" type="string[]" required>
  Array de UUIDs de etapas en el nuevo orden deseado. La primera etapa tendrá posición 0.
</ParamField>

<Note>
  Debes incluir todos los IDs de las etapas que quieres reordenar. Las etapas no incluidas mantendrán su posición relativa.
</Note>

***

## Ejemplos

<RequestExample>
  ```bash cURL theme={null}
  curl -X PATCH https://api.whaapy.com/funnel/v1/stages/reorder \
    -H "Authorization: Bearer wha_TU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "stage_ids": [
        "550e8400-e29b-41d4-a716-446655440002",
        "550e8400-e29b-41d4-a716-446655440000",
        "550e8400-e29b-41d4-a716-446655440001"
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.whaapy.com/funnel/v1/stages/reorder', {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer wha_TU_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      stage_ids: [
        '550e8400-e29b-41d4-a716-446655440002', // Nueva posición 0
        '550e8400-e29b-41d4-a716-446655440000', // Nueva posición 1
        '550e8400-e29b-41d4-a716-446655440001'  // Nueva posición 2
      ]
    })
  });
  ```

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

  response = requests.patch(
      'https://api.whaapy.com/funnel/v1/stages/reorder',
      headers={
          'Authorization': 'Bearer wha_TU_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'stage_ids': [
              '550e8400-e29b-41d4-a716-446655440002',
              '550e8400-e29b-41d4-a716-446655440000',
              '550e8400-e29b-41d4-a716-446655440001'
          ]
      }
  )
  ```

  ```php PHP theme={null}
  $ch = curl_init('https://api.whaapy.com/funnel/v1/stages/reorder');
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer wha_TU_API_KEY',
      'Content-Type: application/json'
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'stage_ids' => [
          '550e8400-e29b-41d4-a716-446655440002',
          '550e8400-e29b-41d4-a716-446655440000',
          '550e8400-e29b-41d4-a716-446655440001'
      ]
  ]));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  ```
</RequestExample>

***

## Respuesta Exitosa

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

***

## Errores

### 400 Bad Request

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "error": "validation_error",
    "message": "Datos inválidos",
    "details": {
      "stage_ids": ["Debe proporcionar al menos una etapa"]
    }
  }
  ```
</ResponseExample>

### 404 Not Found

<ResponseExample>
  ```json 404 Not Found theme={null}
  {
    "error": "not_found",
    "message": "Algunas etapas no existen",
    "invalid_ids": ["id-que-no-existe"]
  }
  ```
</ResponseExample>

***

## Webhooks

Cuando reordenas etapas, se dispara el webhook `funnel_stages.reordered`:

```json theme={null}
{
  "event": "funnel_stages.reordered",
  "data": {
    "stage_ids": [
      "550e8400-e29b-41d4-a716-446655440002",
      "550e8400-e29b-41d4-a716-446655440000",
      "550e8400-e29b-41d4-a716-446655440001"
    ],
    "reordered_at": "2026-01-28T12:30:00Z"
  }
}
```

***

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Listar Etapas" icon="list" href="/api-reference/funnels/stages-list">
    Ver nuevo orden
  </Card>

  <Card title="Actualizar Etapa" icon="pen" href="/api-reference/funnels/stages-update">
    Modificar etapa individual
  </Card>
</CardGroup>