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 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 (monthly_credits) e create_product e update_product (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: Só consulta não muda nada, Altera cria ou muda algo na hora, e Pede confirmação só age depois do seu sim a um resumo. Ver Dinheiro e confirmação.
Em resumo
| Ferramenta | O que faz | Papel mínimo | Tipo |
|---|---|---|---|
get_credit_balance | O saldo, o que vence em 7 dias e os lotes | Qualquer (o seu); equipe (de outro) | Só consulta |
list_credit_entries | O extrato, do mais novo ao mais antigo | Qualquer (o seu); equipe (de outro) | Só consulta |
grant_credits | Abre um lote novo de créditos, com motivo | Financeiro | Pede confirmação |
adjust_credits | Soma créditos como correção, com motivo | Financeiro | Pede confirmação |
revoke_credits | Retira créditos (ajuste negativo) | Financeiro | Pede confirmação |
get_credit_settings | As regras de créditos da comunidade | Moderador (ou financeiro) | Só consulta |
update_credit_settings | Muda as regras | Administrador | Altera |
"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
Só consulta
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
Só consulta
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
Pede confirmação
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
Pede confirmação
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, que pede confirmação. Papel mínimo: financeiro.
revoke_credits
Pede confirmação
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
Só consulta
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
Altera
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."