Devi creare un server di prenotazione per consentire al Centro azioni di effettuare richiamate per creare e aggiornare le prenotazioni per tuo conto.
- Implementazione standard. In questo modo il Centro azioni può creare appuntamenti e prenotazioni per conto dell'utente.
Consulta la documentazione del Portale partner per scoprire come configurare la connessione ai server di prenotazione della sandbox e della produzione.
Implementare un'interfaccia API REST
Implementare un'interfaccia API basata su REST. In questo modo Google può inviare richieste del server di prenotazione tramite HTTP.
Per iniziare, configura un server di prenotazione per lo sviluppo o la sandbox che possa essere connesso all'ambiente sandbox del Centro Azioni. Passa a un ambiente di produzione solo dopo aver completato il test del server sandbox.
Metodi
Per ogni tipo di server di prenotazione, devi disporre di un insieme diverso di metodi API. Facoltativamente, puoi scaricare la definizione del servizio in formato proto per iniziare l'implementazione dell'API. Le seguenti tabelle mostrano i metodi per ciascuna implementazione e includono link ai formati dei prototipi di servizi.
Implementazione standard |
---|
Definizione di servizio standard Scarica il file di definizione del servizio proto. |
Metodo | Richiesta HTTP |
---|---|
HealthCheck | OTTIENI /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:
- Area: un'area dell'inventario.
- Prenotazione: un appuntamento per uno spazio di inventario.
Flusso: creare 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](https://developers-dot-devsite-v2-prod.appspot.com/static/actions-center/images/rest_api_v3_booking_flow_1.png?authuser=0000&hl=it)
Quando un utente crea una prenotazione, Google ti invia nome, cognome, numero di telefono e indirizzo email dell'utente. Dal tuo punto di vista, questa prenotazione deve essere considerata un pagamento senza registrazione, perché il Centro azioni non può cercare l'account dell'utente nel tuo sistema. Assicurati che la prenotazione finale sembri identica a quelle dei commercianti provenienti dal tuo sistema di prenotazione.
Sicurezza e autenticazione
Tutte le comunicazioni con il tuo server di prenotazione avvengono tramite HTTPS, quindi è essenziale che il tuo server abbia un certificato TLS valido che corrisponda al suo nome DNS. Per configurare il server, ti consigliamo di utilizzare uno strumento di verifica SSL/TLS disponibile pubblicamente, come Qualys' SSL Server Test.
Tutte le richieste inviate da Google al tuo server di prenotazione saranno autenticate mediante l'autenticazione di base HTTP. Le credenziali di autenticazione di base (nome utente e password) del tuo server di prenotazione possono essere inserite nella pagina di configurazione del server di prenotazione all'interno del Portale partner. Le password devono essere ruotate ogni sei mesi.
Esempi di implementazioni di scheletri
Per iniziare, controlla i seguenti scheletri di esempio di un server di prenotazione scritto per i framework Node.js e Java:
- Struttura di Node.js js-maps-booking-rest-server-v3-skeleton
- Scheletro Java java-maps-booking-rest-server-v3-skeleton
Questi server hanno eliminato metodi REST.
Requisiti
Errori HTTP ed errori della logica di business
Quando il backend gestisce le richieste HTTP, possono verificarsi due tipi di errori.
- Errori relativi all'infrastruttura o dati errati
- Restituisci questi errori al client con i 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 si possono verificare variano in base ai diversi tipi di implementazioni dei server.
- Restituisce il codice di stato HTTP impostato su
Per l'implementazione Standard, i possibili errori della logica di business vengono acquisiti in Errore di prenotazione e vengono restituiti nella risposta HTTP. Quando una risorsa viene creata o aggiornata, si possono verificare errori di logica di business. 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 viene accettato.
Idempotenza
La comunicazione sulla rete non è sempre affidabile e Google potrebbe ritentare le richieste HTTP se non viene ricevuta alcuna risposta. Per questo motivo, tutti i metodi che cambiano stato devono essere idempotenti:
CreateBooking
UpdateBooking
Per ogni messaggio di richiesta tranne UpdateBooking
, vengono inclusi i token di idempotenza per identificare in modo univoco la richiesta. Ciò consente di distinguere tra una chiamata REST riprovata, con l'intento di creare una singola richiesta, e due richieste separate.
UpdateBooking
è identificato
in modo univoco rispettivamente dai relativi ID delle voci di prenotazione, quindi
nelle richieste non è incluso alcun token di idempotenza.
Di seguito sono riportati alcuni esempi di come i server di prenotazione gestiscono l'idempotenza:
Una risposta HTTP
CreateBooking
riuscita include la prenotazione creata. In alcuni casi, il pagamento viene elaborato nell'ambito del flusso di prenotazione. Se lo stessoCreateBookingRequest
viene ricevuto una seconda volta (con lo stessoidempotency_token
), è necessario restituire lo stessoCreateBookingResponse
. Non viene creata una seconda prenotazione e l'importo viene addebitato all'utente 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 backend dovrebbe riprovare.
Il requisito di idempotenza si applica a tutti i metodi che cambiano stato.