Attivazione delle prenotazioni asincrone

Nota: se vuoi abilitare le prenotazioni asincrone, rivolgiti al tuo contatto Google. Inoltre, le prenotazioni asincrone sono supportate solo dalle integrazioni dell'API v3 basate su REST.

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

Le prenotazioni asincrone sono definite come prenotazioni che il commerciante conferma o rifiuta 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 un servizio potrebbero esistere aree di disponibilità sincrone e asincrone.

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

• Abilitare solo le prenotazioni sincrone: tutti i commercianti e i servizi vengono immediatamente confermati.
• Abilitare le prenotazioni asincrone: alcuni o tutti i commercianti e i servizi richiedono la conferma manuale del commerciante.

Criteri di prenotazione asincroni

• La modifica di una prenotazione asincrona su Prenota con Google non è supportata.
• Le prenotazioni asincrone che richiedono pagamenti non sono supportate.
• I commercianti devono essere in grado di accettare o rifiutare la prenotazione tramite il sistema online del partner (ad es. il pannello host per il ristorante). Chiamare il commerciante per conto dell'utente per determinare se il commerciante accetta o rifiuta una prenotazione non consentito.
• La proposta di un nuovo orario per la prenotazione del commerciante non è supportata. La richiesta di prenotazione deve essere accettata o rifiutata nello stato originale.

Abilitare solo le prenotazioni sincrone

L'implementazione standard utilizza per impostazione predefinita le prenotazioni sincrone. Consulta la guida all'integrazione end-to-end per ulteriori informazioni.

Attivazione della prenotazione asincrona

Se alcuni o tutti i commercianti utilizzano un flusso di prenotazione asincrono, è necessario apportare le seguenti modifiche:

• Modalità di conferma: tutte le rappresentazioni degli slot di disponibilità ora contengono un campo confirmation_mode che descrive come le prenotazioni di tale slot di disponibilità vengono confermate. Specifica il confirmation_mode di ogni slot di disponibilità per quanto segue:

  • Nel feed di disponibilità, l'attributo confirmation_mode è specificato al livello di disponibilità
  • Nei metodi API Booking Server, confirmation_mode è specificato a livello di slot
  • Nei metodi dell'API Real-Time Updates, 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 asincroni: PENDING_CONFIRMATION, DECLINED_BY_MERCHANT e FAILED. Utilizza questi nuovi valori di stato durante l'elaborazione di creazioni, rifiuti e errori delle prenotazioni asincrone.
• Aggiornamenti sulla prenotazione: tutti gli aggiornamenti asincroni allo stato delle prenotazioni devono essere segnalati tramite il metodo bookings.patch dell'API Booking Notification.

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

Figura 1. Flusso di prenotazione asincrono

1. I feed di disponibilità sono stati aggiornati in modo da specificare la modalità di conferma di ogni slot di disponibilità. È importante inserire queste informazioni nel feed per consentirci di spiegare la natura asincrona della prenotazione all'utente nella fase iniziale del flusso.
2. Quando viene richiamato BatchAvailabilityLookup o CheckAvailability, trasmettiamo la modalità di conferma e possibilmente la stessa modalità di conferma da restituire. In questo modo l'utente visualizza il messaggio appropriato.
3. Quando CreateBooking viene richiamata, passiamo la modalità di conferma per indicare la modalità di conferma anticipata. Quando viene inviata la richiesta di prenotazione asincrona, viene restituita la prenotazione 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 Booking Notification in tempo reale. Se vuoi rifiutare automaticamente le prenotazioni a cui non viene data risposta tempestiva, 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.

Nota: il campo confirmation_mode viene archiviato nella sezione della disponibilità dei feed di disponibilità e degli aggiornamenti in tempo reale, ma questo campo viene memorizzato a livello di slot per le API Booking Server.

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

Anche se si presume che la modalità di conferma sia sincrona se non viene specificata alcuna modalità, è vivamente consigliato specificare una modalità esplicita, in modo da rimuovere qualsiasi confusione riguardo a 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"
    }
  ]
}

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

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

BatchAvailabilitySearch o CheckAvailability

In BatchAvailabilityLookupResponse (BAL) o CheckAvailabilityResponse (CA), restituisci lo stesso confirmation_mode specificato nel feed di disponibilità e trasmetti tramite BatchAvailabilityLookupRequest o CheckAvailabilityRequest.

Asal BAL

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

Sincronizzazione BAL

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

Asincrono CA

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

Sincronizzazione CA

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

Crea prenotazione

Assicurati di restituire lo stato corretto della prenotazione utilizzando le opzioni disponibili 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;
}

Nella CreateBookingResponse, restituisce l'attuale confirmation_mode per l'area aggregata della prenotazione fornita in CreateBookingRequest. Inoltre, quando la prenotazione è asincrona, imposta status su PENDING_MERCHANT_CONFIRMATION. Assicurati che l'elemento confirmation_mode sia ciò che l'utente e ciò che Prenota con Google si aspetta di 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": "[e-mail]",
      "family_name": "John",
      "given_name": "Smith",
      "telephone": "[phone]",
      "user_id": "2017492857928759285"
    },
    "payment_information": {
      "prepayment_status": "PREPAYMENT_NOT_PROVIDED"
    },
    "status": "PENDING_MERCHANT_CONFIRMATION"
  }
}

Sincronizzazione

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

Aggiornamento prenotazione

Nella release iniziale di un asincrono, le modifiche degli utenti a una prenotazione esistente non sono supportate. L'utente deve invece annullare la prenotazione e crearne una nuova.

Aggiornamenti in tempo reale

Per aggiornamenti in tempo reale delle disponibilità, è necessario specificare confirmation_mode. Questo vale per i seguenti metodi:

RTU dell'inventario (SostituisciServiceAvailability o BatchSostituisciServiceAvailability)

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

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_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 a uno stato della prenotazione devono essere effettuati tramite il metodo dell'API Bookings patching.patch di Booking.

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

Stato	Descrizione
CONFERMATO	il commerciante ha confermato la prenotazione
ERRORE	il partner non ha potuto 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 il valore di collection_failure. Se lo stato è impostato su qualsiasi altro valore, il valore di booking_failure viene ignorato.

Nota: i campi booking_failure vengono passati come argomenti di query nell'URL.

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, ci sono cinque potenziali email relative allo stato della prenotazione che vengono inviate agli utenti.

Nota: verranno inviate le email di promemoria e feedback oltre alle email corrispondenti ai seguenti stati della prenotazione:

• PENDING_MERCHANT_CONFIRMATION
• CONFIRMED
• DECLINED_BY_MERCHANT
• FAILED
• CANCELED