> For the complete documentation index, see [llms.txt](https://docs.yoplanning.support/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yoplanning.support/it/developpeur/api-agent-yoplanning.md). # 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: {% embed url="" %} Riferimento completo all'API dell'agente Yoplanning {% endembed %} 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: {% hint style="danger" %} **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 se non sai come procedere. {% endhint %} * **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](/it/developpeur/se-connecter-a-yoplanning-via-mcp.md). Per informazioni complete sulle risorse e i campi dell'API Agent, il riferimento attuale rimane [Swagger](https://yoplanning.pro/api/agent/v1/swagger/). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.yoplanning.support/it/developpeur/api-agent-yoplanning.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.