Implementare il server di prenotazione

Devi consentire un server di prenotazione per consentire a Prenota con Google di effettuare chiamate per creare e aggiornare prenotazioni per tuo conto.

• Implementazione standard. In questo modo, Prenota con Google può creare appuntamenti, prenotazioni e prenotazioni per conto dell'utente.

Consulta la documentazione del portale partner per scoprire come configurare la connessione ai server di prenotazione sandbox e di produzione.

Implementare un'interfaccia API REST

Implementa un'interfaccia API basata su REST che consente a Google di inviare richieste del server di prenotazione tramite HTTP.

Per iniziare, configura un server di sviluppo o di prenotazione sandbox che possa essere connesso all'ambiente sandbox di Prenota con Google. Passa a un ambiente di produzione solo dopo che il server sandbox è stato completamente testato.

Metodi

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

Implementazione standard
Definizione del servizio standard: scarica il file di definizione del servizio Protocollo.

Metodo	Richiesta HTTP
Controllo di integrità	GET /v3/HealthCheck/
Verifica disponibilità in batch	POST /v3/BatchAvailabilitySearch/
Creazione di una prenotazione	POST /v3/CreateBooking/
Aggiornamento Booking	POST /v3/UpdateBooking/
StatoGetBooking	POST /v3/GetBookingStatus/
Listbooking	POST /v3/ListBookings/

Risorse API

Prenotazione

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

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

Flusso: creare una prenotazione

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

Flusso di lavoro 1: 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'indirizzo email dell'utente. Dal tuo punto di vista, questa prenotazione deve essere considerata come un pagamento senza registrazione, perché Prenota con Google non può cercare l'account dell'utente nel tuo sistema. Assicurati che la prenotazione finale appaia identica a quelle dei commercianti che provengono dal tuo sistema di prenotazione. Il pagamento senza registrazione e le email alternative sono supportate per impostazione predefinita per le prenotazioni non a pagamento.

Sicurezza e autenticazione

Tutte le comunicazioni con il server di prenotazione avvengono tramite HTTPS, quindi è essenziale che il server abbia un certificato TLS valido che corrisponda al proprio nome DNS. Per facilitare la configurazione del server, ti consigliamo di utilizzare uno strumento di verifica SSL/TLS disponibile pubblicamente, come Test del server SSL di Qualys.

Tutte le richieste che Google effettuerà al tuo server di prenotazione verranno autenticate tramite l'autenticazione HTTP di base. Puoi inserire le credenziali di autenticazione di base (nome utente e password) per il server di prenotazione nella pagina Configurazione del server di prenotazione all'interno del Portale partner. Le password devono essere ruotate ogni sei mesi.

Nota: devi impostare il nome utente e la password per Sandbox e Produzione separatamente utilizzando il Selettore di ambiente.

Esempi di implementazione di scheletri

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

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

Questi server hanno utilizzato metodi REST.

Requisiti

Errori HTTP ed errori logici aziendali

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
  • Restituisce il codice di stato HTTP impostato su 200 OK e specifica l'errore della logica di business nel corpo della risposta. I tipi di errori della logica di business che possono verificarsi sono diversi a seconda del tipo di implementazione del server.

Per l'implementazione standard, i possibili errori della logica di business vengono acquisiti in Errore di prenotazione e vengono restituiti nella risposta HTTP. Gli errori di logica di business possono verificarsi 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.
• La carta PAYMENT_ERROR_CARD_TYPE_REJECTED viene utilizzata se il tipo di carta di credito fornito non viene accettato.

Idemponze

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

• CreateBooking
• UpdateBooking

Per ogni messaggio di richiesta tranne UpdateBooking, sono inclusi i token di idemponcy per identificare in modo univoco la richiesta. Questo ti consente di distinguere tra una chiamata REST ritentata, con l'intento di creare una singola richiesta, e due richieste separate. UpdateBooking è identificato in modo univoco rispettivamente dai rispettivi ID voce di prenotazione, quindi nelle richieste non è incluso alcun token di identificazione.

Ecco alcuni esempi di come i server di prenotazione gestiscono l'idempotenze:

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

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

Il requisito di idempotency si applica a tutti i metodi che mutano stato.