Implementa il server di prenotazione

Devi configurare un server di prenotazione per consentire ad Actions Center di effettuare chiamate di ritorno per creare e aggiornare le prenotazioni per tuo conto.

• L'implementazione standard. In questo modo, il Centro azioni può creare appuntamenti, prenotazioni e prenotazioni con te per conto dell'utente.
• L'implementazione della lista d'attesa. Viene utilizzato quando partecipi al programma pilota della lista d'attesa. In questo modo, Actions Center può recuperare le stime di attesa e creare voci nella lista d'attesa per conto dell'utente. Per implementare un server di prenotazione per la lista d'attesa, consulta Implementare il server di prenotazione della lista d'attesa.

Consulta la documentazione del Partner Portal per scoprire come configurare la connessione ai server di prenotazione della sandbox e di produzione.

Implementa un'interfaccia API REST

Implementa un'interfaccia API basata su REST. In questo modo, Google può inviare richieste al server di prenotazione tramite HTTP.

Per iniziare, configura un server di prenotazione per lo sviluppo o la sandbox che possa essere collegato all'ambiente sandbox di Actions Center. Passa a un ambiente di produzione solo dopo aver testato completamente il server sandbox.

Metodi

Per ogni tipo di server di prenotazione, è necessario un insieme diverso di metodi API. Facoltativamente, puoi scaricare la definizione del servizio in formato proto per iniziare a utilizzare l'implementazione dell'API. Le tabelle seguenti mostrano i metodi per ogni implementazione e includono i link ai formati proto del servizio.

Implementazione standard
Definizione di servizio standard Scarica il file di definizione del servizio proto.

Metodo	Richiesta HTTP
HealthCheck	GET /v3/HealthCheck/
BatchAvailabilityLookup	POST /v3/BatchAvailabilityLookup/
CreateBooking	POST /v3/CreateBooking/
UpdateBooking	POST /v3/UpdateBooking/
GetBookingStatus	POST /v3/GetBookingStatus/
ListBookings	POST /v3/ListBookings/

Risorse API

Prenotazione

Nell'implementazione standard vengono utilizzati i seguenti tipi di risorse:

• Slot: uno spazio dell'inventario.
• Prenotazione: un appuntamento per uno spazio dell'inventario.

Flusso: crea una prenotazione

Questa sezione spiega come creare una prenotazione per l'implementazione standard.

Figura 1: flusso di lavoro per creare una prenotazione da uno slot

Quando un utente crea una prenotazione, Google ti invia il nome, il cognome, il numero di telefono e l'email dell'utente. Dal tuo punto di vista, questa prenotazione deve essere considerata come un pagamento senza registrazione, perché il Centro azioni non può cercare l'account dell'utente nel tuo sistema. Assicurati che la prenotazione finale sia identica alle prenotazioni dei tuoi commercianti provenienti dal tuo sistema di prenotazione. Il pagamento senza registrazione e gli indirizzi email alternativi sono supportati per impostazione predefinita per le prenotazioni non pagate.

Sicurezza e autenticazione

Tutte le comunicazioni con il server di prenotazione avvengono tramite HTTPS, pertanto è fondamentale che il server disponga di un certificato TLS valido che corrisponda al suo nome DNS. Per aiutarti a configurare il server, ti consigliamo di utilizzare uno strumento di verifica SSL/TLS disponibile pubblicamente, come SSL Server Test di Qualys.

Tutte le richieste che Google invierà al tuo server di prenotazione verranno autenticate utilizzando l'autenticazione di base HTTP. Le credenziali di autenticazione di base (nome utente e password) per il server di prenotazione possono essere inserite nella pagina Configurazione server di prenotazione del Partner Portal. Le password devono essere ruotate ogni sei mesi.

Nota: devi impostare il nome utente e la password per la sandbox e la produzione separatamente utilizzando il selettore di ambienti.

Implementazioni di skeleton di esempio

Per iniziare, dai un'occhiata ai seguenti scheletri di esempio di un server di prenotazione scritto per i framework Node.js e Java:

• Skeleton Node.js js-maps-booking-rest-server-v3-skeleton
• Skeleton Java java-maps-booking-rest-server-v3-skeleton

Questi server hanno metodi REST simulati.

Requisiti

Errori HTTP ed errori di logica di business

Quando il backend gestisce le richieste HTTP, possono verificarsi due tipi di errori.

• Errori relativi all'infrastruttura o a dati errati
  • Restituire questi errori al client con codici di errore HTTP standard. Consulta l'elenco completo dei codici di stato HTTP.
• Errori relativi alla logica di business
  • Restituire il codice di stato HTTP impostato su 200 OK e specificare l'errore della logica di business nel corpo della risposta. I tipi di errori di logica aziendale che puoi riscontrare sono diversi per i diversi tipi di implementazioni del server.

Per l'implementazione standard, i possibili errori di logica di business vengono rilevati in Booking Failure e restituiti nella risposta HTTP. È possibile che si verifichino errori di logica di business quando una risorsa viene creata o aggiornata. Ad esempio, quando gestisci i metodi CreateBooking o UpdatingBooking. Alcuni esempi, senza alcuna limitazione, sono:

• SLOT_UNAVAILABLE viene utilizzato se lo slot richiesto non è più disponibile.
• PAYMENT_ERROR_CARD_TYPE_REJECTED viene utilizzato se il tipo di carta di credito fornito non è accettato.

Identità

La comunicazione sulla rete non è sempre affidabile e Google potrebbe riprovare le richieste HTTP se non riceve risposta. Per questo motivo, tutti i metodi che modificano lo stato devono essere idempotenti:

• CreateBooking
• UpdateBooking

Per ogni messaggio di richiesta, ad eccezione di UpdateBooking, vengono inclusi token di iridemicità per identificare in modo univoco la richiesta. In questo modo puoi distinguere tra una chiamata REST ripetuta, con l'intento di creare una singola richiesta, e due richieste distinte. UpdateBooking è identificato in modo univoco dai rispettivi ID voce di prenotazione, pertanto nelle richieste non è incluso alcun token di irideologia.

Di seguito sono riportati alcuni esempi di come i server di prenotazione gestiscono l'idempotency:

• Una risposta HTTP CreateBooking corretta include la prenotazione creata. In alcuni casi, il pagamento viene elaborato nell'ambito del flusso di prenotazione. Se lo stesso CreateBookingRequest viene ricevuto una seconda volta (con lo stesso idempotency_token), deve essere restituito lo stesso CreateBookingResponse. Non viene creata una seconda prenotazione e all'utente viene addebitato un importo esattamente una volta, se applicabile.

  Tieni presente che se un tentativo di CreateBooking non va a buon fine e la stessa richiesta viene inviata di nuovo, in questo caso il tuo backend dovrebbe riprovare.

Il requisito di idempotenticità si applica a tutti i metodi che modificano lo stato.