Asynchrone Buchungen hinzufügen

Hinweis:Wenn Sie die asynchronen Buchungen aktivieren möchten, füllen Sie dieses Formular aus. Außerdem werden asynchrone Buchungen nur von Integrationen der REST-basierten API Version 3 unterstützt.

Synchrone Buchungen werden in Echtzeit bestätigt oder abgelehnt.

Asynchrone Buchungen sind Buchungen, die der Händler später bestätigt oder ablehnt.

Eine Buchung wird auf Verfügbarkeitsebene entweder 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.

Damit du die geeignete Implementierung ermitteln kannst, musst du zuerst ermitteln, in welche Kategorie dein Inventar fällt:

• Nur synchrone Buchungen aktivieren: Alle Händler und Dienstleistungen werden sofort bestätigt.
• Asynchrone Buchungen aktivieren: Für einige oder alle Händler und Dienstleistungen ist eine manuelle Bestätigung des Händlers erforderlich.

Kriterien für asynchrone Buchungen

• Asynchrone Buchungen können im Actions Center nicht geändert werden.
• Händler sollten die Buchung über das Onlinesystem des Partners (z.B. Hostbereich für das Restaurant) annehmen oder ablehnen können. Es ist nicht zulässig, den Händler im Namen des Nutzers anzurufen, um zu erfahren, ob der Händler eine Buchung annimmt oder ablehnt.
• Händler können keine alternativen Zeiten für Buchungen vorschlagen. Die Buchungsanfrage muss im ursprünglichen Status angenommen oder abgelehnt werden.

Nur synchrone Buchungen aktivieren

In der Standardimplementierung sind synchrone Buchungen voreingestellt. Weitere Informationen finden Sie in der Dokumentation zur End-to-End-Integration für Reservierungen.

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, in dem beschrieben wird, wie Buchungen dieses verfügbaren Slots bestätigt werden. Gib für jeden verfügbaren Slot den Wert confirmation_mode für Folgendes an:

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

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

Abbildung 1:Asynchroner Buchungsvorgang

1. Verfügbarkeitsfeeds wurden aktualisiert, sodass für jeden verfügbaren Slot der Bestätigungsmodus angegeben wird. Diese Informationen müssen im Feed vorhanden sein, damit wir dem Nutzer schon früh im Ablauf den asynchronen Charakter der Buchung erklären können.
2. Beim Aufrufen von BatchAvailabilityLookup oder CheckAvailability wird der Bestätigungsmodus übergeben. Idealerweise wird dann derselbe Bestätigungsmodus zurückgegeben. So wird sichergestellt, dass dem Nutzer die richtige Botschaft angezeigt wird.
3. Wenn CreateBooking aufgerufen wird, übergeben wir den Bestätigungsmodus, 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 Echtzeitaktualisierungen aktualisiert. Wenn Buchungen, die nicht zeitnah beantwortet werden, automatisch abgelehnt werden sollen, musst du dafür dieselbe Methode für Echtzeitaktualisierungen verwenden.

Verfügbarkeitsfeeds

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

Hinweis:Die confirmation_mode wird im Verfügbarkeitsbereich des Verfügbarkeitsfeeds und der Echtzeitaktualisierungen gespeichert. Für die Buchungsserver-APIs wird das Feld jedoch auf Slotebene gespeichert.

// 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 zwar davon ausgegangen, dass der Bestätigungsmodus synchron ist, wenn kein Modus angegeben ist. Es wird jedoch dringend empfohlen, explizit einen Modus anzugeben, da dadurch Unklarheiten 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"

Gib in BatchAvailabilityLookupResponse (BAL) oder CheckAvailabilityResponse (CA) dasselbe confirmation_mode-Objekt zurück, das im Verfügbarkeitsfeed angegeben und über BatchAvailabilityLookupRequest oder CheckAvailabilityRequest übergeben wird.

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

Achte darauf, mithilfe der folgenden Optionen den richtigen Status für die Buchung zurückzugeben:

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

Gib in der CreateBookingResponse den aktuellen confirmation_mode für den aggregierten Slot der Buchung zurück, der in „CreateBookingRequest“ angegeben ist. Wenn die Buchung asynchron ist, setze status außerdem auf PENDING_MERCHANT_CONFIRMATION. Achte darauf, dass die confirmation_mode vom Nutzer und von „Mit Google reservieren“ erwartet wird, 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": "[e-mail]",
      "family_name": "John",
      "given_name": "Smith",
      "telephone": "[phone]",
      "user_id": "2017492857928759285"
    },
    "payment_information": {
      "prepayment_status": "PREPAYMENT_NOT_PROVIDED"
    },
    "status": "PENDING_MERCHANT_CONFIRMATION"
  }
}

Synchronisieren

{
  "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": "[e-mail]",
      "family_name": "John",
      "given_name": "Smith",
      "telephone": "[phone]",
      "user_id": "2017492857928759285"
    },
    "payment_information": {
      "prepayment_status": "PREPAYMENT_NOT_PROVIDED"
    },
    "status": "CONFIRMED"
  }
}

UpdateBooking

In der ersten Version des asynchronen Modus werden Änderungen an vorhandenen Buchungen durch den Nutzer nicht unterstützt. Stattdessen muss der Nutzer die Buchung stornieren und eine neue Buchung erstellen.

Echtzeitaktualisierungen

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

Echtzeitaktualisierung für Inventar (ReplaceServiceAvailability oder BatchReplaceServiceAvailability)

Legen Sie mit der Methode availability.replace oder der Methode services.availability.replace confirmation_mode in 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 Methode bookings.patch der Booking Notification API vorgenommen werden.

Achten Sie beim Aktualisieren des Status darauf, den Feldnamen status in updateMask aufzunehmen.

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

Wenn eine Buchung fehlschlägt, setze den Buchungsstatus auf FAILED und gib das Attribut „booking_failure“ an. Ist als Status ein anderer Wert festgelegt, wird booking_failure ignoriert.

Hinweis:booking_failure-Felder werden als Abfrageargumente für die URL übergeben.

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 Buchungsstatus, die an Nutzer gesendet werden.

Hinweis:Neben den E-Mails für die folgenden Buchungsstatus werden auch Erinnerungs- und Feedback-E-Mails gesendet:

• PENDING_MERCHANT_CONFIRMATION
• CONFIRMED
• DECLINED_BY_MERCHANT
• FAILED
• CANCELED