Activer des réservations asynchrones

Les réservations synchrones sont définies comme confirmées ou refusées en temps réel.

Les réservations asynchrones sont définies comme étant des réservations que le marchand confirme ou refuse ultérieurement.

Une réservation est spécifiée en mode synchrone ou asynchrone au niveau de la disponibilité. Cela signifie également que, pour un marchand et un service donnés, il peut exister des créneaux de disponibilité synchrones et asynchrones.

Pour déterminer la mise en œuvre appropriée, commencez par identifier la catégorie à laquelle appartient votre inventaire:

Critères applicables aux réservations asynchrones

  • Vous ne pouvez pas modifier une réservation asynchrone sur Réserver avec Google.
  • Le système n'est pas compatible avec les réservations asynchrones nécessitant des paiements.
  • Les marchands doivent pouvoir accepter ou refuser la réservation via le système en ligne du partenaire (par exemple, le panneau hôte du restaurant). Il n'est pas autorisé d'appeler le marchand pour le compte de l'utilisateur afin de 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. Veuillez consulter le guide d'intégration de bout en bout pour en savoir plus.

Activer la réservation asynchrone

Si certains ou tous les marchands utilisent un flux de réservation asynchrone, vous devez apporter les modifications suivantes:

  • Mode de confirmation : toutes les représentations des créneaux de disponibilité contiennent désormais un champ confirmation_mode décrivant la façon dont les réservations de ce créneau de disponibilité sont confirmées. Indiquez le confirmation_mode de chaque créneau de disponibilité pour les éléments suivants:

    • Dans le flux 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 de l'emplacement Slot.
    • 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 représentant l'état de la réservation. Trois nouvelles valeurs d'état asynchrones ont été introduites: PENDING_CONFIRMATION, DECLINED_BY_MERCHANT et FAILED. Utilisez ces nouvelles valeurs d'état lors du traitement des créations, des refus et des échecs des 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 schéma ci-dessous montre comment le mode de confirmation et l'état de la réservation sont utilisés dans une interaction de réservation asynchrone classique.

Figure 1: Flux de réservation asynchrone
Figure 1 : Flux de réservation asynchrone
  1. Les flux disponibilité ont été mis à jour de sorte que le mode de confirmation de chaque créneau de disponibilité soit spécifié. 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. L'utilisateur reçoit ainsi le message approprié.
  3. Lorsque CreateBooking est appelé, nous transmettons le mode de confirmation pour indiquer le mode de confirmation attendu. Lorsque la requête 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 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 au moment opportun, utilisez la même méthode de mise à jour en temps réel.

Flux de disponibilité

Dans le flux 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 mode de confirmation soit considéré comme synchrone si aucun mode n'est spécifié, il est fortement recommandé de spécifier explicitement un mode, car cela élimine toute confusion liée aux omissions accidentelles.

Async

{
  "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 BatchAvailabilityLookupResponse (BAL) ou CheckAvailabilityResponse (CA), renvoyez le même confirmation_mode que celui spécifié dans le flux de disponibilité, et transmis via 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

Veillez à renvoyer l'état correct de la réservation à l'aide des 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 l'identifiant confirmation_mode actuel de l'emplacement agrégé de la réservation fourni dans la requête CreateBookingRequest. En outre, lorsque la réservation est asynchrone, définissez status sur PENDING_MERCHANT_CONFIRMATION. Veuillez vous assurer que confirmation_mode correspond à ce que l'utilisateur et à Réserver avec Google s'attendent à éviter pour éviter toute confusion.

Async

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

Synchronisation

{
  "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'Asynchrone, les modifications apportées par l'utilisateur à une réservation existante ne sont pas acceptées. L'utilisateur doit annuler la réservation et en créer une autre.

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 :

Inventaire RTU (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 le Availability

Async

{
  "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.

Lorsque vous mettez à jour 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 du champ "booking_failure". Si l'état est défini sur autre chose, 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 liés à l'état de la réservation sont envoyés aux utilisateurs.

  • PENDING_MERCHANT_CONFIRMATION
  • CONFIRMED
  • DECLINED_BY_MERCHANT
  • FAILED
  • CANCELED