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

# Pipelines e leads

> Como o Apollo Space modela o funil — pipelines, stages, leads e atividades.

## Hierarquia simples

```
Organização
  └── Pipeline (1+)
        └── Stages (estágios do funil)
              └── Leads (cards que percorrem os stages)
                    └── Atividades (cada movimentação)
```

Cada org pode ter **múltiplos pipelines** independentes. Cada pipeline
tem **stages próprios**. Leads vivem em UM pipeline + UM stage por vez
(mas podem ser movidos entre pipelines).

## Pipeline

Um **pipeline** representa um **fluxo** específico do seu funil — um
caminho que um lead percorre do início ao fim.

Exemplos comuns:

| Pipeline               | Quando faz sentido                                                   |
| ---------------------- | -------------------------------------------------------------------- |
| **Outbound novo**      | Leads que VOCÊ buscou ativamente (Maps lead search, lista importada) |
| **Inbound**            | Leads que CHEGARAM (formulário do site, redes sociais)               |
| **Pós-venda — Upsell** | Clientes existentes em ciclo de upsell                               |
| **Renovação**          | Clientes próximos do fim do contrato                                 |
| **Cancelados**         | Ex-clientes que podem voltar (re-engagement)                         |

A separação de pipelines existe pra que **cada um tenha sua própria
métrica + cadência**. O conversion rate de outbound não deve se misturar
com o de inbound.

## Stages

Stages são os **estágios** que um lead percorre dentro de um pipeline.
Defaults razoáveis pra outbound B2B:

```
Novo lead → Qualificado → Em conversa → Proposta enviada → Negociação → Fechado-Ganho
                                                                    ↘ Fechado-Perdido
```

Você customiza livremente — adicionar / remover / renomear / reordenar
stages. Stages podem ser **arquivados** (some da UI mas leads
históricos preservam o stage que tinham na época).

### Stages "fechados"

Stages podem ser marcados como **fechados-ganho** ou **fechados-perdido**.
Isto:

* Move o lead pra view de "histórico" automaticamente
* Conta nas métricas de conversion rate
* Sinaliza pros agentes "não precisa fazer mais nada com este lead"

## Lead

Um **lead** é um card que vive em um stage de um pipeline. Cada lead
carrega:

* Dados de contato (nome, e-mail, telefone, site)
* Dados de empresa (nome, localização, setor)
* **Owner** — pessoa responsável (humano ou agente)
* **Valor potencial** — quanto vale fechar esse lead (em centavos da
  moeda configurada)
* **Tags** — labels customizáveis
* **Custom fields** — campos da sua org

### Owner

Quem é "dono" do lead determina quem o sistema notifica em eventos
(reply chegou, hora de follow-up, etc.). O owner pode ser:

* Um **humano** (membro da org)
* Um **agente** (Marcus, Athena, ou customizado)

Quando um agente é owner, o agente opera autonomamente conforme a
configuração — e roteia eventos pro humano supervisor quando faz
sentido.

## Atividades

Toda movimentação relevante de um lead gera uma **atividade** no
histórico. É o **audit log** do CRM — append-only, nada deletado.

Tipos automáticos:

| Tipo                                  | Significa                        |
| ------------------------------------- | -------------------------------- |
| `lead_imported`                       | Lead criado (CSV / API / agente) |
| `stage_changed`                       | Movido entre stages              |
| `pipeline_moved`                      | Movido entre pipelines           |
| `assignment_changed`                  | Owner mudou                      |
| `field_updated`                       | Algum campo alterado             |
| `email_sent` / `email_received`       | E-mails                          |
| `whatsapp_sent` / `whatsapp_received` | WhatsApp                         |
| `note_added`                          | Nota livre (humano ou agente)    |
| `contact_enriched`                    | Enrichment via Apify             |
| `task_created`                        | Task interna                     |

Cada atividade carrega **quem fez** (humano X ou agente Y), **quando**
e o **payload da mudança**. Auditoria total — você reconstrói o
histórico de qualquer lead em segundos.

### Movimentação humano vs agente

Quando o **Marcus** move um lead de stage (ex.: "Em conversa" →
"Proposta enviada" após disparar a proposta), a atividade carrega
`actor_type = 'agent'` + o ID do agente.

Quando **você** move manualmente, `actor_type = 'user'` + seu user ID.

Isso aparece na timeline do lead — em vez de "Stage mudou para X",
você vê "**Marcus** moveu pra X" ou "**João Silva** moveu pra X". Sem
ambiguidade.

## Filtros e segmentação

Filtros aplicam-se sobre o conjunto de leads visíveis. Combina:

* Pipeline + stage
* Owner (humano específico, qualquer humano, agente específico)
* Tags
* Custom field values
* Data (criação, última atividade, próxima ação)
* Valor potencial (range)

Filtros podem ser **salvos** pra reuso. São per-user — cada um tem os
seus.

## Próximos passos

<CardGroup cols={2}>
  <Card title="CRM (feature)" icon="users" href="/features/crm">
    Como operar no dia-a-dia: kanban, lista, custom fields, import.
  </Card>

  <Card title="Outbound" icon="paper-plane" href="/features/outbound">
    Como leads viram campanhas geridas pelo Marcus.
  </Card>

  <Card title="Agentes" icon="robot" href="/concepts/agents">
    Quando um agente é owner de um lead, ele opera autonomamente.
  </Card>
</CardGroup>