# Strumenti · Crediti

> Gli strumenti MCP dei crediti di prenotazione: saldo, estratto, assegnare, rettificare e togliere crediti, e le regole della community (accumulo, finestra di annullamento, annullamento tardivo e assenza). Ruolo minimo e ricette.

I [crediti](/monetizacao/creditos) tramite l'assistente: vedere il saldo e l'estratto (il tuo o, per il team, quello di qualsiasi membro), assegnare e rettificare crediti, toglierli e leggere o cambiare le regole della community. I crediti dei piani e dei prodotti si definiscono con [`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`); in una community senza uno spazio di Prenotazioni o di Appuntamenti, l'assistente spiega che bisogna crearne uno prima.

Ogni strumento ha un'etichetta: <span class="tool-kind tool-kind-read">Solo lettura</span> non cambia nulla, <span class="tool-kind tool-kind-write">Modifica</span> crea o cambia qualcosa subito, e <span class="tool-kind tool-kind-confirm">Chiede conferma</span> agisce solo dopo il tuo sì a un riepilogo. Vedi [Denaro e conferma](/mcp/dinheiro-e-confirmacao).

## In sintesi

| Strumento | Cosa fa | Ruolo minimo | Tipo |
|---|---|---|---|
| [`get_credit_balance`](#get-credit-balance) | Il saldo, ciò che scade entro 7 giorni e i lotti | Qualsiasi (il tuo); team (di altri) | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`list_credit_entries`](#list-credit-entries) | L'estratto, dal più recente al più vecchio | Qualsiasi (il tuo); team (di altri) | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`grant_credits`](#grant-credits) | Apre un nuovo lotto di crediti, con motivo | Finanza | <span class="tool-kind tool-kind-confirm">Chiede conferma</span> |
| [`adjust_credits`](#adjust-credits) | Aggiunge crediti come correzione, con motivo | Finanza | <span class="tool-kind tool-kind-confirm">Chiede conferma</span> |
| [`revoke_credits`](#revoke-credits) | Toglie crediti (rettifica negativa) | Finanza | <span class="tool-kind tool-kind-confirm">Chiede conferma</span> |
| [`get_credit_settings`](#get-credit-settings) | Le regole dei crediti della community | Moderatore (o finanza) | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`update_credit_settings`](#update-credit-settings) | Cambia le regole | Amministratore | <span class="tool-kind tool-kind-write">Modifica</span> |

"Finanza" qui significa **proprietario, amministratore o finanza**; il **moderatore legge soltanto**. "Team" è il proprietario, l'amministratore, il moderatore e la finanza. I ruoli sono quelli delle rotte: l'assistente non fa mai più di quanto la persona collegata farebbe sullo schermo. La variabile della piattaforma che decide se un abbonamento in pausa o insolvente continua a usare il saldo è del SuperAdmin e non ha strumento.

## `get_credit_balance`

<span class="tool-kind tool-kind-read">Solo lettura</span>

**Il saldo.** Il saldo utilizzabile (la somma dei lotti non scaduti; può essere negativo, il che blocca le prenotazioni), ciò che scade nei prossimi 7 giorni e i lotti, ciascuno con l'origine (**Piano**, **Prodotto** o **Team**), quanto resta e quando scade. *Ruolo minimo: qualsiasi (il tuo); il team legge quello di qualsiasi membro.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `profile_id` | id | No | Solo il team: di chi. Senza, è il tuo (un membro che chiede quello di un altro viene rifiutato) |

**Chiedi così:** *"Quanti crediti ho?"* · *"Qual è il saldo di Maria Rossi?"*

## `list_credit_entries`

<span class="tool-kind tool-kind-read">Solo lettura</span>

**L'estratto.** Ogni movimento con il tipo (assegnazione, uso in una prenotazione, rimborso, rettifica, scadenza, revoca), l'importo con il segno, l'origine, la prenotazione, il prodotto o l'abbonamento dietro e il motivo. Il registro cresce soltanto: nulla viene modificato né cancellato. Paginato.

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `profile_id` | id | No | Solo il team: di chi. Senza, è il tuo |
| `kind` | `GRANT`, `DEBIT`, `REFUND`, `ADJUSTMENT`, `EXPIRATION` o `REVOCATION` | No | Filtra per tipo |
| `page`, `limit` | numero | No | Paginazione (`limit` fino a 200) |

**Chiedi così:** *"Mostrami l'estratto dei crediti di Maria di questo mese."*

## `grant_credits`

<span class="tool-kind tool-kind-confirm">Chiede conferma</span>

**Assegnare crediti.** Apre un **nuovo lotto** con **motivo obbligatorio** e validità facoltativa (senza, non scadono). Prima di agire, mostra un riepilogo e ripete la chiamata solo dopo il tuo sì. Restituisce il nuovo saldo e il movimento. *Ruolo minimo: finanza.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `profile_id` | id | Sì | Il membro (`list_members`) |
| `amount` | intero, da 1 a 100.000 | Sì | Quanti crediti |
| `reason` | testo (fino a 255) | Sì | Il motivo: resta nell'estratto |
| `expires_at` | data e ora future | No | Quando scadono; senza o `null`, mai |

**Chiedi così:** *"Dai 10 crediti omaggio a Giovanni, validi fino alla fine del mese, perché ha presentato un nuovo membro."*

## `adjust_credits`

<span class="tool-kind tool-kind-confirm">Chiede conferma</span>

**Rettificare in aumento.** Aggiunge crediti come **correzione** (un movimento di rettifica: è il modo di sistemare un errore, dato che il registro non modifica mai). Stessi parametri di `grant_credits` (fino a 100.000 per volta), e chiede anche conferma. Per togliere crediti, usa [`revoke_credits`](#revoke-credits), che chiede conferma. *Ruolo minimo: finanza.*

## `revoke_credits`

<span class="tool-kind tool-kind-confirm">Chiede conferma</span>

**Togliere crediti.** Una rettifica negativa, con motivo obbligatorio. Consuma **prima i lotti che scadono prima** e **non supera il saldo utilizzabile** (altrimenti `409`: leggi prima il saldo). Prima di agire, mostra un riepilogo (quanto, il saldo attuale, il saldo dopo e il motivo) e ripete la chiamata con il `confirmation_token` solo dopo un sì esplicito. *Ruolo minimo: finanza.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `profile_id` | id | Sì | Il membro |
| `amount` | intero, 1 o più | Sì | Quanti crediti togliere |
| `reason` | testo | Sì | Il motivo |

## `get_credit_settings`

<span class="tool-kind tool-kind-read">Solo lettura</span>

**Le regole.** Accumulo (attivo, tetto, mesi), quota proporzionale del primo mese, finestra di annullamento in ore, se l'annullamento tardivo e l'assenza perdono il credito e i giorni di avviso prima della scadenza. *Ruolo minimo: moderatore (o finanza).*

## `update_credit_settings`

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

**Cambiare le regole.** Cambia solo ciò che invii. Vale dal prossimo cambio di mese in poi e non modifica mai un lotto già esistente. *Ruolo minimo: amministratore.*

| Parametro | Tipo | Descrizione |
|---|---|---|
| `rollover_enabled` | vero o falso | Riportare il credito del piano al mese successivo (predefinito: no) |
| `rollover_cap` | intero o `null` | Il tetto di ciò che passa; `null`, nessun tetto |
| `rollover_max_cycles` | da 1 a 12 | Per quanti mesi l'accumulato resta valido |
| `prorate_first_month` | vero o falso | Quota proporzionale ai giorni restanti nel primo mese |
| `change_window_hours` | da 0 a 720 | Finestra per annullare o modificare senza perdere (predefinito: 24) |
| `late_cancel_loses_credits` | vero o falso | L'annullamento tardivo perde il credito (predefinito: sì) |
| `no_show_loses_credits` | vero o falso | L'assenza perde il credito (predefinito: sì) |
| `expiry_notice_days` | da 0 a 30 | Giorni di avviso prima della scadenza (0 = nessun avviso) |

**Chiedi così:** *"Attiva l'accumulo dei crediti, con tetto di 20, per 2 mesi, e porta la finestra di annullamento a 12 ore."*

## Correlati

- [Crediti](/monetizacao/creditos)
- [Strumenti · Prenotazioni e Appuntamenti](/mcp/ferramentas-reservas)
- [Strumenti](/mcp/ferramentas)
- [Denaro e conferma](/mcp/dinheiro-e-confirmacao)
- [Ricette](/mcp/receitas)