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 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 (monthly_credits) e create_product e update_product (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: Solo lettura non cambia nulla, Modifica crea o cambia qualcosa subito, e Chiede conferma agisce solo dopo il tuo sì a un riepilogo. Vedi Denaro e conferma.
In sintesi
| Strumento | Cosa fa | Ruolo minimo | Tipo |
|---|---|---|---|
get_credit_balance | Il saldo, ciò che scade entro 7 giorni e i lotti | Qualsiasi (il tuo); team (di altri) | Solo lettura |
list_credit_entries | L'estratto, dal più recente al più vecchio | Qualsiasi (il tuo); team (di altri) | Solo lettura |
grant_credits | Apre un nuovo lotto di crediti, con motivo | Finanza | Chiede conferma |
adjust_credits | Aggiunge crediti come correzione, con motivo | Finanza | Chiede conferma |
revoke_credits | Toglie crediti (rettifica negativa) | Finanza | Chiede conferma |
get_credit_settings | Le regole dei crediti della community | Moderatore (o finanza) | Solo lettura |
update_credit_settings | Cambia le regole | Amministratore | Modifica |
"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
Solo lettura
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
Solo lettura
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
Chiede conferma
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
Chiede conferma
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, che chiede conferma. Ruolo minimo: finanza.
revoke_credits
Chiede conferma
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
Solo lettura
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
Modifica
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."