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

# Visão Geral da Pipeline

> CRM kanban: funis de venda, etapas, negócios e catálogo de produtos

O módulo **Pipeline** é o CRM kanban da Leavo. Enquanto o módulo de **Leads** registra o
*contato*, a Pipeline registra a *negociação*: valor, produtos, etapa do funil e motivo de perda.

<Note>
  Todo negócio está sempre vinculado a um **Lead real**. Os dados de contato (nome, empresa,
  email, telefone) nunca são duplicados no negócio — são lidos do Lead no momento da leitura.
</Note>

## Hierarquia

```
Grupo (ex: Comercial)
└── Pipeline (ex: Vendas Inbound)
    ├── Etapas (ordenadas: Entrada → Em andamento → Ganho → Perdido)
    │   └── Negócios (deals)
    │       ├── Produtos (do catálogo ou avulsos)
    │       ├── Tags (compartilhadas com Leads)
    │       ├── Atividades (todos)
    │       ├── Arquivos
    │       └── Histórico (eventos)
    └── Motivos de perda
```

O **catálogo de produtos** é global por conta — é compartilhado por todas as pipelines,
nunca escopado a uma delas.

## Recursos

<CardGroup cols={2}>
  <Card title="Pipelines e Grupos" icon="folder-tree" href="/pt-BR/api-reference/pipeline/pipelines">
    Criar, configurar, reordenar e excluir funis e seus grupos
  </Card>

  <Card title="Etapas" icon="columns-3" href="/pt-BR/api-reference/pipeline/stages">
    Colunas do kanban, incluindo as etapas de Ganho e Perdido
  </Card>

  <Card title="Negócios" icon="handshake" href="/pt-BR/api-reference/pipeline/deals">
    Quadro, listagem paginada, criação, edição e movimentação
  </Card>

  <Card title="Produtos" icon="box" href="/pt-BR/api-reference/pipeline/products">
    Catálogo global de produtos da conta
  </Card>

  <Card title="Atividades, Arquivos e Histórico" icon="list-check" href="/pt-BR/api-reference/pipeline/activities">
    Tarefas, anexos e o log de eventos de cada negócio
  </Card>
</CardGroup>

## Etapas especiais (`kind`)

Uma etapa pode ter um `kind` que muda o comportamento do negócio ao entrar nela:

| `kind`      | Significado | Efeito                                       |
| ----------- | ----------- | -------------------------------------------- |
| *(ausente)* | Etapa comum | Nenhum                                       |
| `won`       | Ganho       | Preenche `won_at` no negócio                 |
| `lost`      | Perdido     | Preenche `lost_at` e **exige** `loss_reason` |

Cada pipeline tem no máximo **uma** etapa `won` e **uma** etapa `lost`. Elas **não podem ser
excluídas**, porque não existe rota que as recrie.

Toda pipeline nova nasce com quatro etapas padrão:

| Nome         | `kind` |
| ------------ | ------ |
| Entrada      | —      |
| Em andamento | —      |
| Ganho        | `won`  |
| Perdido      | `lost` |

E com os motivos de perda padrão: *Sem orçamento*, *Sem resposta / sumiu*,
*Fechou com concorrente*, *Sem fit com o produto*, *Momento errado*.

## Regras garantidas pela API

Estas regras são validadas no servidor — não são apenas travas de interface:

<AccordionGroup>
  <Accordion title="Perder um negócio sempre exige um motivo">
    Mover um negócio para a etapa `lost` (ou criá-lo já nela) sem `loss_reason` retorna
    **400**. Não existe caminho que perca um negócio em silêncio.
  </Accordion>

  <Accordion title="Excluir uma etapa com negócios exige um destino">
    Excluir uma etapa que ainda contém negócios sem informar `target_stage_id` retorna
    **409**. Os negócios nunca são apagados junto com a etapa.
  </Accordion>

  <Accordion title="Excluir um grupo com pipelines é bloqueado">
    Retorna **409** com a contagem de pipelines. Mova-as para outro grupo antes.
  </Accordion>

  <Accordion title="Excluir um produto do catálogo não quebra negócios">
    As linhas de produto já existentes viram linhas **avulsas** (`custom: true`), preservando
    nome e preço. Os negócios continuam editáveis.
  </Accordion>

  <Accordion title="A etapa precisa pertencer à pipeline">
    Criar ou mover um negócio para uma etapa de outra pipeline retorna **400**.
  </Accordion>
</AccordionGroup>

## Permissões

Toda rota da Pipeline — **inclusive as de leitura** — é protegida por uma permissão granular.
Um papel customizado sem `pipeline.view` recebe **403** da API, e não apenas um menu escondido.

| Código                     | Permite                                                 |
| -------------------------- | ------------------------------------------------------- |
| `pipeline.view`            | Ver as pipelines e negócios                             |
| `pipeline.manage`          | Criar e configurar pipelines, etapas e motivos de perda |
| `pipeline.deals.create`    | Criar negócios                                          |
| `pipeline.deals.edit`      | Editar e mover negócios entre etapas                    |
| `pipeline.deals.delete`    | Excluir negócios                                        |
| `pipeline.products.manage` | Gerenciar o catálogo de produtos                        |

O papel de sistema **OPERATOR** recebe `pipeline.view`, `pipeline.deals.create` e
`pipeline.deals.edit`.

Para descobrir as permissões efetivas do usuário autenticado:

<Card>
  <strong>GET</strong> `/backend/roles/my-permissions`
</Card>

## Valor de um negócio

O total de um negócio (`total`) é calculado assim:

* Se o negócio **tem produtos**: soma de `price × qty` de cada linha.
* Se **não tem produtos**: usa o campo legado `value`.

O campo `total` sempre vem calculado na resposta — não é preciso somar no cliente.

## Autenticação

Todos os endpoints da Pipeline exigem autenticação:

```bash theme={null}
Authorization: Bearer sua_chave_aqui
```

Veja [Autenticação](/pt-BR/authentication) para detalhes.