# Relatórios e gráficos

> Oito ferramentas MCP só de consulta para ver como está a comunidade e transformar em gráfico ou tabela na conversa — vendas, assinaturas e MRR, membros ativos, engajamento e ranking, eventos, cursos, a atividade de um membro e o painel do mês — com receitas prontas.

Peça ao assistente como estão as vendas, quem mais participa ou o que uma pessoa fez, e ele responde com números e, se você quiser, com um gráfico ou uma tabela na própria conversa (no Claude, como um artefato). As oito ferramentas desta página só consultam: nenhuma muda nada na comunidade.

## Em resumo

| Ferramenta | O que faz | Papel mínimo | Tipo |
|---|---|---|---|
| [`sales_report`](#sales-report) | Vendas por dia, semana ou mês, por plano, produto ou forma de pagamento, e o total desde a primeira venda | Administrador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`subscriptions_report`](#subscriptions-report) | MRR, assinaturas novas e canceladas, churn, cortesias e downsell | Administrador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`members_report`](#members-report) | Membros novos, ativos e inativos, por grupo e por tag | Moderador | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`engagement_report`](#engagement-report) | Posts, comentários, reações, quem mais engaja, posts sem resposta e os pontos do ranking | Moderador | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`events_report`](#events-report) | Eventos e quantos responderam vou, talvez e não vou | Moderador | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`courses_report`](#courses-report) | Matrículas, conclusões e progresso por curso | Moderador | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`member_activity`](#member-activity) | O que uma pessoa fez: contagens, pontos do ranking e links | Administrador | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`community_overview`](#community-overview) | Este mês contra o mês passado, num pedido só | Moderador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |

**Quem vê o quê.** Dinheiro (vendas e assinaturas) é do proprietário, do administrador e do **financeiro**. Comunidade (membros, engajamento, eventos e cursos) é do proprietário, do administrador e do **moderador**. A atividade de uma pessoa específica é só do proprietário e do administrador. No `community_overview`, cada um vê só o bloco da sua área: o financeiro vê o dinheiro, o moderador vê a comunidade.

## Como as respostas chegam

Toda resposta vem pronta para virar gráfico:

| Parte | O que é |
|---|---|
| `series` | Uma linha por período (`period`), com os números daquele período. Períodos sem nada aparecem com zero, para o gráfico não pular um mês |
| `totals` | A soma do intervalo pedido |
| `currency` | A moeda dos valores (uma por consulta; padrão, a moeda em que a comunidade mais vende) |
| `timezone` | O fuso usado para contar os dias |

Parâmetros comuns:

| Parâmetro | Valores | Padrão |
|---|---|---|
| `interval` | `day`, `week` (começa na segunda) ou `month` | `month` |
| `from`, `to` | Datas `AAAA-MM-DD`, inclusive. São alargadas até o começo e o fim do período: com `month`, 15/03 vira 01/03 | 30 dias, 12 semanas ou 12 meses até hoje |
| `timezone` | Um fuso como `America/Sao_Paulo` | O fuso do país da comunidade |

Uma consulta cobre no máximo 366 dias, 156 semanas ou 120 meses. Para um período maior, use um intervalo maior.

**O que cada número quer dizer:**

- **Vendas** vêm do [extrato](/pagamentos/saldo-e-extrato): o líquido do relatório é o líquido do extrato no mesmo período. A única taxa que aparece é a [taxa da plataforma](/pagamentos/taxa-da-plataforma), que independe do método de pagamento.
- **MRR** é a receita recorrente mensal: cada assinatura pagante convertida para o mês (a anual dividida por 12). Cortesias e assinaturas em teste ficam fora.
- **Ativo** é quem fez pelo menos uma coisa no período: publicou, comentou, reagiu, respondeu a um evento (vou ou talvez), se matriculou ou estudou num curso, ou ganhou pontos no ranking (o que inclui o login diário, quando o ranking está ligado). Só ler não conta, porque visualizações não são registradas.
- **Presença em evento** não existe: a Memberfy guarda a resposta de cada pessoa (vou, talvez, não vou), não quem compareceu. O relatório diz isso (`attendanceTracked: false`).

## `sales_report`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Relatório de vendas.** Por período: bruto, taxa da plataforma, juros de parcelamento, líquido, número de vendas, ticket médio, reembolsos e contestações (separados), e o líquido depois deles. Traz também os saques pedidos e concluídos e o total desde a primeira venda. *Papel mínimo: administrador ou financeiro.*

Parâmetros: os comuns, mais `group_by` (`product`, `plan`, `payment_method` ou `product_type`) e `currency`.

**Devolve:** `series`, `totals`, `allTime` (desde sempre), `payouts` e, com `group_by`, `groups`: cada plano, produto ou forma de pagamento com a sua própria série. Uma venda que não pertence a plano nenhum cai no grupo sem nome.

**Peça assim:** *"Quanto eu ganhei no total desde que comecei a vender?"*

**Depois:** a resposta sugere, em `next_steps`, o mesmo relatório no período imediatamente anterior, com as datas prontas, para comparar. Ver [Próximos passos](/mcp/ferramentas#proximos-passos).

## `subscriptions_report`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Relatório de assinaturas.** Por período: MRR, assinaturas pagantes, novas, canceladas, churn (a porcentagem das que estavam ativas no começo do período e cancelaram), em teste e cortesias. *Papel mínimo: administrador ou financeiro.*

Parâmetros: os comuns, mais `currency`.

**Devolve:** `series`, `totals`, o retrato de hoje em `current` (MRR, ARR, por status, quantas vão encerrar no fim do período, em atraso, cortesias), `byPlan` e `downsell` (ofertas de última chance exibidas e aceitas).

**Peça assim:** *"Como evoluiu o MRR este ano? Qual foi o churn de cada mês?"*

> [!NOTE]
> O histórico é refeito pelas datas de início e de fim de cada assinatura. Um atraso que já se resolveu ou uma pausa não deixam data, então só aparecem no retrato de hoje.

## `members_report`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Relatório de membros.** Por período: quantos entraram, quantos estavam ativos, o total no fim do período e os inativos. *Papel mínimo: moderador.*

Parâmetros: os comuns.

**Devolve:** `series`, `totals`, `current` (total, ativos e inativos nos últimos 30 dias, por papel), `byGroup` e `byTag`.

**Peça assim:** *"Quantos membros novos tivemos por semana no último trimestre, e quantos estavam ativos?"*

## `engagement_report`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Relatório de engajamento e ranking.** Por período: posts do feed, conteúdos, comentários, reações, membros ativos e pontos do ranking. Mostra também onde a conversa acontece, quem mais participou, os posts que ninguém respondeu e os dados que formam o [ranking](/espacos/ranking). *Papel mínimo: moderador.*

Parâmetros: os comuns, mais `order_by` (`points`, `interactions`, `posts`, `comments` ou `reactions`; padrão `points` com o ranking ligado), `page` e `limit` (até 100).

**Devolve:** `series`, `totals`, `bySpace`, `members` (paginado: posts, comentários, reações, interações, pontos no período e o nível de hoje), `unansweredPosts` e `ranking` (as regras de pontos, os pontos por ação e por período e quantos membros estão em cada nível).

**Peça assim:** *"Quem são os 10 mais engajados do mês? E quais ações mais deram pontos?"*

## `events_report`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Relatório de eventos.** Por período: os eventos que aconteceram e as respostas recebidas. Por evento: quantos disseram vou, talvez e não vou, com o link. *Papel mínimo: moderador.*

Parâmetros: os comuns, mais `page` e `limit`.

**Devolve:** `series`, `totals` e `events`. Presença não é registrada, e o assistente diz isso se você perguntar quem compareceu.

**Peça assim:** *"Quantas pessoas confirmaram em cada evento deste semestre?"*

## `courses_report`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Relatório de cursos.** Por período: matrículas, cursos concluídos e aulas concluídas. Por curso: matrículas, concluídos, taxa de conclusão e o progresso médio dos matriculados. *Papel mínimo: moderador.*

Parâmetros: os comuns, mais `page` e `limit`.

**Devolve:** `series`, `totals` e `courses`, com o link de cada curso.

**Peça assim:** *"Qual curso tem a menor taxa de conclusão?"*

## `member_activity`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Atividade de um membro.** O que uma pessoa fez na comunidade, no período e desde sempre: posts, comentários, reações, respostas a eventos, matrículas, compras, assinaturas, cursos concluídos e certificados. Traz os pontos do ranking por ação, o nível e a posição, e os itens recentes com link. *Papel mínimo: administrador.*

Parâmetros: `member` (o id do perfil, de `list_members`, o e-mail ou o link do perfil copiado do app) e os comuns. Para a linha do tempo de tudo o que a pessoa fez, com data e hora, use [`list_activity_logs`](/mcp/ferramentas-membros#list-activity-logs).

**Devolve:** `counts`, `ranking` e `recent`. Das compras, só o valor pago e a forma de pagamento. Não há registro de navegação: o relatório mostra o que a pessoa fez, não o que ela viu.

**Peça assim:** *"O que a maria.silva@memberfy.net fez na comunidade nos últimos 3 meses?"*

## `community_overview`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Painel geral da comunidade.** Este mês até agora contra o mês passado inteiro e contra o mês passado até o mesmo dia: receita e MRR, membros novos, engajamento e os eventos dos próximos 30 dias. *Papel mínimo: moderador ou financeiro; cada um vê o bloco da sua área.*

Parâmetros: `timezone`.

**Devolve:** `money` (para proprietário, administrador e financeiro) e `community` (para proprietário, administrador e moderador).

**Peça assim:** *"Como está o mês em relação ao anterior?"*

## Receitas

### Gráfico de receita por mês por plano

**Para quem:** proprietário, administrador ou financeiro.

> Faça um gráfico de barras empilhadas da receita líquida mês a mês em 2026, uma cor por plano, e embaixo uma tabela com o total de cada plano e o ticket médio.

| # | Ferramenta | O que faz |
|---|---|---|
| 1 | `sales_report` | `interval: month`, `from: 2026-01-01`, `to: 2026-12-31`, `group_by: plan` |

**Resultado:** o gráfico e a tabela na conversa. Cada plano em `groups` já vem com a série completa, com zero nos meses sem venda. Para ver também os reembolsos, peça *"e uma linha com os reembolsos"*.

### Quem são os 10 mais engajados

**Para quem:** proprietário, administrador ou moderador.

> Quem foram os 10 membros mais engajados nos últimos 30 dias? Mostre numa tabela com posts, comentários, reações, pontos e nível, e diga quais ações mais deram pontos.

| # | Ferramenta | O que faz |
|---|---|---|
| 1 | `engagement_report` | `interval: day`, `limit: 10`, `order_by: points` |

**Resultado:** a tabela com os 10 primeiros e um resumo de `ranking.byAction`. Com o ranking desligado, peça `order_by: interactions`. Para ver o detalhe de uma pessoa da lista, siga com `member_activity`.

### Resumo da semana

**Para quem:** qualquer papel da equipe. O financeiro recebe só a parte do dinheiro; o moderador, só a da comunidade.

> Faça o resumo da semana: vendas e assinaturas novas, membros novos, quem mais participou, os posts que ficaram sem resposta e os próximos eventos com quantos confirmaram. Termine com três sugestões do que fazer.

| # | Ferramenta | O que faz |
|---|---|---|
| 1 | `community_overview` | O mês até agora, para dar contexto |
| 2 | `sales_report` | `interval: day`, os últimos 7 dias |
| 3 | `engagement_report` | `interval: day`, os últimos 7 dias, `limit: 5` |
| 4 | `events_report` | Da semana que vem em diante |

**Resultado:** o resumo na conversa. Se quiser publicar, peça *"escreva um post com isso para o Feed e me mostre antes"*: o assistente usa `create_post` depois do seu ok.

## Relacionados

- [Ferramentas](/mcp/ferramentas)
- [Receitas](/mcp/receitas)
- [Ferramentas · Financeiro](/mcp/ferramentas-financeiro)
- [Segurança e limites](/mcp/seguranca)