Asynchrone Buchungen aktivieren

Synchrone Buchungen werden als Buchungen definiert, die in Echtzeit bestätigt oder abgelehnt werden.

Asynchrone Buchungen werden vom Händler zu einem späteren Zeitpunkt bestätigt oder abgelehnt.

Eine Buchung wird auf Verfügbarkeitsebene als synchron oder asynchron angegeben. Das bedeutet auch, dass es für einen bestimmten Händler und eine bestimmte Dienstleistung sowohl synchrone als auch asynchrone verfügbare Slots geben kann.

Ermitteln Sie zur Bestimmung der geeigneten Implementierung zuerst, zu welcher Kategorie Ihr Inventar gehört:

Kriterien für asynchrone Buchungen

  • Eine asynchrone Buchung in „Mit Google reservieren“ wird nicht unterstützt.
  • Asynchrone Buchungen, für die Zahlungen erforderlich sind, werden nicht unterstützt.
  • Händler sollten die Buchung über das Onlinesystem des Partners annehmen oder ablehnen können (z.B. Hostbereich für das Restaurant). Es ist nicht zulässig, den Händler im Namen des Nutzers anzurufen, um herauszufinden, ob der Händler die Buchung annimmt oder ablehnt.
  • Händler können keine alternativen Zeiten für Buchungen vorschlagen. Die Buchungsanfrage muss im ursprünglichen Zustand angenommen oder abgelehnt werden.

Nur synchrone Buchungen aktivieren

In der Standardimplementierung sind synchrone Buchungen voreingestellt. Weitere Informationen finden Sie im End-to-End-Integrationsleitfaden.

Asynchrone Buchung aktivieren

Wenn einige oder alle Händler einen asynchronen Buchungsvorgang verwenden, müssen die folgenden Änderungen vorgenommen werden:

  • Bestätigungsmodus: Alle Darstellungen von verfügbaren Slots enthalten jetzt das Feld confirmation_mode. Dieses Feld beschreibt, wie Buchungen dieses Slots bestätigt werden. Gib für jeden Verfügbarkeits-Slot die confirmation_mode für Folgendes an:

    • Im Verfügbarkeitsfeed wird confirmation_mode auf Verfügbarkeitsebene angegeben.
    • In den Booking Server API-Methoden wird confirmation_mode auf Slot-Ebene angegeben
    • In den API-Methoden für Echtzeitaktualisierungen wird confirmation_mode auf Verfügbarkeitsebene angegeben
  • Buchungsstatus:Alle Darstellungen von Buchungen enthalten das Feld status für den Status der Buchung. Es wurden drei neue asynchrone Statuswerte eingeführt: PENDING_CONFIRMATION, DECLINED_BY_MERCHANT und FAILED. Verwenden Sie diese neuen Statuswerte beim Verarbeiten von Kreationen, Ablehnungen und Fehlern bei asynchronen Buchungen.
  • Buchungsaktualisierungen:Alle asynchronen Aktualisierungen am Buchungsstatus sollten über die Methode bookings.patch der Booking Notification API gemeldet werden.

Das folgende Diagramm zeigt, wie der Bestätigungsmodus und der Buchungsstatus bei einer typischen asynchronen Buchungsinteraktion verwendet werden.

Abbildung 1: Asynchroner Buchungsvorgang
Abbildung 1:Asynchroner Buchungsvorgang
  1. Verfügbarkeitsfeeds wurden aktualisiert, sodass der Bestätigungsmodus für jeden verfügbaren Slot angegeben ist. Diese Informationen müssen im Feed enthalten sein, damit wir dem Nutzer schon früh im Ablauf den asynchronen Charakter der Buchung erklären können.
  2. Wenn BatchAvailabilityLookup oder CheckAvailability aufgerufen wird, übergeben wir den Bestätigungsmodus und idealerweise denselben Bestätigungsmodus, der zurückgegeben wird. So wird sichergestellt, dass dem Nutzer die richtige Botschaft angezeigt wird.
  3. Beim Aufruf von CreateBooking wird der Bestätigungsmodus übergeben, um den erwarteten Bestätigungsmodus anzugeben. Wenn die asynchrone Buchungsanfrage gesendet wird, wird die Buchung mit dem Status PENDING_MERCHANT_CONFIRMATION zurückgegeben.
  4. Wenn der Händler eine Buchungsanfrage annimmt oder ablehnt, wird der Buchungsstatus über die Methode bookings.patch der Booking Notification API für die Echtzeitaktualisierung aktualisiert. Wenn Sie Buchungen, die nicht zeitnah beantwortet werden, automatisch ablehnen möchten, können Sie dies mit derselben Echtzeitaktualisierungsmethode tun.

Verfügbarkeitsfeeds

Geben Sie im Verfügbarkeitsfeed an, ob jeder Slot synchron oder asynchron ist. Legen Sie dazu das neue Feld confirmation_mode fest.

// 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;
}

Es wird angenommen, dass der Bestätigungsmodus synchron ist, wenn kein Modus angegeben ist. Es wird jedoch dringend empfohlen, einen Modus explizit anzugeben, da dadurch Verwirrungen im Zusammenhang mit versehentlichen Auslassungen vermieden werden.

Asynchron

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

Synchron

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

Asynchron und synchron

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

  ]
}

Buchungsserver

"BatchAvailabilityLookup" oder "CheckAvailability"

In BatchAvailabilityLookupResponse (BAL) oder CheckAvailabilityResponse (CA) wird dasselbe confirmation_mode wie im Verfügbarkeitsfeed angegeben zurückgegeben und über BatchAvailabilityLookupRequest oder CheckAvailabilityRequest weitergegeben.

BAL – asynchron

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

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

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

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

Geben Sie den richtigen Buchungsstatus zurück, indem Sie die folgenden Optionen nutzen:

// 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;
}

In der CreateBookingResponse wird der aktuelle confirmation_mode für den aggregierten Slot der Buchung zurückgegeben, der in CreateBookingRequest angegeben ist. Wenn die Buchung asynchron ist, setze status außerdem auf PENDING_MERCHANT_CONFIRMATION. Achte darauf, dass „confirmation_mode“ der Nutzer ist und was „Mit Google reservieren“ erwartet, um den Nutzer nicht zu verwirren.

Asynchron

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

Synchron

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

In der ersten Version des asynchronen Modus werden Nutzeränderungen an einer vorhandenen Buchung nicht unterstützt. Stattdessen sollte der Nutzer die Buchung stornieren und eine neue erstellen.

Echtzeitaktualisierungen

Für Echtzeitaktualisierungen der Verfügbarkeit sollte confirmation_mode angegeben werden. Das gilt für folgende Methoden:

Inventar-CTR

Legen Sie mit der Methode availability.replace (Batch) oder services.availability.replace confirmation_mode in der Availability auf CONFIRMATION_MODE_ASYNCHRONOUS fest.

Asynchron

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

Synchron

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

Asynchron und synchron

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

Booking Notification API

Asynchrone Aktualisierungen des Buchungsstatus sollten über die Booking Notification API-Methode bookings.patch vorgenommen werden.

Wenn du den Status aktualisierst, musst du den status-Feldnamen in das updateMask aufnehmen.

Status Beschreibung
CONFIRMED Der Händler hat die Buchung bestätigt.
FAILED Der Partner konnte die Buchung beim Händler weder bestätigen noch ablehnen.
DECLINED_BY_MERCHANT Der Händler hat die Buchung abgelehnt. 
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"}

Legen Sie bei einem Buchungsfehler den Buchungsstatus auf FAILED fest und geben Sie „booking_failure“ an. Wenn der Status auf einen anderen Wert gesetzt ist, wird booking_failure ignoriert.

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

E-Mail-Benachrichtigungen

Bei asynchronen Buchungen gibt es fünf potenzielle E-Mails zum Status der Buchung, die an Nutzer gesendet werden.

  • PENDING_MERCHANT_CONFIRMATION
  • CONFIRMED
  • DECLINED_BY_MERCHANT
  • FAILED
  • CANCELED