## Visão geral

O módulo de Vendas da Conversa Labs tem **superfícies de consumo** (onde você lê os números) e uma
**superfície ao vivo** (o TELÃO). As de consumo são três:

- **Painel do Vendedor** — a leitura individual: suas moedas, badges, nível, pontos do mês e o
  progresso das suas metas.
- **Painel do Gestor** — a visão agregada da equipe, montada a partir do ranking (leaderboard), dos
  Relatórios e do TELÃO.
- **Relatórios de vendas** — o painel analítico de atingimento, histórico de comissões (payout) e
  histórico de ranking, com exportação em CSV.

Acima de tudo isso, o **TELÃO (wallboard)** mostra o ranking ao vivo em uma TV do escritório. Em
todas as superfícies, **os números derivam de eventos reais** do produto — negócios ganhos no CRM,
pagamentos confirmados, agendamentos, follow-ups que convertem. Não há digitação manual: o que você
lê é o que a operação realmente produziu.

## Pré-requisitos

- Módulo **Vendas & Gamificação** habilitado na conta.
- **Eventos reais fluindo** na plataforma (negócios no CRM, pagamentos, agendamentos), para que haja
  o que pontuar e relatar.
- **Metas ativas** no período vigente, para que o atingimento tenha referência.
- Para abrir os **Relatórios de vendas** e as **exportações CSV** (incluindo o livro de um vendedor
  específico), é necessária a permissão de **gestão de vendas** (`sales_manage`) — ou ser
  administrador. O Painel do Vendedor não exige essa permissão.

## Passo a passo

1. **Abra o Painel do Vendedor.** Confira, de relance, saldo de moedas, badges, nível, pontos do mês
   e o progresso de até 5 metas ativas.
2. **Acompanhe o ranking.** Veja sua posição no leaderboard (por métrica, período e escopo) e no
   TELÃO ao vivo.
3. **Gestor: abra os Relatórios de vendas.** Leia as três seções — atingimento, histórico de payout
   e histórico do leaderboard.
4. **Aplique filtros.** Estreite por período, vendedor, métrica e escopo para responder a uma
   pergunta específica.
5. **Exporte em CSV.** Baixe o extrato de comissões ou o histórico de ranking para conciliar ou
   analisar fora da plataforma.

## Configurações & opções

### Painel do Vendedor

A leitura individual é sempre da **sua própria** carteira. Os widgets:

| Widget | O que mostra | De onde vem |
|---|---|---|
| Saldo de moedas | Moedas disponíveis para resgate | Soma do extrato de moedas (créditos menos débitos) |
| Badges conquistados | Quantidade de medalhas que você ganhou | Premiações de badge atribuídas a você |
| Nível atual | Seu nível e os pontos acumulados que o sustentam | Maior nível cujo limiar de pontos você ultrapassou |
| Pontos do mês | Pontos somados no mês corrente | Eventos de pontos do mês vigente |
| Metas ativas | Até 5 metas (a sua, a da sua equipe e a da conta) com % de atingimento | Metas vigentes mais o atingimento calculado |

### Painel do Gestor

O gestor consolida a equipe a partir de três fontes: o **leaderboard** (ranking por métrica × período
× escopo), os **Relatórios de vendas** (atingimento, payout e histórico do ranking) e o **TELÃO** ao
vivo. É aqui que **carteira, metas e ranking** se conectam: a carteira define o dono de cada negócio,
as metas definem o alvo, e o ranking ordena quem está mais perto de bater. O Painel do Vendedor
continua individual mesmo para o gestor — a visão de equipe vem do ranking e dos Relatórios.

### Relatórios de vendas

O overview analítico traz três seções:

| Seção | O que traz |
|---|---|
| Atingimento (attainment) | % de atingimento por meta vigente, com valor atual e data do cálculo (até 50 metas, da maior para a menor) |
| Histórico de payout | Totais de comissão por período: acumulado, aprovado e pago |
| Histórico do leaderboard | O vencedor (1º lugar) por período e métrica |

Filtros disponíveis:

| Filtro | Efeito |
|---|---|
| Período (`period_start`) | Considera registros a partir da data informada |
| Vendedor (`payee_id`) | Restringe ao extrato de um vendedor (livro individual) |
| Métrica (`metric`) | Filtra o histórico de ranking pela métrica |
| Escopo (`scope_type`) | Filtra o histórico de ranking por tipo de escopo (conta/equipe/vendedor) |

### Exportação CSV

A exportação aceita `?kind=commissions` ou `?kind=leaderboard` (sem o parâmetro, o padrão é
comissões):

| Exportação | Quando usar | Colunas |
|---|---|---|
| Comissões (`?kind=commissions`) | Conciliar payout e contabilidade | `payee_id`, `period_start`, `period_end`, `status`, `total_accrued`, `total_approved`, `total_paid` |
| Leaderboard (`?kind=leaderboard`) | Analisar o histórico do ranking | `rank`, `user_id`, `team_id`, `scope_type`, `period_type`, `period_start`, `metric`, `value`, `trend` |

### Permissões e privacidade

- O **Painel do Vendedor** é isolado por vendedor: cada métrica (moedas, badges, nível, pontos) é
  filtrada pelo seu usuário. Um vendedor não enxerga os números de outro.
- O **ranking** (leaderboard/TELÃO) é a visão compartilhada da competição.
- Os **Relatórios de vendas** e as **exportações CSV** exigem a permissão de **gestão de vendas**.
  Puxar o **livro de um vendedor específico** (filtro por vendedor) também é uma ação de gestão.

## Casos de uso

- O vendedor abre o painel pela manhã e vê, em segundos, quão perto está da meta do mês.
- O gestor usa os Relatórios para identificar quem está acima e abaixo do atingimento por meta.
- O financeiro exporta o CSV de comissões para conciliar o payout do período.
- A liderança exporta o histórico do leaderboard para analisar a evolução do ranking ao longo dos
  períodos.

## Dicas, limites e boas práticas

- Trate o Painel do Vendedor como ritual diário — é a forma mais rápida de ver o progresso da meta.
- Nos Relatórios, comece sem filtros e estreite aos poucos; filtros muito restritos podem esvaziar o
  resultado.
- O atingimento lista as metas vigentes da maior para a menor — use-o para priorizar quem precisa de
  apoio.
- A exportação de comissões reflete o extrato (payout); a de leaderboard reflete os snapshots do
  ranking. Escolha a que responde à sua pergunta.

## Solução de problemas

- **Painel zerado**: provavelmente não há eventos pontuáveis no período (negócios, pagamentos,
  agendamentos) ou não há metas ativas. Confirme o uso de CRM/Pagamentos/Agenda e a existência de
  metas vigentes.
- **Relatório vazio**: os filtros podem estar restritos demais ou o escopo errado. Amplie o período,
  limpe o filtro de vendedor/métrica e revise o tipo de escopo.
- **Exportação bloqueada**: você não tem a permissão de **gestão de vendas**. Peça a um administrador
  para conceder o perfil adequado.

## Veja também

- [Visão geral de Vendas e Gamificação](/hc/ajuda/articles/sales-gamification-overview-pt-br)
- [Gestão de vendas: carteira, isolamento por vendedor e metas](/hc/ajuda/articles/sales-gamification-gestao-de-vendas-carteira-metas-pt-br)
- [Gamificação, leaderboard, recompensas e comissões](/hc/ajuda/articles/sales-gamification-gamificacao-leaderboard-recompensas-comissoes-pt-br)
- [TELÃO (wallboard) em tempo real](/hc/ajuda/articles/sales-gamification-telao-wallboard-pt-br)