Asynchrone Buchungen hinzufügen

Synchrone Buchungen werden in Echtzeit bestätigt oder abgelehnt.

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

Eine Buchung wird auf Verfügbarkeitsebene entweder als synchron oder asynchron angegeben. Daher können für einen bestimmten Händler und eine Dienstleistung sowohl synchrone als auch asynchrone verfügbare Slots vorhanden sein.

Um die geeignete Implementierung zu finden, musst du zuerst ermitteln, zu welcher Kategorie dein Inventar gehört:

Kriterien für asynchrone Buchungen

  • Asynchrone Buchungen können im Actions Center nicht geändert werden.
  • Händler müssen die Buchung über das Onlinesystem des Partners annehmen oder ablehnen können (z.B. über den Gastgeberbereich für das Restaurant). Es ist nicht zulässig, den Händler für den Nutzer anzurufen, um zu erfragen, ob er eine 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 in der End-to-End-Integrationsdokumentation für Google Kalender.

Asynchrone Buchung aktivieren

Wenn einige oder alle Händler einen asynchronen Buchungsablauf verwenden, müssen folgende Änderungen vorgenommen werden:

  • Bestätigungsmodus:Alle Darstellungen verfügbarer Slots enthalten jetzt das Feld confirmation_mode. Dort wird beschrieben, wie Buchungen des entsprechenden Slots bestätigt werden. Gib den Bestätigungsmodus (confirmation_mode) jedes verfügbaren Slots so an:

    • Im Verfügbarkeitsfeed wird confirmation_mode auf der Verfügbarkeitsebene angegeben.
    • In den API-Methoden des Buchungsservers wird confirmation_mode auf Slot-Ebene angegeben.
    • In den API-Methoden für Echtzeitaktualisierungen wird confirmation_mode auf der Verfügbarkeitsebene angegeben.
  • Buchungsstatus:Alle Buchungsdarstellungen 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 sie, wenn du Erstellungen, Ablehnungen und Fehler asynchroner Buchungen verarbeitest.
  • Buchungsaktualisierungen:Alle asynchronen Aktualisierungen des Buchungsstatus müssen über die bookings.patch-Methode der Booking Notification API gemeldet werden.

Im folgenden Diagramm siehst du, wie der Bestätigungsmodus und der Buchungsstatus in einer typischen asynchronen Buchungsinteraktion verwendet werden.

Abbildung 1: Asynchroner Buchungsablauf
Abbildung 1:Asynchroner Buchungsablauf
  1. Verfügbarkeitsfeeds wurden aktualisiert. Jetzt wird der Bestätigungsmodus jedes verfügbaren Slots angegeben. Diese Informationen müssen im Feed enthalten sein, damit wir dem Nutzer die asynchrone Buchung schon früh im Ablauf erklären können.
  2. Wenn BatchAvailabilityLookup oder CheckAvailability aufgerufen wird, wird der Bestätigungsmodus übergeben und im Idealfall derselbe Bestätigungsmodus zurückgegeben. Dadurch wird sichergestellt, dass der Nutzer die richtige Nachricht sieht.
  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 akzeptiert oder ablehnt, wird der Buchungsstatus über die bookings.patch-Methode 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.

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

Auch wenn standardmäßig vom synchronen Buchungsmodus ausgegangen wird, solltest du explizit einen Modus angeben, damit es keine Probleme mit versehentlichen Auslassungen gibt.

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) denselben confirmation_mode zurück, der im Verfügbarkeitsfeed angegeben ist und über BatchAvailabilityLookupRequest oder CheckAvailabilityRequest weitergegeben 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

Stell mithilfe der folgenden Optionen sicher, dass der richtige Status für die Buchung zurückgegeben wird:

// 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 CreateBookingResponse den aktuellen confirmation_mode für den aggregierten Slot der Buchung zurück, der in CreateBookingRequest angegeben ist. Wenn die Buchung asynchron ist, musst du außerdem status auf PENDING_MERCHANT_CONFIRMATION setzen. Achte darauf, dass der Wert von 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": "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 Bestätigungsmodus werden Änderungen vorhandener Buchungen durch den Nutzer nicht unterstützt. Stattdessen muss der Nutzer die Buchung stornieren und dann eine neue Buchung erstellen.

Echtzeitaktualisierungen

Für Aktualisierungen der Verfügbarkeit in Echtzeit muss confirmation_mode angegeben werden. Das gilt für folgende Methoden:

Inventar – Echtzeitaktualisierung (ReplaceServiceAvailability oder BatchReplaceServiceAvailability)

Verwenden Sie die availability.replace-Methode (Batch) oder die services.availability.replace-Methode, um in Availability confirmation_mode auf CONFIRMATION_MODE_ASYNCHRONOUS festzulegen.

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 von Buchungsstatus müssen über die bookings.patch-Methode der Booking Notification API vorgenommen werden.

Beim Aktualisieren des Status musst du den Namen des Felds status in 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"}

Wenn eine Buchung fehlschlägt, setze den Buchungsstatus auf FAILED und gib einen Wert für „booking_failure“ an. Ist der Status auf einen anderen Wert gesetzt, 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 E-Mails zum Buchungsstatus, die an Nutzer gesendet werden können.

  • PENDING_MERCHANT_CONFIRMATION
  • CONFIRMED
  • DECLINED_BY_MERCHANT
  • FAILED
  • CANCELED