# Ferramentas · Créditos

> Ferramentas MCP dos créditos de reserva: saldo, extrato, conceder, ajustar e retirar créditos, e as regras da comunidade (acúmulo, janela de cancelamento, cancelamento tardio e ausência). Papel mínimo e receitas.

Os [créditos](/monetizacao/creditos) pelo assistente: ver o saldo e o extrato (o seu ou o de qualquer membro, para a equipe), conceder e ajustar créditos, retirá-los e ler ou mudar as regras da comunidade. Os créditos dos planos e dos produtos se definem com [`create_plan` e `update_plan`](/mcp/ferramentas-vendas) (`monthly_credits`) e [`create_product` e `update_product`](/mcp/ferramentas-vendas) (`granted_credits` e `granted_credits_validity_days`); numa comunidade sem espaço de Reservas ou de Agendamento, o assistente explica que é preciso criar um primeiro.

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_credit_balance`](#get-credit-balance) | O saldo, o que vence em 7 dias e os lotes | Qualquer (o seu); equipe (de outro) | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`list_credit_entries`](#list-credit-entries) | O extrato, do mais novo ao mais antigo | Qualquer (o seu); equipe (de outro) | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`grant_credits`](#grant-credits) | Abre um lote novo de créditos, com motivo | Financeiro | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`adjust_credits`](#adjust-credits) | Soma créditos como correção, com motivo | Financeiro | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`revoke_credits`](#revoke-credits) | Retira créditos (ajuste negativo) | Financeiro | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`get_credit_settings`](#get-credit-settings) | As regras de créditos da comunidade | Moderador (ou financeiro) | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`update_credit_settings`](#update-credit-settings) | Muda as regras | Administrador | <span class="tool-kind tool-kind-write">Altera</span> |

"Financeiro" aqui significa **proprietário, administrador ou financeiro**; o **moderador só lê**. "Equipe" é o proprietário, o administrador, o moderador e o financeiro. Os papéis são os das rotas: o assistente nunca faz mais do que a pessoa conectada faria na tela. A variável da plataforma que decide se uma assinatura pausada ou inadimplente continua usando o saldo é do SuperAdmin e não tem ferramenta.

## `get_credit_balance`

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

**O saldo.** O saldo utilizável (a soma dos lotes que não venceram; pode ser negativo, o que bloqueia reservar), o que vence nos próximos 7 dias e os lotes, cada um com a origem (**Plano**, **Produto** ou **Equipe**), quanto resta e quando vence. *Papel mínimo: qualquer (o seu); a equipe lê o de qualquer membro.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `profile_id` | id | Não | Só a equipe: de quem. Sem ele, é o seu (um membro pedindo o de outro é recusado) |

**Peça assim:** *"Quantos créditos eu tenho?"* · *"Qual o saldo da Maria Souza?"*

## `list_credit_entries`

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

**O extrato.** Cada lançamento com o tipo (concessão, uso em reserva, estorno, ajuste, expiração, revogação), o valor com sinal, a origem, a reserva, o produto ou a assinatura por trás e o motivo. O livro só cresce: nada é editado nem apagado. Paginado.

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `profile_id` | id | Não | Só a equipe: de quem. Sem ele, é o seu |
| `kind` | `GRANT`, `DEBIT`, `REFUND`, `ADJUSTMENT`, `EXPIRATION` ou `REVOCATION` | Não | Filtra por tipo |
| `page`, `limit` | número | Não | Paginação (`limit` até 200) |

**Peça assim:** *"Mostre o extrato de créditos da Maria deste mês."*

## `grant_credits`

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

**Conceder créditos.** Abre um **lote novo** com **motivo obrigatório** e validade opcional (sem ela, não vencem). Antes de agir, mostra um resumo e só repete a chamada depois do seu sim. Devolve o novo saldo e o lançamento. *Papel mínimo: financeiro.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `profile_id` | id | Sim | O membro (`list_members`) |
| `amount` | inteiro, de 1 a 100.000 | Sim | Quantos créditos |
| `reason` | texto (até 255) | Sim | O motivo: fica no extrato |
| `expires_at` | data e hora no futuro | Não | Quando vencem; sem ela ou `null`, nunca |

**Peça assim:** *"Dê 10 créditos de cortesia ao João, válidos até o fim do mês, porque indicou um membro novo."*

## `adjust_credits`

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

**Ajustar para mais.** Soma créditos como **correção** (um lançamento de ajuste: é o modo de consertar um erro, já que o livro nunca edita). Mesmos parâmetros de `grant_credits` (até 100.000 por vez), e também pede confirmação. Para tirar créditos, use [`revoke_credits`](#revoke-credits), que pede confirmação. *Papel mínimo: financeiro.*

## `revoke_credits`

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

**Retirar créditos.** Um ajuste negativo, com motivo obrigatório. Consome **primeiro os lotes que vencem antes** e **não passa do saldo utilizável** (senão, `409`: leia o saldo antes). Antes de agir, mostra um resumo (quanto, o saldo agora, o saldo depois e o motivo) e só repete a chamada com o `confirmation_token` depois de um sim explícito. *Papel mínimo: financeiro.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `profile_id` | id | Sim | O membro |
| `amount` | inteiro, 1 ou mais | Sim | Quantos créditos remover |
| `reason` | texto | Sim | O motivo |

## `get_credit_settings`

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

**As regras.** Acúmulo (ligado, teto, meses), proporcional do primeiro mês, janela de cancelamento em horas, se o cancelamento tardio e a ausência perdem o crédito e os dias de aviso de vencimento. *Papel mínimo: moderador (ou financeiro).*

## `update_credit_settings`

<span class="tool-kind tool-kind-write">Altera</span>

**Mudar as regras.** Muda só o que você mandar. Vale da próxima virada do mês em diante e nunca altera um lote que já existe. *Papel mínimo: administrador.*

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `rollover_enabled` | verdadeiro ou falso | Acumular o crédito do plano para o mês seguinte (padrão: não) |
| `rollover_cap` | inteiro ou `null` | O teto do que passa; `null`, sem teto |
| `rollover_max_cycles` | 1 a 12 | Por quantos meses o acumulado vale |
| `prorate_first_month` | verdadeiro ou falso | Proporcional aos dias restantes no primeiro mês |
| `change_window_hours` | 0 a 720 | Janela para cancelar ou alterar sem perder (padrão: 24) |
| `late_cancel_loses_credits` | verdadeiro ou falso | Cancelamento tardio perde o crédito (padrão: sim) |
| `no_show_loses_credits` | verdadeiro ou falso | Ausência perde o crédito (padrão: sim) |
| `expiry_notice_days` | 0 a 30 | Dias de aviso antes de vencer (0 = não avisa) |

**Peça assim:** *"Ligue o acúmulo de créditos, com teto de 20, por 2 meses, e deixe a janela de cancelamento em 12 horas."*

## Relacionados

- [Créditos](/monetizacao/creditos)
- [Ferramentas · Reservas e Agendamento](/mcp/ferramentas-reservas)
- [Ferramentas](/mcp/ferramentas)
- [Dinheiro e confirmação](/mcp/dinheiro-e-confirmacao)
- [Receitas](/mcp/receitas)