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 też, że w przypadku danego sprzedawcy i usługi mogą występować zarówno synchroniczne, jak i asynchroniczne sloty dostępności.

Aby określić odpowiednią implementację, najpierw określ, do której kategorii należy Twój zasób reklamowy:

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 w przypadku restauracji). Niedozwolone jest dzwonienie do sprzedawcy w imieniu użytkownika w celu ustalenia, czy sprzedawca akceptuje czy odrzuca rezerwację.
  • Propozycja sprzedawcy dotycząca nowego czasu rezerwacji nie jest obsługiwana. prośba o rezerwację musi zostać zaakceptowana lub odrzucona w pierwotnym stanie;

Włączanie rezerwacji synchronicznych

Standardowa implementacja domyślnie korzysta z rezerwacji synchronicznych. Więcej informacji znajdziesz w dokumentacji dotyczącej kompleksowej integracji z rezerwacjami.

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, jak są potwierdzane rezerwacje w ramach danego przedziału czasu dostępności. Określ confirmation_mode każdego przedziału dostępności dla:

    • 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 slotu.
    • W metodach interfejsu API Aktualizacje w czasie rzeczywistym parametr confirmation_mode jest określony na poziomie dostępności.
  • Stan rezerwacji: wszystkie reprezentacje rezerwacji zawierają pole status, które przedstawia 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 utworzeń, odrzuceń i błędów 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 tryb potwierdzenia i stan rezerwacji są używane w typowej asynchronicznej interakcji z rezerwacją.

Rysunek 1. Proces rezerwacji asynchronicznej
Rysunek 1. Asynchroniczny proces rezerwacji
  1. Pliki danych o dostępności zostały zaktualizowane, aby umożliwić określenie trybu potwierdzenia dla każdego okna dostępności. Te informacje są ważne, ponieważ umożliwiają nam wyjaśnienie użytkownikowi asynchronicznego charakteru rezerwacji na wczesnym etapie procesu.
  2. Gdy wywołana zostanie funkcja BatchAvailabilityLookup lub CheckAvailability przekazywany jest tryb potwierdzenia, który powinien być taki sam w przypadku zwracania. Dzięki temu użytkownik zobaczy odpowiedni komunikat.
  3. Gdy wywoływana jest funkcja CreateBooking, przekazujemy tryb potwierdzenia, aby wskazać oczekiwany tryb potwierdzenia. Gdy asynchroniczne żądanie rezerwacji zostanie przesłane, rezerwacja zostanie zwrócona 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 Booking Notification API. Jeśli chcesz automatycznie odrzucać rezerwacje, na które nie udało Ci się odpowiedzieć w sposób terminowy, 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żdy slot jest synchroniczny czy asynchroniczny. 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;
}

Chociaż w przypadku braku trybu zakłada się, że jest on synchroniczny, zdecydowanie zalecamy jawne określenie trybu, ponieważ eliminuje to wszelkie wątpliwości dotyczące przypadkowych pomijań.

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

Asynchronicznie i synchronicznie

{
  "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) zwracaj 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 CreateBookingResponsezwracaj bieżącą wartość confirmation_mode dla zbiorczego przedziału czasowego rezerwacji podanego w CreateBookingRequest. Dodatkowo, jeśli rezerwacja jest asynchroniczna, ustaw parametr status na PENDING_MERCHANT_CONFIRMATION. Upewnij się, że confirmation_mode jest tym, czego oczekują użytkownik i Reserve with Google, aby uniknąć wprowadzania 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 asynchroniczności nie można modyfikować istniejących rezerwacji. Użytkownik powinien anulować rezerwację i utworzyć nową.

Aktualizacje w czasie rzeczywistym

Aby otrzymywać bieżące informacje o dostępności, należy podać confirmation_mode. Dotyczy to tych metod:

RTU zasobów reklamowych (ReplaceServiceAvailability lub BatchReplaceServiceAvailability)

Używając metody availability.replace (grupowej) lub services.availability.replace, ustaw wartość confirmation_mode na CONFIRMATION_MODE_ASYNCHRONOUS w sekcji 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"
        }
      ]
    }
  ]
}

Asynchronicznie i synchronicznie

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

Niesynchroniczne zmiany stanu rezerwacji należy wprowadzać za pomocą metody bookings.patch interfejsu Notification API.

Podczas aktualizowania stanu pamiętaj, aby w polu updateMask podać 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 niepowodzenia rezerwacji ustaw stan rezerwacji na FAILED i określ booking_failure. Jeśli stan ma 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 dotyczących stanu rezerwacji.

  • PENDING_MERCHANT_CONFIRMATION
  • CONFIRMED
  • DECLINED_BY_MERCHANT
  • FAILED
  • CANCELED