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

# Pipelines e Grupos

> Criar, configurar, reordenar e excluir funis de venda

## Listar pipelines e grupos

<Card>
  <strong>GET</strong> `/backend/pipelines`
</Card>

Retorna os grupos e as pipelines da conta, prontos para montar o seletor.

### Response

<ResponseField name="groups" type="Group[]">
  Grupos ordenados por `position`
</ResponseField>

<ResponseField name="pipelines" type="Pipeline[]">
  Pipelines ordenadas por `position`, cada uma com seu `group_id`
</ResponseField>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "groups": [
      { "id": "aa0e8400-e29b-41d4-a716-446655440000", "name": "Comercial", "position": 0 }
    ],
    "pipelines": [
      {
        "id": "bb0e8400-e29b-41d4-a716-446655440000",
        "group_id": "aa0e8400-e29b-41d4-a716-446655440000",
        "name": "Vendas Inbound",
        "description": "Leads vindos do site",
        "position": 0,
        "created_at": "2026-07-16T09:00:00Z"
      }
    ]
  }
  ```
</ResponseExample>

***

## Obter uma pipeline

<Card>
  <strong>GET</strong> `/backend/pipelines/{id}`
</Card>

Retorna a pipeline **com suas etapas e motivos de perda**.

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "id": "bb0e8400-e29b-41d4-a716-446655440000",
    "group_id": "aa0e8400-e29b-41d4-a716-446655440000",
    "name": "Vendas Inbound",
    "description": "Leads vindos do site",
    "position": 0,
    "stages": [
      { "id": "cc0e8400-e29b-41d4-a716-446655440000", "name": "Entrada", "color": "217 91% 60%", "position": 0 },
      { "id": "cc1e8400-e29b-41d4-a716-446655440000", "name": "Em andamento", "color": "38 92% 50%", "position": 1 },
      { "id": "cc2e8400-e29b-41d4-a716-446655440000", "name": "Ganho", "color": "152 60% 40%", "kind": "won", "position": 2 },
      { "id": "cc3e8400-e29b-41d4-a716-446655440000", "name": "Perdido", "color": "0 72% 56%", "kind": "lost", "position": 3 }
    ],
    "loss_reasons": [
      "Sem orçamento",
      "Sem resposta / sumiu",
      "Fechou com concorrente",
      "Sem fit com o produto",
      "Momento errado"
    ],
    "created_at": "2026-07-16T09:00:00Z"
  }
  ```
</ResponseExample>

<Info>
  `color` usa o formato de token do design system — uma tripla HSL sem o invólucro `hsl()`,
  como `"217 91% 60%"`.
</Info>

***

## Criar pipeline

<Card>
  <strong>POST</strong> `/backend/pipelines`
</Card>

Requer a permissão `pipeline.manage`. A pipeline criada já vem com as **quatro etapas padrão**
e os **motivos de perda padrão**.

### Request Body

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

<ParamField body="description" type="string">
  Descrição da pipeline
</ParamField>

<ParamField body="group_id" type="string">
  UUID de um grupo existente
</ParamField>

<ParamField body="new_group_name" type="string">
  Nome de um grupo a criar junto com a pipeline
</ParamField>

<Warning>
  Informe **`group_id` ou `new_group_name`** — a pipeline precisa pertencer a um grupo.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.leavo.ai/backend/pipelines" \
    -H "Authorization: Bearer sua_chave_aqui" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Vendas Inbound",
      "description": "Leads vindos do site",
      "new_group_name": "Comercial"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.leavo.ai/backend/pipelines', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sua_chave_aqui',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Vendas Inbound',
      description: 'Leads vindos do site',
      new_group_name: 'Comercial'
    })
  });
  ```

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

  response = requests.post(
      'https://api.leavo.ai/backend/pipelines',
      headers={'Authorization': 'Bearer sua_chave_aqui'},
      json={
          'name': 'Vendas Inbound',
          'description': 'Leads vindos do site',
          'new_group_name': 'Comercial'
      }
  )
  ```
</RequestExample>

Retorna **201 Created** com a pipeline.

***

## Configurar pipeline

<Card>
  <strong>PUT</strong> `/backend/pipelines/{id}`
</Card>

Salvamento **transacional** da tela "Configurar pipeline": nome, descrição, a lista completa
e ordenada de etapas, e os motivos de perda.

### Request Body

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

<ParamField body="description" type="string">
  Descrição da pipeline
</ParamField>

<ParamField body="stages" type="ConfigStage[]" required>
  Lista **completa e ordenada** de etapas. A posição no array define a ordem no quadro.
</ParamField>

<Expandable title="Propriedades de ConfigStage">
  <ParamField body="id" type="string">
    UUID da etapa existente. **Omita para criar uma etapa nova.**
  </ParamField>

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

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

<ParamField body="loss_reasons" type="string[]">
  Lista completa de motivos de perda da pipeline
</ParamField>

<ParamField body="reallocation_targets" type="object">
  Mapa `{ "id_da_etapa_removida": "id_da_etapa_destino" }` para as etapas que saíram da lista
</ParamField>

<Warning>
  **Etapas omitidas da lista `stages` são excluídas.** Se uma etapa removida ainda tiver
  negócios, é obrigatório informar seu destino em `reallocation_targets` — caso contrário a
  requisição retorna **409**. O destino precisa ser uma etapa que permaneceu na lista.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://api.leavo.ai/backend/pipelines/bb0e8400-e29b-41d4-a716-446655440000" \
    -H "Authorization: Bearer sua_chave_aqui" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Vendas Inbound",
      "description": "Leads vindos do site",
      "stages": [
        { "id": "cc0e8400-e29b-41d4-a716-446655440000", "name": "Entrada", "color": "217 91% 60%" },
        { "name": "Qualificação", "color": "271 81% 56%" },
        { "id": "cc2e8400-e29b-41d4-a716-446655440000", "name": "Ganho", "color": "152 60% 40%" },
        { "id": "cc3e8400-e29b-41d4-a716-446655440000", "name": "Perdido", "color": "0 72% 56%" }
      ],
      "loss_reasons": ["Sem orçamento", "Preço acima do esperado"],
      "reallocation_targets": {
        "cc1e8400-e29b-41d4-a716-446655440000": "cc0e8400-e29b-41d4-a716-446655440000"
      }
    }'
  ```
</RequestExample>

No exemplo acima, a etapa *Em andamento* saiu da lista e seus negócios foram movidos para
*Entrada*. A etapa *Qualificação* foi criada (não tem `id`).

***

## Reordenar pipeline

<Card>
  <strong>PUT</strong> `/backend/pipelines/reorder`
</Card>

Move uma pipeline para antes de outra e/ou para outro grupo.

### Request Body

<ParamField body="pipeline_id" type="string" required>
  UUID da pipeline movida
</ParamField>

<ParamField body="group_id" type="string" required>
  UUID do grupo de destino
</ParamField>

<ParamField body="before_id" type="string">
  UUID da pipeline que deve ficar **depois** da movida. Omita para posicionar no fim do grupo.
</ParamField>

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

***

## Excluir pipeline

<Card>
  <strong>DELETE</strong> `/backend/pipelines/{id}`
</Card>

<Warning>
  Exclui a pipeline e **todo o seu conteúdo**: etapas, motivos de perda, negócios, produtos dos
  negócios, tags, atividades, arquivos e histórico. A operação é irreversível.
</Warning>

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

***

## Grupos

Grupos organizam as pipelines no seletor (ex: *Marketing*, *Comercial*, *CS*).

### Listar grupos

<Card>
  <strong>GET</strong> `/backend/pipeline/groups`
</Card>

### Criar grupo

<Card>
  <strong>POST</strong> `/backend/pipeline/groups`
</Card>

<ParamField body="name" type="string" required>
  Nome do grupo
</ParamField>

Retorna **201 Created**.

### Renomear grupo

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

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

### Excluir grupo

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

<Warning>
  Um grupo que ainda contém pipelines **não pode ser excluído** — a resposta é **409** com a
  contagem. Mova as pipelines para outro grupo antes.
</Warning>

```json 409 Conflict theme={null}
{
  "code": "ERR_CONFLICT",
  "message": "O grupo tem 2 pipeline(s). Mova-as para outro grupo antes de excluir."
}
```