# Ferramentas · Financeiro

> Ferramentas MCP para o dinheiro da comunidade: resumo de vendas, clientes, extrato, saldo, saques e a simulação da taxa, e pedir ou cancelar saques, com confirmação.

O caixa da comunidade: quanto vendeu, quem paga, o extrato, o saldo disponível, os saques, e quanto fica de uma venda. Pedir ou cancelar um saque pede o seu sim, com um resumo. Em valores, aparece só a taxa da plataforma.

Cada ferramenta traz um selo: <span class="tool-kind tool-kind-read">Só consulta</span> não muda nada, <span class="tool-kind tool-kind-write">Altera</span> cria ou muda algo na hora, e <span class="tool-kind tool-kind-confirm">Pede confirmação</span> só age depois do seu sim a um resumo. Ver [Dinheiro e confirmação](/mcp/dinheiro-e-confirmacao).

## Em resumo

| Ferramenta | O que faz | Papel mínimo | Tipo |
|---|---|---|---|
| [`get_sales_summary`](#get-sales-summary) | Receita, série mensal, receita por produto e assinantes | Administrador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`list_customers`](#list-customers) | Quem paga e quanto já pagou | Administrador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`list_ledger_entries`](#list-ledger-entries) | Lançamentos do extrato | Administrador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`get_balance`](#get-balance) | Saldo total, disponível, retido e a liberar | Administrador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`list_payouts`](#list-payouts) | Saques e status | Administrador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`simulate_fee`](#simulate-fee) | Quanto a comunidade recebe de uma venda | Administrador | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`request_payout`](#request-payout) | Pede um saque, com confirmação | Administrador | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`cancel_payout`](#cancel-payout) | Cancela um saque pendente, com confirmação | Administrador | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |

## `get_sales_summary`

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

**Resumo de vendas.** A receita e os assinantes de um período. *Papel mínimo: administrador ou financeiro.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `period` | `7d`, `30d`, `90d`, `1y`, `custom` | Não | O período |
| `start_date` | data ISO 8601 | Não | Com `period: custom` |
| `end_date` | data ISO 8601 | Não | Com `period: custom` |

**Devolve:** a receita do período, a série mês a mês, a receita por produto e os assinantes ativos, em atraso e cancelados. Em valores, só aparece a taxa da plataforma.

**Peça assim:** *"Faça um gráfico da receita dos últimos 12 meses."* · *"Qual produto mais vendeu no trimestre?"*

## `list_customers`

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

**Quem paga e quanto já pagou.** Os clientes pagantes e o total pago por cada um. *Papel mínimo: administrador ou financeiro.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `page`, `limit` | número | Não | Paginação |

**Devolve:** os clientes, com nome, e-mail e total pago.

**Peça assim:** *"Quem são os 10 clientes que mais pagaram?"*

## `list_ledger_entries`

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

**Extrato.** Os lançamentos do extrato, mais novos primeiro. *Papel mínimo: administrador ou financeiro.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `entry_type` | texto | Não | Um tipo de lançamento: `SALE_GROSS`, `SALE_NET`, `PLATFORM_FEE`, `INSTALLMENT_INTEREST`, `REFUND`, `CHARGEBACK`, `PAYOUT_REQUESTED`… |
| `page`, `limit` | número | Não | Paginação |

**Devolve:** os lançamentos, com data, tipo, descrição e valor. Ver [Saldo e extrato](/pagamentos/saldo-e-extrato).

**Peça assim:** *"Quais foram os reembolsos deste mês?"*

## `get_balance`

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

**Saldo.** O saldo da comunidade. *Papel mínimo: administrador ou financeiro.*

Parâmetros: nenhum.

**Devolve:** o saldo total, o disponível para saque, o retido e o que ainda vai ser liberado.

**Peça assim:** *"Quanto posso sacar hoje?"*

## `list_payouts`

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

**Saques.** Os saques pedidos, com status. *Papel mínimo: administrador ou financeiro.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `status` | `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `CANCELED` | Não | Só um status |
| `page`, `limit` | número | Não | Paginação |

**Devolve:** os saques, com id (que `cancel_payout` pede), valor, taxa, status e datas.

**Peça assim:** *"Algum saque falhou?"*

## `simulate_fee`

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

**Quanto recebo de uma venda.** Simula uma venda: o valor, a taxa da plataforma e o que a comunidade recebe. *Papel mínimo: administrador.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `amount` | número | Sim | O valor da venda, em reais |
| `payment_method` | `PIX`, `CREDIT_CARD`, `BOLETO` | Não | O método de pagamento |
| `installments` | número | Não | Número de parcelas no cartão |

**Devolve:** o valor, a taxa da plataforma (que independe do método de pagamento) e o líquido. Ver [Taxa da plataforma](/pagamentos/taxa-da-plataforma).

**Peça assim:** *"Se eu vender um curso de R$ 297, quanto fica para a comunidade?"*

## `request_payout`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Pedir saque.** Pede um saque do saldo disponível para a conta bancária cadastrada. *Papel mínimo: administrador; o financeiro só lê.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `amount` | número, em reais | Sim | Até o disponível (veja com `get_balance`) |

**O resumo:** a ação, o valor e o saldo atual.

**Peça assim:** *"Quanto tenho disponível? Saque R$ 2.000."*

**Notas:** a taxa de R$ 3,67 por saque e as regras são as do painel. Ver [Saque](/pagamentos/saque).

## `cancel_payout`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Cancelar saque.** Cancela um saque que ainda está pendente. *Papel mínimo: administrador.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `payout_id` | id | Sim | De `list_payouts` |

**O resumo:** a ação, o valor, o status e a data do pedido.

**Peça assim:** *"Cancele o saque de R$ 2.000 que pedi hoje."*

## O que não existe

Não há ferramenta de **reembolso**: continua no painel. Ver [Problemas comuns](/mcp/problemas-comuns#o-que-ainda-nao-da-para-fazer).

## Relacionados

- [Ferramentas](/mcp/ferramentas)
- [Receitas](/mcp/receitas)
- [Dinheiro e confirmação](/mcp/dinheiro-e-confirmacao)