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

Ajouter des réservations asynchrones

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

Les réservations asynchrones sont celles que le marchand confirme ou refuse ultérieurement.

Une réservation est spécifiée comme 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é à la fois synchrones et asynchrones.

Pour déterminer l'implémentation appropriée, commencez par identifier la catégorie de votre inventaire:

Activer uniquement les réservations synchrones : tous les marchands et services sont confirmés instantanément.
Activer les réservations asynchrones : une confirmation manuelle est requise pour certains marchands et services, ou pour l'ensemble d'entre eux.

Critères applicables aux réservations asynchrones

La modification d'une réservation asynchrone dans le Centre d'actions n'est pas autorisée.
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 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, veuillez consulter la documentation sur l'intégration de bout en bout des rendez-vous.

Activer la réservation asynchrone

Si certains marchands ou tous utilisent un processus 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 qui décrit la façon dont les réservations de ce créneau sont confirmées. Spécifiez 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 du créneau.
- Dans les méthodes de l'API Real-Time Updates, confirmation_mode est spécifié au niveau de disponibilité.
État de la réservation:toutes les représentations des réservations contiennent un champ status qui représente 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 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 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: Processus de réservation asynchrone — **Figure 1**:Processus de réservation asynchrone

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 que ces informations figurent dans le flux afin que nous puissions expliquer à l'utilisateur le caractère asynchrone de la réservation dès le début du processus.
Lorsque BatchAvailabilityLookup ou CheckAvailability est appelé, nous transmettons le mode de confirmation et, idéalement, le même mode de confirmation à renvoyer. Cela permet de s'assurer que l'utilisateur voit le message approprié.
Lorsque CreateBooking est appelé, nous transmettons le mode de confirmation pour 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.
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 la mise à jour en temps réel de l'API Booking Notification. Si vous souhaitez refuser automatiquement les réservations auxquelles vous ne répondez pas dans les meilleurs délais, utilisez la même méthode de mise à jour en temps réel.

Flux de disponibilité

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

Remarque:Le confirmation_mode est stocké dans la section "Disponibilité" des flux de disponibilité et des mises à jour en temps réel. Toutefois, ce champ est stocké au niveau du créneau dans les API Booking Server.

// 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 nous partons du principe que le mode de confirmation est synchrone si aucun mode n'est spécifié, nous vous recommandons vivement d'en spécifier explicitement un, car cela permet d'éviter toute confusion éventuelle.

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 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 le confirmation_mode actuel pour le créneau agrégé de la réservation fourni dans CreateBookingRequest. En outre, si la réservation est asynchrone, définissez status sur PENDING_MERCHANT_CONFIRMATION. Pour éviter toute confusion, veuillez vous assurer que confirmation_mode correspond à ce que l'utilisateur s'attend à voir et à ce qu'attend Réserver avec Google.

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

Synchroniser

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

La version initiale d'async ne permet pas de modifier une réservation existante par les utilisateurs. L'utilisateur doit alors l'annuler 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 (méthode par lot) ou de la méthode services.availability.replace, définissez confirmation_mode sur CONFIRMATION_MODE_ASYNCHRONOUS dans 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 "booking_failure". Si l'état est défini sur autre chose, booking_failure est ignoré.

Remarque:Les champs booking_failure sont transmis en tant qu'arguments de requête sur l'URL.

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 sont envoyés aux utilisateurs concernant l'état de la réservation.

PENDING_MERCHANT_CONFIRMATION
CONFIRMED
DECLINED_BY_MERCHANT
FAILED
CANCELED