Aggiornamenti in tempo reale della struttura

Casi d'uso per gli aggiornamenti in tempo reale

Gli aggiornamenti in tempo reale devono sempre essere emessi nei seguenti scenari:

  • Quando un utente annulla una prenotazione nel tuo sistema e lo slot diventa disponibile.
  • Quando un utente prenota una prenotazione tramite il Centro azioni e lo slot di disponibilità non è più disponibile.
  • Quando una prenotazione effettuata tramite il Centro azioni viene annullata dalla tua parte, ad esempio direttamente dal commerciante. Dovrai aggiornare la prenotazione e la disponibilità perché lo slot originale è di nuovo disponibile.

Inoltre, se implementi Availability Replace RTU, gli aggiornamenti in tempo reale devono essere emessi nei seguenti scenari:

  • Quando un commerciante modifica il proprio programma (disponibilità) nel tuo sistema.
  • Quando un utente prenota una prenotazione nel tuo sistema e lo slot di disponibilità non è più disponibile.
  • Se utilizzi un'integrazione precedente con CheckAvailability, quando un server di prenotazione CheckAvailability la chiamata restituisce un inventario che non corrisponde all'inventario effettivo.

Non tutte le chiamate API Maps Booking sono obbligatorie. Sono obbligatori:

A seconda del tipo di integrazione, potrebbero essere disponibili o richiesti anche i seguenti elementi:

Aggiornare i Termini di utilizzo di Prenotazioni

Nel caso in cui sia stato apportato un aggiornamento a una prenotazione di Actions Center (ad es. annullata o modificata) sul tuo sistema, deve essere inviato un notification.partners.bookings.patch (BookingNotification.UpdateBooking).

Campi modificabili

  • status
  • startTime
  • duration
  • partySize
  • paymentInformation.prepaymentStatus

Esempio di annullamento

Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status

Body:
{
  "name": "partners/<PARTNER_ID>/bookings/<BOOKING_ID>",
  "merchantId": "10001",
  "serviceId": "1001",
  "startTime": "2025-01-02T15:01:23.045123456Z",
  "duration": "3000s",
  "status": "CANCELED"
}

Availability Replace RTU

Sono disponibili due tipi di metodi di sostituzione per aggiornare la tua disponibilità:

  • Sostituzione batch (InventoryUpdate.BatchServiceAvailability): Sostituisce completamente i dati di disponibilità per più commercianti e servizi.
    • Nota: questa chiamata batch non garantisce l'atomicità. Verranno restituiti solo gli slot di disponibilità aggiornati correttamente.
  • Sostituzione singola (InventoryUpdate.ReplaceServiceAvailability): Sostituisce completamente la disponibilità per un singolo commerciante e servizio.

Per maggiori dettagli, consulta il seguente riferimento.

Gli aggiornamenti in tempo reale devono utilizzare la stessa struttura di disponibilità dei dati inviati tramite i feed. Devono utilizzare uno dei seguenti metodi:

  • spotsOpen
  • recurrence

Scegliere un metodo di sostituzione da chiamare

Utilizza la seguente guida per determinare il metodo di sostituzione più adatto:

  • Sono interessati più commercianti? Ad esempio, sostituisci la disponibilità per più commercianti in un'unica richiesta.
  • Il sistema si sincronizzerà di tanto in tanto con Google inviando tutte le modifiche alla disponibilità dall'ultimo aggiornamento (non consigliato).
    • Sostituzione batch
    • Nota: prevediamo che l'RTU dell'inventario venga inviata entro 5 minuti dall'aggiornamento da parte tua. Pertanto, devi controllare e inviare gli aggiornamenti almeno ogni 5 minuti.
  • Nessuno di questi si applica o devi aggiornare un solo commerciante e servizio?
    • Sostituzione singola
    • Nota: puoi utilizzare più chiamate di sostituzione singola per emulare una chiamata di sostituzione batch, ma sarebbe più efficiente utilizzare una singola chiamata di sostituzione batch

Aggiornamenti in tempo reale: formato aperto per gli spot

È importante utilizzare lo stesso formato per tutti i feed, il server di prenotazione e gli aggiornamenti in tempo reale.

Uno snippet feed spots_open ha il seguente aspetto:

Snippet del feed

   "availability": [
          {
            "merchant_id": "1001",
            "service_id": "12310",
            "spots_open": 2,
            "spots_total": 2,
            "start_sec": 1735831800, # January 02, 2025 15:30:00
            "duration_sec": 1800,
            "availabilityTag": "1000001"
          }
    ]

Per l'API Inventory Update, il formato del corpo della richiesta di sostituzione quando viene prenotato uno slot delle 15:30:

Sostituisci lo snippet Aggiornamenti in tempo reale

  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2025-01-02T15:01:23.045123456Z",
        "endTimeRestrict": "2025-01-02T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2025-01-02T15:30:00.00Z",
            "duration": "3600s",
            "spotsOpen": "1",
            "spotsTotal": "2",
            "availabilityTag": "1000001"
          }
        ]
      }
    ]
  }

Ecco un esempio di ciò che ci aspettiamo nel feed giornaliero successivo, se viene prenotato un nuovo slot alle 15:30:

Snippet del feed

"availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 2,
          "start_sec": 1735831800, # January 02, 2025 15:30:00
          "duration_sec": 1800,
          "availabilityTag": "1000001"
        }
      ]

Aggiornamenti in tempo reale: formato della ricorrenza

È importante utilizzare lo stesso formato per tutti i feed, il server di prenotazione e gli aggiornamenti in tempo reale.

Un feed che utilizza la ricorrenza ha il seguente aspetto:

Snippet del feed

  "availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 1,
          "start_sec": 1540890000, # October 30, 2018 9:00:00 AM
          "duration_sec": 1800,
          "recurrence": {
            "repeat_every_sec": 1800,
            "repeat_until_sec": 1540918800 # October 30, 2018 5:00:00 PM
          },
          "schedule_exception": [
            {
              "time_range": {
                "begin_sec": 1540902600, # October 30, 2018 12:30:00 PM
                "end_sec": 1540904400 # October 30, 2018 1:00:00 PM
              }
            }
          ],
        }
      ]

Per l'API Inventory Update, il formato del corpo della richiesta di sostituzione quando viene prenotato uno slot delle 15:30 è il seguente:

  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2018-10-30T15:01:23.045123456Z",
        "endTimeRestrict": "2018-10-30T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2018-10-30T15:30:00.00Z",
            "duration": "3600s",
            "spotsOpen": "1",
            "scheduleException": [
             {
                "timeRange": {
                  "startTime": "2018-10-30T12:30:00.00Z",
                  "endTime": "2018-10-30T13:00:00.00Z"
                }
              },
              {
                "timeRange": {
                  "startTime": "2018-10-30T15:30:00.00Z",
                  "endTime": "2018-10-30T16:00:00.00Z"
                }
              }
            ]
          }
        ]
      }
    ]
  }

Ecco un esempio di ciò che è previsto nel feed giornaliero successivo. Tieni presente che si tratta dell'intera disponibilità del servizio per il commerciante e di tutti i suoi schedule_exceptions precedenti e nuovi:

Snippet del feed

   "availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 1,
          "start_sec": 1540890000, # October 30, 2018 9:00:00 AM
          "duration_sec": 1800,
          "recurrence": {
            "repeat_every_sec": 1800,
            "repeat_until_sec": 1540918800 # October 30, 2018 5:00:00 PM
          },
          "schedule_exception": [
            {
              "time_range": {
                "begin_sec": 1540902600, # October 30, 2018 12:30:00 PM
                "end_sec": 1540904400 # October 30, 2018 1:00:00 PM
              }
            },
            {
              "time_range": {
                "begin_sec": 1540913400, # October 30, 2018 3:30:00 PM
                "end_sec": 1540915200 # October 30, 2018 4:00:00 PM
              }
            }
          ],
        }
      ]

Quando inviare gli aggiornamenti in tempo reale

Gli aggiornamenti in tempo reale devono essere inviati continuamente ogni volta che la disponibilità cambia. Questo si aggiunge a un feed completo della disponibilità che deve essere inviato una volta al giorno, per garantire che la disponibilità sia sincronizzata tra i tuoi sistemi e quelli di Google.