API dell'agente Yoplanning
Yoplanning offre un'API Agente che consente di controllare Yoplanning a livello programmatico, o tramite un assistente IA, esattamente come se si utilizzasse l'interfaccia web. La documentazione tecnica completa (tutti gli endpoint, tutti i campi) è disponibile in Swagger:
Questo articolo non sostituisce il riferimento tecnico: spiega il principio generale, a cosa serve questa API e soprattutto le precauzioni da adottare prima di collegarla a qualsiasi cosa.
Metodologia
L'API dell'agente segue alcuni principi semplici, ma è bene tenerli a mente prima di utilizzarla:
Questo è un collegamento diretto al codice interno di Yoplanning — lo stesso codice richiamato dall'interfaccia web. Scrivere tramite API ha esattamente lo stesso comportamento, le stesse convalide e gli stessi effetti collaterali di un'azione manuale all'interno di Yoplanning. Non c'è alcuna logica nascosta: ciò che l'interfaccia consente, lo consente anche l'API; ciò che l'interfaccia rifiuta, lo rifiuta anche l'API, con lo stesso errore.
Tutto è limitato al team. Quasi tutti gli indirizzi iniziano con l'ID del tuo team (
/teams/{teamId}/…), e un token dà accesso solo al team per cui è stato creato.La regola del "viaggio di andata e ritorno" per qualsiasi modifica: L'oggetto esistente viene recuperato, i campi desiderati vengono modificati e quindi l'intero oggetto viene inviato nuovamente. Un aggiornamento non è una correzione parziale: qualsiasi campo mancante nell'invio viene reimpostato. Questa è una fonte comune di errore se non viene prevista.
Autenticazione tramite token, specifica per utente e team, trasmessa in ogni richiesta tramite l'intestazione
Authorization.
A cosa serve?
L'API Agent ti permette di creare, configurare, modificare o eliminare praticamente qualsiasi elemento gestito da Yoplanning: clienti, prodotti, sessioni, ordini, pagamenti, personale, codici promozionali, motore di prenotazione, rivenditori, ecc. — con gli stessi diritti della persona a cui appartiene il token.
In pratica, viene utilizzato per connettere Yoplanning a un sistema esterno (sito web, strumento interno, altro software aziendale) o a un assistente IA al quale si desidera delegare attività di configurazione o gestione in linguaggio naturale, anziché eseguire tutto manualmente nell'interfaccia.
Rischi da tenere presenti prima di connettere uno strumento a questa API
Questa non è un'API di sola lettura: fornisce un accesso con le stesse funzionalità di un utente Yoplanning autenticato. Prima di collegarla a uno strumento, uno script o un assistente AI, tieni presente questi punti:
Il token contiene dati strettamente riservati, proprio come una password. Qualsiasi persona o programma in suo possesso può agire sul tuo team esattamente come puoi fare tu: creare, modificare, eliminare.
Non incollarlo mai in un repository di codice (nemmeno privato), in un messaggio non crittografato, in un'e-mail, in uno screenshot o in uno strumento di cui non ti fidi completamente. Se viene divulgato, consideralo compromesso: generane immediatamente uno nuovo dalle tue preferenze avanzate oppure contatta support@yoplanning.com se non sai come procedere.
Gli effetti collaterali sono reali. Uno script può inviare un'e-mail di conferma, registrare un pagamento, inviare un invito o eliminare dati in modo reale, una sola volta, proprio come farebbe l'interfaccia. Uno script o un agente mal progettato può quindi innescare azioni concrete da parte dei clienti o del team, non limitandosi a modificare i dati internamente.
Un aggiornamento sostituisce l'intero oggetto. Se lo strumento a cui ti connetti non rilegge l'oggetto prima di inviarlo modificato, potrebbe eliminare involontariamente dei campi anziché lasciarli invariati.
Il token detiene i diritti della persona che lo ha creato. Se colleghi un assistente AI a questa API, esso sarà in grado di fare – e annullare – tutto ciò che quella persona può fare in questo team. Definisci chiaramente cosa gli chiedi di fare, soprattutto per qualsiasi azione irreversibile (eliminazione, invio di email o SMS, elaborazione di pagamenti) e dai la priorità a un token creato specificamente per questo scopo piuttosto che al tuo token personale principale, se lo strumento lo consente.
Per andare oltre
Per un'integrazione AI più leggera e di sola lettura, limitata dalle tue autorizzazioni, consulta anche l'articolo Connessione a Yoplanning tramite MCP. Per informazioni complete sulle risorse e i campi dell'API Agent, il riferimento attuale rimane Swagger.
Ultimo aggiornamento