> 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-octo-yoplanning-workflow-de-vente-standard.md). # API OCTO Yoplanning - Workflow de vente standard ### Presentazione Yoplanning offre un'implementazione dell'API OCTO per consentire la rivendita di attività tra team. Questa documentazione presenta il flusso di lavoro standard per vendite, annullamenti e notifiche webhook. Questa implementazione è conforme agli standard OCTO Travel. [Certificazione ufficiale OCTO](https://certify.octo.travel/verify/5065485c-5142-4814-91b7-1dd63777a741) Documentazione ufficiale di OCTO: *** ### Prerequisiti Prima di utilizzare l'API OCTO Yoplanning, è necessario che in Yoplanning siano presenti le seguenti configurazioni: * Un team di rivendita (`teamId`) * Un team di fornitori (`providerId`) * Un token API di tipo `run user` creato nel team di rivendita * Il fornitore deve: * avendo aggiunto il rivenditore al suo team * dopo aver configurato i prodotti disponibili per la rivendita *** ### URL di base ``` https://yoplanning.pro/api/octo/teams//providers// ``` #### Variabili | Variabile | Descrizione | | -------------- | --------------------------- | | `` | ID del team del rivenditore | | `` | ID del team del fornitore | *** ### Autenticazione L'autenticazione funziona come nell'API Yoplanning v3.1. È possibile utilizzare: #### Token di autorizzazione dell'intestazione ```http Authorization: Token XXXX ``` #### Intestazione di autorizzazione Bearer ```http Authorization: Bearer XXXX ``` *** ### Capacità utilizzate Tutte le richieste utilizzano le seguenti funzionalità: ```http Octo-Capabilities: pricing,content ``` Queste funzionalità consentono di recuperare: * informazioni sui prezzi * contenuti di marketing del prodotto * dati descrittivi sulla disponibilità *** ### Flusso di lavoro standard supportato Il flusso di lavoro standard supportato da Yoplanning è il seguente: ``` /products ↓ /availability/calendar (optionnel) ↓ /availability ↓ /booking ↓ /confirm ``` Flusso di lavoro di cancellazione: ``` /cancel ``` Flusso di notifica: ``` /notifications/subscriptions ``` *** ### 1. Recupera i prodotti Punto finale: ```http GET /products ``` Questo endpoint consente di recuperare i prodotti disponibili per la vendita. #### Utilizzo Il rivenditore utilizza questo percorso per: * visualizzare il catalogo dei fornitori * recuperare le opzioni * recuperare le unità tariffarie * visualizzazione di contenuti di marketing *** ### 2. Visualizzare un calendario di disponibilità (facoltativo) Punto finale: ```http POST /availability/calendar ``` Questo passaggio è facoltativo. Consente di visualizzare: * date disponibili * prezzi “a partire da” * un calendario delle prenotazioni #### migliori prassi Utilizza questo percorso per: * visualizzare un calendario mensile * Disponibilità di precarico * migliorare le prestazioni del front-end *** ### 3. Verifica la disponibilità Punto finale: ```http POST /availability ``` Questo passaggio è obbligatorio. Consente di recuperare: * le fasce orarie disponibili * gli orari * le capacità * i prezzi esatti * l'`availabilityId` Il campo `availabilityId` è necessario per creare una prenotazione. #### Raccomandazione importante Il modo migliore è trasmettere le "unità" (numero di partecipanti). Ciò consente: * per ottenere il prezzo migliore * per recuperare la buona disponibilità * per calcolare correttamente le capacità *** ### 4. Posti riservati Punto finale: ```http POST /booking ``` Questo percorso crea una prenotazione temporanea. L'ordine viene creato con il seguente stato: ``` ON_HOLD ``` Lo stato `ON_HOLD` significa: * I posti sono bloccati. * La prenotazione non è ancora confermata. * L'ordine scade automaticamente dopo 30 minuti se non viene confermato. #### Importante In questa fase: * la prenotazione esiste già * Gli spazi sono sicuri. * Il pagamento può essere finalizzato dal rivenditore. *** ### 5. Conferma l'ordine Punto finale: ```http POST /confirm ``` Questo passaggio finalizza la prenotazione. Una volta confermato: * l'ordine diventa definitivo * È possibile generare biglietti * La prenotazione è completa. #### Importante La conferma è semplice: * Conferma soltanto l'ordine esistente * Non è possibile modificare il contenuto dell'ordine in questa fase *** ### 6. Annullare un ordine Punto finale: ```http POST /cancel ``` Questa procedura consente di cancellare una prenotazione. #### Importante Se la prenotazione è già confermata, assicurati di rispettare la politica di cancellazione del fornitore. Secondo le regole del fornitore: * Potrebbero essere applicate delle commissioni * La cancellazione potrebbe essere vietata * possono sussistere condizioni specifiche Il rivenditore deve verificare le condizioni di cancellazione prima di proporre l'azione al cliente finale. *** ### Prolungare la prenotazione (facoltativo) Punto finale: ```http POST /extend ``` Questo percorso consente di estendere la durata dello stato `ON_HOLD`. Esempio : * pagamento in sospeso * Validazione del cliente in corso * Tempo aggiuntivo necessario La prenotazione deve essere ancora valida al momento della chiamata. *** ### Notifiche Webhook Punto finale: ```http POST /notifications/subscriptions ``` Questo percorso consente di registrarsi ai webhook di OCTO. I webhook ti permettono di ricevere notifiche su: * i prodotti * disponibilità * prenotazioni #### Funzionamento I dati completi dell'oggetto non vengono inviati direttamente al webhook. Il webhook contiene le informazioni necessarie per richiamare gli endpoint pertinenti e recuperare gli aggiornamenti. #### migliori prassi Dopo aver ricevuto un webhook: * richiamare l'endpoint in questione * ricarica i dati più recenti * Non utilizzare il webhook come unica fonte di dati. *** ### Gestione delle scadenze delle prenotazioni Una prenotazione non confermata viene automaticamente cancellata alla scadenza. Per impostazione predefinita: ``` 30 minutes ``` Il rivenditore deve pertanto: * conferma rapida degli ordini * gestire correttamente le scadenze di pagamento * utilizzare `/extend` se necessario *** ### migliori prassi #### Utilizzare sempre `/availability` Anche se utilizzi `/availability/calendar`, devi comunque chiamare: ```http /availability ``` prima di `/booking`. Questo percorso fornisce l'`availabilityId` necessario per la prenotazione. #### Invia le unità tariffarie Trasmettere sempre le unità (`unità` / partecipanti). Ciò migliora: * calcolo della tariffa * disponibilità * le regole di capacità #### Gestire l'espirazione sul lato anteriore Visualizza un timer quando il comando è in stato `ON_HOLD`. #### Ricarica i dati dopo il webhook I webhook vengono utilizzati esclusivamente per le notifiche. Ricarica sempre i dati tramite gli endpoint API pertinenti. *** ### Documentazione ufficiale dell'OCTO I dettagli completi degli endpoint e dell'architettura OCTO sono disponibili qui: --- # 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: ``` GET https://docs.yoplanning.support/it/developpeur/api-octo-yoplanning-workflow-de-vente-standard.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.