Dodawanie rezerwacji asynchronicznych

Rezerwacje synchroniczne to rezerwacje, które są potwierdzane lub odrzucane w czasie rzeczywistym.

Rezerwacje asynchroniczne to rezerwacje, które sprzedawca potwierdza lub odrzuca w późniejszym terminie.

Rezerwacja jest określana jako synchroniczna lub asynchroniczna na poziomie dostępności. Oznacza to również, że w przypadku danego sprzedawcy i usługi mogą występować zarówno synchroniczne, jak i asynchroniczne przedziały czasowe.

Aby określić odpowiednią implementację, najpierw sprawdź, do której kategorii należą Twoje zasoby reklamowe:

Kryteria rezerwacji asynchronicznej

  • Modyfikowanie rezerwacji asynchronicznej w Centrum działań nie jest obsługiwane.
  • Sprzedawcy powinni mieć możliwość zaakceptowania lub odrzucenia rezerwacji w systemie online partnera (np. w panelu gospodarza restauracji). Dzwonienie do sprzedawcy w imieniu użytkownika w celu ustalenia, czy sprzedawca akceptuje lub odrzuca rezerwację, jest niedozwolone.
  • Propozycja sprzedawcy dotycząca nowego terminu rezerwacji nie jest obsługiwana. Prośbę o rezerwację należy zaakceptować lub odrzucić w pierwotnym stanie.

Włączanie tylko rezerwacji synchronicznych

Standardowa implementacja domyślnie obsługuje rezerwacje synchroniczne. Więcej informacji znajdziesz w dokumentacji integracji kompleksowej rezerwacji.

Włączanie rezerwacji asynchronicznej

Jeśli niektórzy lub wszyscy sprzedawcy korzystają z asynchronicznego procesu rezerwacji, należy wprowadzić te zmiany:

  • Tryb potwierdzenia: wszystkie reprezentacje przedziałów czasu dostępności zawierają teraz pole confirmation_mode, które opisuje sposób potwierdzania rezerwacji tego przedziału czasu dostępności. Określ confirmation_mode każdego przedziału dostępności w przypadku tych elementów:

    • W pliku danych o dostępności atrybut confirmation_mode jest określony na poziomie dostępności.
    • W metodach interfejsu Booking Server API wartość confirmation_mode jest określana na poziomie przedziału czasu.
    • W metodach interfejsu API do aktualizacji w czasie rzeczywistym wartość confirmation_mode jest określana na poziomie dostępności.
  • Stan rezerwacji: wszystkie reprezentacje rezerwacji zawierają pole status, które określa stan rezerwacji. Wprowadziliśmy 3 nowe wartości stanu asynchronicznego: PENDING_CONFIRMATION, DECLINED_BY_MERCHANT i FAILED. Używaj tych nowych wartości stanu podczas przetwarzania tworzenia, odrzucania i niepowodzeń rezerwacji asynchronicznych.
  • Aktualizacje rezerwacji: wszystkie asynchroniczne aktualizacje stanu rezerwacji należy zgłaszać za pomocą metody bookings.patch interfejsu Booking Notification API.

Diagram poniżej pokazuje, jak w typowym asynchronicznym procesie rezerwacji wykorzystywane są tryb potwierdzenia i stan rezerwacji.

Ilustracja 1. Asynchroniczny proces rezerwacji
Rysunek 1. Asynchroniczny proces rezerwacji
  1. Zaktualizowaliśmy pliki danych o dostępności, aby określić tryb potwierdzenia każdego przedziału czasowego. Ważne jest, aby te informacje były dostępne w pliku danych, dzięki czemu będziemy mogli wyjaśnić użytkownikowi asynchroniczny charakter rezerwacji na wczesnym etapie procesu.
  2. Gdy wywoływana jest funkcja BatchAvailabilityLookup lub CheckAvailability przekazujemy tryb potwierdzenia i najlepiej ten sam tryb potwierdzenia, który ma zostać zwrócony. Dzięki temu użytkownik zobaczy odpowiedni komunikat.
  3. Gdy wywoływana jest funkcja CreateBooking, przekazujemy tryb potwierdzenia, aby wskazać oczekiwany tryb potwierdzenia. Po przesłaniu asynchronicznego żądania rezerwacji zwracana jest rezerwacja ze stanem PENDING_MERCHANT_CONFIRMATION.
  4. Gdy sprzedawca zaakceptuje lub odrzuci prośbę o rezerwację, stan rezerwacji zostanie zaktualizowany za pomocą metody bookings.patch interfejsu API powiadomień o rezerwacji w czasie rzeczywistym. Jeśli chcesz automatycznie odrzucać rezerwacje, na które nie odpowiedziano w odpowiednim czasie, zrób to za pomocą tej samej metody aktualizacji w czasie rzeczywistym.

Pliki danych o dostępności

W pliku danych o dostępności określ, czy każde miejsce jest synchroniczne czy asynchroniczne. Aby to zrobić, ustaw nowe pole 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;
}

Jeśli nie określono trybu potwierdzenia, zakłada się, że jest on synchroniczny. Zdecydowanie zalecamy jednak jego wyraźne określenie, ponieważ pozwala to uniknąć nieporozumień związanych z przypadkowymi pominięciami.

Dane asynchroniczne

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

Synchronizacja

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

Asynchroniczne i synchroniczne

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

  ]
}

Serwer rezerwacji

BatchAvailabilityLookup lub CheckAvailability

W przypadku BatchAvailabilityLookupResponse (BAL) lub CheckAvailabilityResponse (CA) zwróć ten sam confirmation_mode, który jest określony w pliku danych o dostępności i przekazywany za pomocą BatchAvailabilityLookupRequest lub 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

Upewnij się, że zwracasz prawidłowy stan rezerwacji, korzystając z dostępnych opcji poniżej:

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

W CreateBookingResponse zwróć bieżący confirmation_mode dla zagregowanego przedziału rezerwacji podanego w CreateBookingRequest. Dodatkowo, gdy rezerwacja jest asynchroniczna, ustaw wartość status na PENDING_MERCHANT_CONFIRMATION. Upewnij się, że confirmation_mode jest tym, czego oczekuje użytkownik i usługa Zarezerwuj z Google, aby uniknąć wprowadzenia użytkownika w błąd.

Dane asynchroniczne

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

Synchronizacja

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

W pierwszej wersji asynchronicznego interfejsu API nie obsługujemy modyfikacji istniejącej rezerwacji przez użytkownika. Zamiast tego użytkownik powinien anulować rezerwację i utworzyć nową.

Aktualizacje w czasie rzeczywistym

Aby otrzymywać aktualizacje dostępności w czasie rzeczywistym, musisz określić confirmation_mode. Dotyczy to tych metod:

Zasoby reklamowe RTU (ReplaceServiceAvailability lub BatchReplaceServiceAvailability)

Używając metody availability.replace (batch) lub services.availability.replace, ustaw wartość confirmation_mode na CONFIRMATION_MODE_ASYNCHRONOUS w Availability.

Dane asynchroniczne

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

Synchronizacja

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

Asynchroniczne i synchroniczne

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

Asynchroniczne aktualizacje stanu rezerwacji należy wprowadzać za pomocą metody bookings.patch interfejsu Booking Notification API.

Aktualizując stan, pamiętaj, aby w updateMask uwzględnić nazwę pola status.

Stan Opis
POTWIERDZONO sprzedawca potwierdził rezerwację,
NIEPOWODZENIE partner nie mógł potwierdzić ani odrzucić rezerwacji u sprzedawcy;
DECLINED_BY_MERCHANT sprzedawca odrzucił rezerwację, 
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"}

W przypadku nieudanej rezerwacji ustaw stan rezerwacji na FAILED i określ booking_failure. Jeśli stan jest ustawiony na inną wartość, parametr booking_failure jest ignorowany.

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

Powiadomienia e-mail

W przypadku rezerwacji asynchronicznych użytkownicy mogą otrzymać 5 e-maili związanych ze stanem rezerwacji.

  • PENDING_MERCHANT_CONFIRMATION
  • CONFIRMED
  • DECLINED_BY_MERCHANT
  • FAILED
  • CANCELED