Aggiungere prenotazioni asincrone

Le prenotazioni sincrone sono definite come prenotazioni confermate o rifiutate in tempo reale.

Le prenotazioni asincrone sono definite come prenotazioni confermate o rifiutate dal commerciante in un secondo momento.

Una prenotazione viene specificata come sincrona o asincrona a livello di disponibilità. Ciò significa anche che per un determinato commerciante e servizio, potrebbero essere presenti fasce orarie di disponibilità sia sincrone che asincrone.

Per determinare l'implementazione appropriata, identifica prima la categoria in cui rientra il tuo inventario:

Criteri di prenotazione asincrona

  • La modifica di una prenotazione asincrona nel Centro azioni non è supportata.
  • I commercianti devono essere in grado di accettare o rifiutare la prenotazione tramite il sistema online del partner (ad es. il pannello dell'organizzatore per il ristorante). Chiamare il commerciante per conto dell'utente per determinare se il commerciante accetta o rifiuta una prenotazione non è consentito.
  • La proposta del commerciante di un nuovo orario di prenotazione non è supportata. La richiesta di prenotazione deve essere accettata o rifiutata nello stato originale.

Attivazione solo delle prenotazioni sincrone

L'implementazione standard prevede per impostazione predefinita le prenotazioni sincrone. Per ulteriori informazioni, consulta la documentazione relativa all'integrazione end-to-end di Reservations.

Attivare la prenotazione asincrona

Se alcuni o tutti i commercianti utilizzano un flusso di prenotazione asincrono, devono essere apportate le seguenti modifiche:

  • Modalità di conferma: tutte le rappresentazioni degli intervalli di disponibilità ora contengono un campo confirmation_mode che descrive la modalità di conferma delle prenotazioni di quell'intervallo di disponibilità. Specifica il valore confirmation_mode di ogni intervallo di disponibilità per quanto segue:

    • Nel feed della disponibilità, confirmation_mode è specificato a livello di disponibilità
    • Nei metodi dell'API Booking Server, confirmation_mode è specificato a livello di slot
    • Nei metodi dell'API Aggiornamenti in tempo reale, confirmation_mode è specificato a livello di disponibilità
  • Stato della prenotazione: tutte le rappresentazioni delle prenotazioni contengono un campo status che rappresenta lo stato della prenotazione. Sono stati introdotti tre nuovi valori di stato asincrono: PENDING_CONFIRMATION, DECLINED_BY_MERCHANT e FAILED. Utilizza questi nuovi valori di stato durante l'elaborazione delle prenotazioni asincrone create, rifiutate e non riuscite.
  • Aggiornamenti delle prenotazioni: tutti gli aggiornamenti asincroni dello stato delle prenotazioni devono essere segnalati tramite il metodo bookings.patch dell'API Booking Notification.

Il diagramma seguente mostra come vengono utilizzati la modalità di conferma e lo stato della prenotazione in una tipica interazione di prenotazione asincrona.

Figura 1: flusso di prenotazione asincrono
Figura 1: flusso di prenotazione asincrono
  1. I feed di disponibilità sono stati aggiornati in modo che sia specificata la modalità di conferma di ogni intervallo di disponibilità. È importante avere queste informazioni nel feed per poter spiegare all'utente la natura asincrona della prenotazione all'inizio del flusso.
  2. Quando viene chiamato BatchAvailabilityLookup o CheckAvailability trasmettiamo la modalità di conferma e, idealmente, la stessa modalità di conferma da restituire. In questo modo, all'utente vengono mostrati i messaggi appropriati.
  3. Quando viene chiamato CreateBooking trasmettiamo la modalità di conferma per indicare la modalità di conferma prevista. Quando viene inviata la richiesta di prenotazione asincrona, la prenotazione viene restituita con lo stato PENDING_MERCHANT_CONFIRMATION.
  4. Quando il commerciante accetta o rifiuta una richiesta di prenotazione, lo stato della prenotazione viene aggiornato tramite il metodo bookings.patch dell'API di notifica delle prenotazioni con aggiornamento in tempo reale. Se vuoi rifiutare automaticamente le prenotazioni a cui non è stata data risposta in modo tempestivo, utilizza lo stesso metodo di aggiornamento in tempo reale.

Feed di disponibilità

Nel feed di disponibilità, specifica se ogni slot è sincrono o asincrono. Per farlo, imposta il nuovo campo 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;
}

Sebbene si presuma che la modalità di conferma sia sincrona se non viene specificata alcuna modalità, è vivamente consigliato di specificare esplicitamente una modalità, poiché questo elimina qualsiasi confusione sulle omissioni accidentali.

Asinc

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

Sincronizza

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

Asincrono e sincronizzazione

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

  ]
}

Server di prenotazione

BatchAvailabilityLookup o CheckAvailability

In BatchAvailabilityLookupResponse (BAL) o CheckAvailabilityResponse (CA), restituisci lo stesso confirmation_mode specificato nel feed di disponibilità e trasmesso tramite BatchAvailabilityLookupRequest o 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

Assicurati di restituire lo stato corretto della prenotazione utilizzando le opzioni disponibili riportate di seguito:

// 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 CreateBookingResponse, restituisci il confirmation_mode corrente per lo spazio aggregato della prenotazione fornito in CreateBookingRequest. Inoltre, quando la prenotazione è asincrona, imposta status su PENDING_MERCHANT_CONFIRMATION. Assicurati che confirmation_mode sia ciò che l'utente e Prenota con Google si aspettano per evitare di confondere l'utente.

Asinc

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

Sincronizza

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

Nella versione iniziale di Async, le modifiche apportate dagli utenti a una prenotazione esistente non sono supportate. L'utente deve invece annullare la prenotazione e crearne una nuova.

Aggiornamenti in tempo reale

Per gli aggiornamenti in tempo reale delle disponibilità, deve essere specificato confirmation_mode. Ciò si applica ai seguenti metodi:

RTU dell'inventario (ReplaceServiceAvailability o BatchReplaceServiceAvailability)

Utilizzando il metodo availability.replace (batch) o il metodo services.availability.replace, imposta confirmation_mode su CONFIRMATION_MODE_ASYNCHRONOUS in Availability

Asinc

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

Sincronizza

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

Asincrono e sincronizzazione

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

API Booking Notification

Gli aggiornamenti asincroni dello stato di una prenotazione devono essere eseguiti tramite il metodo bookings.patch dell'API di notifica delle prenotazioni.

Quando aggiorni lo stato, assicurati di includere il nome del campo status in updateMask.

Stato Descrizione
CONFERMATA Il commerciante ha confermato la prenotazione
ERRORE Il partner non è riuscito a confermare o rifiutare la prenotazione con il commerciante
DECLINED_BY_MERCHANT Il commerciante ha rifiutato la prenotazione 
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"}

In caso di errore di prenotazione, imposta lo stato della prenotazione su FAILED e specifica booking_failure. Se lo stato è impostato su un valore diverso, booking_failure viene ignorato.

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

Notifiche email

Per le prenotazioni asincrone, vengono inviate agli utenti cinque potenziali email relative allo stato della prenotazione.

  • PENDING_MERCHANT_CONFIRMATION
  • CONFIRMED
  • DECLINED_BY_MERCHANT
  • FAILED
  • CANCELED