Structurer les mises à jour en temps réel

Cas d'utilisation des mises à jour en temps réel

Les mises à jour en temps réel doivent toujours être émises dans les cas suivants :

  • Lorsqu'un utilisateur annule une réservation sur votre système et que le créneau devient disponible.
  • Lorsqu'un utilisateur effectue une réservation via le Centre d'actions et que le créneau n'est plus disponible.
  • Une réservation effectuée via le Centre d'actions est annulée de votre côté (par exemple, directement par le marchand). Vous devrez mettre à jour à la fois la réservation et la disponibilité, car le créneau d'origine est de nouveau disponible.

De plus, si vous implémentez la mise à jour en temps réel Availability Replace, les mises à jour en temps réel doivent être émises dans les scénarios suivants :

  • Lorsqu'un marchand modifie sa programmation (disponibilité) dans votre système.
  • Lorsqu'un utilisateur effectue une réservation sur votre système et que le créneau n'est plus disponible.
  • Si vous utilisez une ancienne intégration avec CheckAvailability, lorsqu'un appel CheckAvailability au serveur de réservation renvoie un inventaire qui ne correspond pas à l'inventaire réel.

Tous les appels de l'API Maps Booking ne sont pas obligatoires. Les éléments suivants sont obligatoires :

Selon le type d'intégration, les éléments suivants peuvent également être disponibles ou requis :

Mettre à jour la réservation – Mises à jour en temps réel

Si une réservation Actions Center (par exemple, annulée ou modifiée) a été mise à jour dans votre système, un notification.partners.bookings.patch (BookingNotification.UpdateBooking) doit être envoyé.

Champs modifiables

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

Exemple d'annulation

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 – Mises à jour en temps réel

Deux types de méthodes de remplacement sont disponibles pour mettre à jour votre disponibilité :

  • Remplacer par lot (InventoryUpdate.BatchServiceAvailability) : remplace complètement les données de disponibilité pour plusieurs marchands et services.
    • Remarque : Cet appel par lot ne garantit pas l'atomicité. Seuls les créneaux de disponibilité mis à jour sont renvoyés.
  • Remplacement unique (InventoryUpdate.ReplaceServiceAvailability) : remplace complètement la disponibilité d'un marchand et d'un service uniques.

Pour en savoir plus, veuillez consulter la documentation de référence.

Les mises à jour en temps réel doivent utiliser la même structure de disponibilité que les données envoyées via les flux. Ils doivent utiliser l'un des éléments suivants :

  • spotsOpen
  • recurrence

Choisir une méthode de remplacement à appeler

Utilisez le guide suivant pour déterminer la méthode de remplacement la plus appropriée :

  • Plusieurs marchands sont-ils concernés ? Par exemple, remplacez la disponibilité de plusieurs marchands dans une seule requête.
  • Votre système se synchronisera de temps en temps avec Google en envoyant toutes les modifications de disponibilité depuis la dernière mise à jour (non recommandé).
    • Remplacer par lot
    • Remarque : Nous nous attendons à ce que l'unité de traitement et d'utilisation (RTU) de l'inventaire soit envoyée dans les cinq minutes suivant une mise à jour de votre côté. Vous devez donc vérifier et envoyer les mises à jour au moins toutes les cinq minutes.
  • Aucun de ces cas ne s'applique ou vous n'avez besoin de mettre à jour qu'un seul marchand et service ?
    • Remplacer une seule fois
    • Remarque : Vous pouvez utiliser plusieurs appels de remplacement unique pour simuler un appel de remplacement par lot, mais il serait plus efficace d'utiliser un seul appel de remplacement par lot.

Mises à jour en temps réel : format ouvert pour les emplacements

Il est important d'utiliser le même format dans les flux, le serveur de réservation et les mises à jour en temps réel.

Voici à quoi ressemble un extrait de flux spots_open :

Extrait de flux

   "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"
          }
    ]

Pour l'API Inventory Update, voici le format du corps de la requête de remplacement lorsqu'un créneau de 15h30 est réservé :

Remplacer l'extrait de code des mises à jour en temps réel

  {
    "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"
          }
        ]
      }
    ]
  }

Voici un exemple de ce que nous attendons dans le prochain flux quotidien si un nouvel emplacement à 15h30 est réservé :

Extrait de flux

"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"
        }
      ]

Mises à jour en temps réel : format de récurrence

Il est important d'utiliser le même format dans les flux, le serveur de réservation et les mises à jour en temps réel.

Voici un exemple de flux utilisant la récurrence :

Extrait de flux

  "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
              }
            }
          ],
        }
      ]

Pour l'API Inventory Update, le format du corps de la requête de remplacement lorsqu'un créneau de 15h30 est réservé se présente comme suit :

  {
    "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"
                }
              }
            ]
          }
        ]
      }
    ]
  }

Voici un exemple de ce qui est attendu dans le prochain flux quotidien. Notez qu'il s'agit de la disponibilité de l'ensemble du service pour ce marchand, ainsi que de tous ses schedule_exceptions précédents et nouveaux :

Extrait de flux

   "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
              }
            }
          ],
        }
      ]

Quand envoyer des mises à jour en temps réel

Les mises à jour en temps réel doivent être envoyées en continu chaque fois que la disponibilité change. En plus d'un flux de disponibilité complet qui doit être envoyé une fois par jour, afin de s'assurer que la disponibilité est synchronisée entre vos systèmes et ceux de Google.