Ajouter des réservations asynchrones

Une réservation est définie comme synchrone si elle est confirmée ou refusée en temps réel.

Une réservation est définie comme asynchrone si le marchand doit la confirmer ou la refuser ultérieurement.

Vous définissez une réservation comme étant synchrone ou asynchrone au niveau de la disponibilité. Ainsi, pour un marchand et un service donnés, il peut exister des créneaux de disponibilité à la fois synchrones et asynchrones.

Pour savoir quel type de réservation mettre en œuvre, commencez par identifier votre catégorie d'inventaire:

Critères applicables aux réservations asynchrones

  • La modification d'une réservation asynchrone dans le Centre d'actions n'est pas possible.
  • Les marchands doivent avoir la possibilité d'accepter ou de refuser la réservation via le système en ligne du partenaire (panneau hôte du restaurant, par exemple). Il n'est pas autorisé d'appeler le marchand au nom de l'utilisateur pour déterminer s'il accepte ou refuse une réservation.
  • Le système ne permet pas que le marchand propose une nouvelle heure de réservation. La demande de réservation doit être acceptée ou refusée dans son état d'origine.

Activer uniquement des réservations synchrones

La mise en œuvre standard utilise par défaut les réservations synchrones. Pour en savoir plus, consultez la documentation sur l'intégration de bout en bout des rendez-vous.

Activer les réservations asynchrones

Si tous les marchands ou une partie d'entre eux utilisent un processus de réservation asynchrone, vous devez apporter les modifications suivantes:

  • Mode de confirmation:toutes les représentations de créneaux de disponibilité contiennent désormais un champ confirmation_mode qui décrit comment les réservations du créneau en question sont confirmées. Spécifiez le confirmation_mode de chaque créneau de disponibilité comme suit:

    • Dans le flux de disponibilité, confirmation_mode est spécifié au niveau de la disponibilité.
    • Dans les méthodes de l'API Booking Server, confirmation_mode est spécifié au niveau du créneau.
    • Dans les méthodes de l'API Real-Time Updates, confirmation_mode est spécifié au niveau de la disponibilité.
  • État de la réservation:toutes les représentations des réservations contiennent un champ status qui indique l'état de la réservation. Trois nouvelles valeurs d'état asynchrone ont été introduites: PENDING_CONFIRMATION, DECLINED_BY_MERCHANT et FAILED. Utilisez ces nouvelles valeurs d'état lors du traitement de créations, refus et échecs de réservations asynchrones.
  • Mises à jour des réservations:toutes les mises à jour asynchrones de l'état des réservations doivent être signalées via la méthode bookings.patch de l'API Booking Notification.

Le diagramme ci-dessous montre comment le mode de confirmation et l'état de réservation sont utilisés dans une interaction de réservation asynchrone classique.

Figure 1: Processus de réservation asynchrone
Figure 1:Processus de réservation asynchrone
  1. Les flux disponibilité ont été mis à jour afin que le mode de confirmation puisse être spécifié au niveau de chaque créneau de disponibilité. Il est important d'inclure ces informations dans le flux afin que nous puissions expliquer la nature asynchrone de la réservation à l'utilisateur dès le début du processus.
  2. Lorsque BatchAvailabilityLookup ou CheckAvailability est appelé, nous transmettons le mode de confirmation et, idéalement, le même mode de confirmation à renvoyer. Cela permet que l'utilisateur reçoive les bonnes informations.
  3. Lors de l'appel de CreateBooking, nous transmettons le mode de confirmation afin d'indiquer le mode de confirmation attendu. Lorsque la demande de réservation asynchrone est envoyée, la réservation est renvoyée avec l'état PENDING_MERCHANT_CONFIRMATION.
  4. Lorsque le marchand accepte ou refuse une demande de réservation, l'état de la réservation est mis à jour en temps réel via la méthode bookings.patch de l'API Booking Notification. Si vous souhaitez refuser automatiquement les réservations qui ne sont pas traitées rapidement, utilisez la même méthode de mise à jour en temps réel.

Flux de disponibilité

Dans le flux de disponibilité, spécifiez si chaque créneau est synchrone ou asynchrone. Pour ce faire, définissez le nouveau champ confirmation_mode.

// Mode by which bookings for an availability slot are confirmed.
enum ConfirmationMode {
  // The confirmation mode was not specified.
  // Synchronous confirmation will be assumed.
  CONFIRMATION_MODE_UNSPECIFIED = 0;

  // Bookings for this availability will be confirmed synchronously.
  CONFIRMATION_MODE_SYNCHRONOUS = 1;

  // Bookings for this availability will be confirmed asynchronously.
  CONFIRMATION_MODE_ASYNCHRONOUS = 2;
}

Bien que le système part du principe que le mode de confirmation est synchrone si aucun mode n'est spécifié, nous vous recommandons fortement d'en spécifier un explicitement, car cela empêchera toute confusion due à une omission accidentelle.

Asynchrone

{
  "availability": [
    {
      "merchant_id": "10001",
      "service_id": "1000",
      "spots_open": 3,
      "spots_total": 3,
      "duration_sec": 3600,
      "start_sec": 1535806800,
      "resources": {
        "party_size": 4
      },
      "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
    }
  ]
}

Synchrone

{
  "availability": [
    {
      "merchant_id": "10001",
      "service_id": "1000",
      "spots_open": 3,
      "spots_total": 3,
      "duration_sec": 3600,
      "start_sec": 1535806800,
      "resources": {
        "party_size": 4
      },
      "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
    }
  ]
}

Asynchrone et synchrone

{
  "availability": [
    {
      "merchant_id": "10001",
      "service_id": "1000",
      "spots_open": 3,
      "spots_total": 3,
      "duration_sec": 3600,
      "start_sec": 1535806800,
      "resources": {
        "party_size": 4
      },
      "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
    },
    {
      "merchant_id": "10002",
      "service_id": "1000",
      "spots_open": 4,
      "spots_total": 4,
      "duration_sec": 3600,
      "start_sec": 1535806800,
      "resources": {
        "party_size": 2
      },
      "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
    }

  ]
}

Serveur de réservation

BatchAvailabilityLookup ou CheckAvailability

Dans les réponses BatchAvailabilityLookupResponse (BAL) ou CheckAvailabilityResponse (CA), renvoyez la même valeur confirmation_mode que celle spécifiée dans le flux de disponibilité et transmise via les requêtes BatchAvailabilityLookupRequest ou CheckAvailabilityRequest.

BAL-Async

{
  "slot_time_availability": [
    {
      "slot_time": {
        "duration_sec": "3600",
        "resource_ids": {
          "party_size": 3
        },
        "service_id": "1000",
        "start_sec": "1546458300",
        "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
      },
      "available": true
    }
  ]
}

BAL-Sync

{
  "slot_time_availability": [
    {
      "slot_time": {
        "duration_sec": "3600",
        "resource_ids": {
          "party_size": 3
        },
        "service_id": "1000",
        "start_sec": "1546458300",
        "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
      },
      "available": true
    }
  ]
}

CA-Async

{
  "slot": {
    "duration_sec": "3600",
    "merchant_id": "317652",
    "resources": {
      "party_size": 3
    },
    "service_id": "1000",
    "start_sec": "1546458300",
    "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
  },
  "count_available": 1,
  "duration_requirement": "DO_NOT_SHOW_DURATION"
}

CA-Sync

{
  "slot": {
    "duration_sec": "3600",
    "merchant_id": "317652",
    "resources": {
      "party_size": 3
    },
    "service_id": "1000",
    "start_sec": "1546458300",
    "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
  },
  "count_available": 1,
  "duration_requirement": "DO_NOT_SHOW_DURATION"
}

CreateBooking

Assurez-vous de renvoyer correctement l'état de la réservation en utilisant les options disponibles ci-dessous:

// Status of a booking.
//
// Updating booking status does not change the status of the associated payment.
// Prepayment status updates should be done using the PrepaymentStatus enum.
enum BookingStatus {
  // Not specified.
  BOOKING_STATUS_UNSPECIFIED = 0;

  // Booking has been confirmed
  CONFIRMED = 1;

  // Booking is awaiting confirmation by the merchant before it can transition
  // into CONFIRMED status. Only applicable to non-payments Dining or
  // Beauty verticals.
  PENDING_MERCHANT_CONFIRMATION = 2;

  // Booking has been canceled on behalf of the user.
  // The merchant can still trigger a manual refund.
  CANCELED = 3;

  // User did not show for the appointment
  NO_SHOW = 4;

  // User did not show for the appointment in violation of the cancellation
  // policy.
  NO_SHOW_PENALIZED = 5;

  // Booking could not be completed by the async backend due to a failure.
  FAILED = 6;

  // Booking was asynchronously declined by the merchant. Only applicable to
  // non-payments Dining or Beauty verticals.
  DECLINED_BY_MERCHANT = 7;
}

Dans CreateBookingResponse, renvoyez la valeur confirmation_mode actuelle pour le créneau agrégé associé à la réservation fourni dans la requête CreateBookingRequest. En outre, si la réservation est asynchrone, définissez status sur PENDING_MERCHANT_CONFIRMATION. Afin de ne pas créer de confusion, veuillez vous assurer que confirmation_mode correspond à ce que l'utilisateur et à Réserver avec Google s'attendent.

Asynchrone

{
  "booking": {
    "slot": {
      "duration_sec": "3600",
      "merchant_id": "100001",
      "resources": {
        "party_size": 2
      },
      "service_id": "1000",
      "start_sec": "1546647234",
      "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
    },
    "user_information": {
      "email": "johnsmith@gmail.com",
      "family_name": "John",
      "given_name": "Smith",
      "telephone": "+1 800-123-4567",
      "user_id": "2017492857928759285"
    },
    "payment_information": {
      "prepayment_status": "PREPAYMENT_NOT_PROVIDED"
    },
    "status": "PENDING_MERCHANT_CONFIRMATION"
  }
}

Sync

{
  "booking": {
    "slot": {
      "duration_sec": "3600",
      "merchant_id": "100001",
      "resources": {
        "party_size": 2
      },
      "service_id": "1000",
      "start_sec": "1546647234",
      "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
    },
    "user_information": {
      "email": "johnsmith@gmail.com",
      "family_name": "John",
      "given_name": "Smith",
      "telephone": "+1 800-123-4567",
      "user_id": "2017492857928759285"
    },
    "payment_information": {
      "prepayment_status": "PREPAYMENT_NOT_PROVIDED"
    },
    "status": "CONFIRMED"
  }
}

UpdateBooking

Dans la version initiale d'async, les modifications apportées par les utilisateurs à une réservation existante ne sont pas acceptées. À la place, l'utilisateur doit annuler la réservation et en créer une autre.

Real-Time Updates (Mises à jour en temps réel)

Pour les mises à jour en temps réel des disponibilités, confirmation_mode doit être spécifié. Cela s'applique aux méthodes suivantes :

Mises à jour en temps réel de l'inventaire (ReplaceServiceAvailability ou BatchReplaceServiceAvailability)

À l'aide de la méthode availability.replace (par lot) ou de la méthode services.availability.replace, définissez confirmation_mode sur CONFIRMATION_MODE_ASYNCHRONOUS dans Availability.

Asynchrone

{
  "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",
          "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
        }
      ]
    }
  ]
}

Synchrone

{
  "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",
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        }
      ]
    }
  ]
}

Asynchrone et synchrone

{
  "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",
          "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
        },
        {
          "startTime": "2014-10-03T11:00:00.00Z",
          "duration": "5400s",
          "spotsOpen": "1",
          "spotsTotal": "1",
          "availabilityTag": "1000002",
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        }
      ]
    }
  ]
}

API Booking Notification

Les mises à jour asynchrones d'un état de réservation doivent être effectuées via la méthode bookings.patch de l'API Booking Notification.

Lors de la mise à jour de l'état, veillez à inclure le nom du champ status dans updateMask.

État Description
CONFIRMED Le marchand a confirmé la réservation.
FAILED Le partenaire n'a pas pu confirmer ou refuser la réservation auprès du marchand.
DECLINED_BY_MERCHANT Le marchand a refusé la réservation. 
Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status

Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"DECLINED_BY_MERCHANT"}

En cas d'échec de la réservation, définissez l'état de la réservation sur FAILED et spécifiez la valeur de booking_failure. Si l'état est défini sur une autre valeur, booking_failure est ignoré.

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

Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"FAILED"}

Notifications par e-mail

Pour les réservations asynchrones, cinq e-mails potentiels relatifs à l'état de la réservation sont envoyés aux utilisateurs.

  • PENDING_MERCHANT_CONFIRMATION
  • CONFIRMED
  • DECLINED_BY_MERCHANT
  • FAILED
  • CANCELED