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

# Crear Etapa

> Crea una nueva etapa en el funnel

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

Agrega una nueva etapa a tu funnel. Por defecto se coloca al final.

<Tip>
  Si no especificas `position`, la etapa se agregará automáticamente al final del funnel.
</Tip>

***

## Body Parameters

<ParamField body="name" type="string" required>
  Nombre de la etapa (1-100 caracteres)
</ParamField>

<ParamField body="color" type="string" default="#6366f1">
  Color en formato hex. Ej: `#10b981`
</ParamField>

<ParamField body="position" type="number">
  Posición en el funnel (0 = primera). Si no se proporciona, se asigna al final.
</ParamField>

***

## Ejemplos

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.whaapy.com/funnel/v1/stages \
    -H "Authorization: Bearer wha_TU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Negotiation",
      "color": "#f59e0b"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.whaapy.com/funnel/v1/stages', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer wha_TU_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Negotiation',
      color: '#f59e0b'
    })
  });
  ```

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

  response = requests.post(
      'https://api.whaapy.com/funnel/v1/stages',
      headers={
          'Authorization': 'Bearer wha_TU_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'Negotiation',
          'color': '#f59e0b'
      }
  )
  ```

  ```php PHP theme={null}
  $ch = curl_init('https://api.whaapy.com/funnel/v1/stages');
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer wha_TU_API_KEY',
      'Content-Type: application/json'
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'name' => 'Negotiation',
      'color' => '#f59e0b'
  ]));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  ```
</RequestExample>

***

## Respuesta Exitosa

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "stage": {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "name": "Negotiation",
      "position": 3,
      "color": "#f59e0b",
      "contact_count": 0,
      "created_at": "2026-01-28T12:00:00Z",
      "updated_at": "2026-01-28T12:00:00Z"
    }
  }
  ```
</ResponseExample>

***

## Errores

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "error": "validation_error",
    "message": "Datos inválidos",
    "details": {
      "name": ["El nombre es requerido"],
      "color": ["Color inválido. Usar formato hex: #RRGGBB"]
    }
  }
  ```
</ResponseExample>

***

## Webhooks

Cuando creas una etapa, se dispara el webhook `funnel_stage.created`:

```json theme={null}
{
  "event": "funnel_stage.created",
  "data": {
    "stage_id": "550e8400-e29b-41d4-a716-446655440003",
    "name": "Negotiation",
    "position": 3,
    "color": "#f59e0b",
    "created_at": "2026-01-28T12:00:00Z"
  }
}
```

***

## Próximos Pasos

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

  <Card title="Mover Contacto" icon="arrow-right" href="/api-reference/funnels/contacts-move">
    Asignar contactos a la nueva etapa
  </Card>
</CardGroup>