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

# Etapas

> Colunas do quadro kanban, incluindo Ganho e Perdido

Etapas são as colunas do quadro. Cada etapa pertence a uma pipeline e tem uma `position` que
define sua ordem. Todas as rotas desta página exigem a permissão `pipeline.manage`.

<Info>
  Para criar ou reordenar **várias etapas de uma vez**, prefira
  [Configurar pipeline](/pt-BR/api-reference/pipeline/pipelines#configurar-pipeline) — é uma
  operação transacional que salva a lista completa.
</Info>

## O objeto Etapa

<ResponseField name="id" type="string">
  UUID da etapa
</ResponseField>

<ResponseField name="name" type="string">
  Nome exibido no topo da coluna
</ResponseField>

<ResponseField name="color" type="string">
  Cor no formato de token `"H S% L%"` (tripla HSL sem o invólucro `hsl()`)
</ResponseField>

<ResponseField name="kind" type="string">
  `won`, `lost` ou ausente para uma etapa comum
</ResponseField>

<ResponseField name="position" type="integer">
  Ordem da coluna no quadro (base 0)
</ResponseField>

***

## Criar etapa

<Card>
  <strong>POST</strong> `/backend/pipelines/{id}/stages`
</Card>

Adiciona uma etapa comum ao fim da pipeline. Não é possível criar etapas `won` ou `lost` —
elas já existem desde a criação da pipeline.

### Request Body

<ParamField body="name" type="string" required>
  Nome da etapa
</ParamField>

<ParamField body="color" type="string">
  Cor no formato `"H S% L%"`. Quando omitida, usa o cinza padrão `"215 16% 47%"`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.leavo.ai/backend/pipelines/bb0e8400-e29b-41d4-a716-446655440000/stages" \
    -H "Authorization: Bearer sua_chave_aqui" \
    -H "Content-Type: application/json" \
    -d '{ "name": "Proposta enviada", "color": "271 81% 56%" }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.leavo.ai/backend/pipelines/bb0e8400-e29b-41d4-a716-446655440000/stages',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sua_chave_aqui',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ name: 'Proposta enviada', color: '271 81% 56%' })
    }
  );
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": "cc4e8400-e29b-41d4-a716-446655440000",
    "name": "Proposta enviada",
    "color": "271 81% 56%",
    "position": 4
  }
  ```
</ResponseExample>

***

## Atualizar etapa

<Card>
  <strong>PUT</strong> `/backend/pipeline/stages/{id}`
</Card>

Renomeia, recolore ou reposiciona uma etapa. Campos omitidos permanecem inalterados.

### Request Body

<ParamField body="name" type="string">
  Novo nome
</ParamField>

<ParamField body="color" type="string">
  Nova cor no formato `"H S% L%"`
</ParamField>

<ParamField body="position" type="integer">
  Nova posição no quadro
</ParamField>

<Note>
  As etapas `won` e `lost` podem ser renomeadas e recoloridas normalmente — o `kind` é que não
  muda.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://api.leavo.ai/backend/pipeline/stages/cc4e8400-e29b-41d4-a716-446655440000" \
    -H "Authorization: Bearer sua_chave_aqui" \
    -H "Content-Type: application/json" \
    -d '{ "name": "Proposta", "position": 2 }'
  ```
</RequestExample>

***

## Excluir etapa

<Card>
  <strong>DELETE</strong> `/backend/pipeline/stages/{id}`
</Card>

### Query Parameters

<ParamField query="target_stage_id" type="string">
  Etapa que receberá os negócios da etapa excluída. **Obrigatório** quando a etapa ainda contém
  negócios.
</ParamField>

<Warning>
  Excluir uma etapa que ainda tem negócios **sem** `target_stage_id` retorna **409**. Os
  negócios nunca são apagados junto com a etapa — a API obriga a escolher um destino.
</Warning>

O destino precisa pertencer à mesma pipeline e não pode ser a própria etapa sendo excluída —
ambos os casos retornam **400**.

<Warning>
  As etapas de **Ganho** (`kind: "won"`) e **Perdido** (`kind: "lost"`) **não podem ser
  excluídas** (**400**), porque não existe rota que as recrie. A pipeline também precisa manter
  pelo menos uma etapa.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  # Etapa vazia — nenhum destino necessário
  curl -X DELETE "https://api.leavo.ai/backend/pipeline/stages/cc4e8400-e29b-41d4-a716-446655440000" \
    -H "Authorization: Bearer sua_chave_aqui"

  # Etapa com negócios — destino obrigatório
  curl -X DELETE "https://api.leavo.ai/backend/pipeline/stages/cc4e8400-e29b-41d4-a716-446655440000?target_stage_id=cc0e8400-e29b-41d4-a716-446655440000" \
    -H "Authorization: Bearer sua_chave_aqui"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  { "success": true }
  ```

  ```json 409 Conflict theme={null}
  {
    "code": "ERR_CONFLICT",
    "message": "A etapa \"Proposta enviada\" tem 12 negócio(s). Escolha para qual etapa eles devem ir."
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "code": "ERR_INVALID_INPUT",
    "message": "A etapa de ganho e a de perda não podem ser excluídas — a pipeline precisa delas para marcar negócios como ganhos ou perdidos"
  }
  ```
</ResponseExample>

<Tip>
  Fluxo recomendado na interface: tente o `DELETE` sem `target_stage_id`; se vier **409**,
  pergunte ao usuário para onde mover os negócios e repita com o parâmetro.
</Tip>