Cette page a été traduite par l'API Cloud Translation.

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 scénarios suivants:

Lorsqu'un utilisateur annule une réservation sur votre système et que le créneau devient disponible.
Lorsqu'un utilisateur réserve une réservation via Réserver avec Google et que le créneau de disponibilité n'est plus disponible.
Lorsqu'une réservation effectuée via Réserver avec Google est annulée de votre part, par exemple, directement par le marchand. Vous devrez mettre à jour la réservation ainsi que la disponibilité, car le créneau d'origine est à nouveau disponible.

En outre, si vous mettez en œuvre le remplacement de disponibilité RTU, des mises à jour en temps réel doivent être publiées dans les scénarios suivants:

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

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

notification.partners.bookings.patch (BookingNotification.UpdateBooking)

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

inventory.partners.availability.replace (InventoryUpdate.BatchServiceAvailability) OU inventory.partners.merchants.services.availability.replace (InventoryUpdate.ReplaceServiceAvailability)

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

En cas de mise à jour d'une réservation Réserver avec Google (par exemple, annulation ou modification) sur votre système, vous devez envoyer un message notification.partners.bookings.patch (BookingNotification.UpdateBooking).

Champs modifiables

status
startTime
duration
partySize
paymentInformation.prepaymentStatus

Remarque:name, merchant_id, service_id et le champ spécifique qui doit être modifié doivent être spécifiés. Tous les autres sont facultatifs. Dans certains cas, plusieurs champs peuvent être modifiés en même temps. Dans ce cas, séparez les champs dans updateMask (par exemple, updateMask=partySize,startTime).

Exemple de résiliation

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": "2014-10-02T15:01:23.045123456Z",
  "duration": "3000s",
  "status": "CANCELED"
}

Availability Replace – Mises à jour en temps réel

Il existe deux méthodes de remplacement pour mettre à jour la disponibilité:

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

Pour en savoir plus, consultez la documentation de référence ci-dessous.

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

spotsOpen
recurrence

Veuillez consulter le guide de la structure de disponibilité pour déterminer le format qui vous convient le mieux.

Choisir une méthode de remplacement à appeler

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

Plusieurs services sont-ils affectés par une seule réservation ? Par exemple, une coupe de cheveux et une coloration (chacune étant un service distinct) sont réservées par un styliste. Tous les services liés au coiffeur pour ce créneau horaire doivent donc être supprimés.
- Remplacement par lot
Votre système se synchronisera de temps en temps avec Google en envoyant toutes les modifications de disponibilité depuis la dernière mise à jour (déconseillé).
- Remplacement par lot
- Remarque: La RTU de l'inventaire doit être envoyée dans les cinq minutes suivant une mise à jour de votre côté. Nous vous conseillons de vérifier et d'envoyer les éventuelles mises à jour au moins toutes les cinq minutes.
Aucune de ces propositions ne s'applique ?
- Remplacement simple
- Remarque: Vous pouvez utiliser plusieurs appels de remplacement unique pour émuler 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: Spots Open Format

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.

L'extrait de flux spots_open se présente comme suit:

Extrait de flux

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

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

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

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

Voici un exemple de ce à quoi nous nous attendons dans le prochain flux quotidien, si un nouveau créneau à 15h30 est réservé :

Extrait de flux

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

Remarque:S'il n'y a plus de disponibilité (spots_open est égal à 0), il existe deux formats possibles pour envoyer la demande de remplacement pour Inventory API.

Spécification explicite : méthode recommandée si vous disposez de spots_total > 1

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

Spécification vide : recommandé uniquement si spots_total = 1 pour la plupart des marchands et des services.

  {
  "extendedServiceAvailability": [
    {
      "merchantId": "1001",
      "serviceId": "12310",
      "startTimeRestrict": "2014-10-02T15:01:23.045123456Z",
      "endTimeRestrict": "2014-10-02T19:01:23.045123456Z",
      "availability": [
        {}
      ]
    }
  ]
}

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 à quoi ressemble un flux qui utilise 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 pour un créneau de 15h30 est réservé :

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

Remarque : Les mises à jour en temps réel doivent contenir l'ensemble des schedule_exceptions pour les emplacements réservés. En effet, la méthode API remplace la disponibilité du service et du marchand en question. Si vous le remplacez par un autre, il doit s'agir d'informations complètes sur la disponibilité du service, et doit inclure tous ses emplacements réservés.

Voici un exemple de ce à quoi vous devez vous attendre dans le flux quotidien suivant. Notez qu'il s'agit de la disponibilité complète du service pour ce marchand, et 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. Il s'ajoute à un flux de disponibilité complet qui doit être envoyé une fois par jour afin que la disponibilité soit synchronisée entre vos systèmes et ceux de Google.