Server partner

Per integrare le informazioni su prezzi e disponibilità, i partner dovranno implementare l'API Partner. Questa interfaccia è basata su REST e consente a Google di inviare chiamate live tramite HTTP. Mentre i dettagli dei singoli metodi API sono descritti nella sezione Riferimento, puoi trovare informazioni sui problemi trasversali più avanti.

Formato di richiesta e risposta

Inizialmente saranno supportati solo i formati JSON. Se sono necessari formati aggiuntivi per richieste o risposte, contatta il team di Travel Transport all'indirizzo [e-mail] per discutere del tuo caso d'uso.

Le richieste verranno inviate utilizzando il metodo HTTP POST, con il messaggio di richiesta nel corpo della richiesta POST.

Tieni presente che, per chiarezza strutturale, la documentazione dell'interfaccia API viene fornita come definizioni dei messaggi di buffer del protocollo e la traduzione di una definizione di messaggio di buffer del protocollo in un oggetto JSON è definita dal mapping JSON canonico, utilizzando le opzioni per emettere campi con valori predefiniti e per utilizzare i nomi dei campi proto anziché i nomi lowerCamelCase.

Importante: è consigliabile utilizzare le librerie protocol buffer e le utilità JsonFormat incluse per API type-safe che garantiscono la produzione di risposte sintatticamente corrette. Le definizioni enum mostrate nella documentazione escludono il valore UNSPECIFIED. Questi devono essere aggiunti quando si utilizzano direttamente i protobuf.

Autenticazione

Google supporta l'autenticazione digest HTTP e l'autenticazione con certificato client. Tutte le chiamate HTTP dell'API Partner utilizzano l'autenticazione HTTP Digest (con nome utente e password) o l'autenticazione del certificato client. Il partner deve fornire a Google un nome utente e una password (vedi Configurazione partner) o un certificato client SSL, rispettivamente.

Codici di stato e gestione degli errori

In generale, nelle risposte HTTP possono essere restituiti i seguenti codici di stato:

Codice HTTP	Descrizione HTTP	Note
2xx	Ok	Non è un errore; viene restituito in caso di esito positivo. Il corpo della risposta dovrebbe contenere un risultato positivo (ad es. TripOptionsResult), non una risposta di errore.
400	Richiesta non valida	La richiesta ricevuta non è valida. Le risposte di errore specifiche del metodo devono essere utilizzate per restituire ulteriori dettagli sull'errore nel corpo della risposta. L'errore HTTP 400 deve essere utilizzato in genere solo se Google ha commesso un errore tecnico (ad es. un campo denominato in modo errato in una richiesta).
403	Vietato	Autorizzazione negata/vietata (il chiamante è noto e rifiutato). Questa risposta non deve essere utilizzata per i rifiuti causati dall'esaurimento di alcune risorse (utilizza Troppe richieste per questi errori). Forbidden non deve essere utilizzato se il chiamante non può essere identificato (utilizza Unauthorized per questi errori).
404	Non trovato	Impossibile trovare la risorsa richiesta. Le risposte di errore specifiche del metodo devono essere utilizzate per restituire ulteriori dettagli sull'errore nel corpo della risposta.
429	Troppe richieste	Alcune risorse sono esaurite, ad esempio una quota per utente.
500	Errore interno del server	Errori interni. Ciò significa che alcuni invarianti previsti dal sistema sottostante sono stati violati. Questo codice di errore è riservato a errori gravi e indica un bug nell'implementazione del server API del partner.
503	Servizio non disponibile	Il servizio non è disponibile. Si tratta molto probabilmente di una condizione temporanea, che può essere corretta riprovando con un backoff.
504	Timeout gateway	La scadenza è terminata prima che l'operazione potesse essere completata. Per le operazioni che modificano lo stato del sistema, questo errore potrebbe essere restituito anche se l'operazione è stata completata correttamente. Ad esempio, una risposta riuscita da un server potrebbe essere stata ritardata abbastanza a lungo da far scadere il termine.

Tieni presente che per tutte le precondizioni, gli argomenti non validi o gli errori di tipo "Non trovato":

• devono essere utilizzate le risposte o i messaggi di errore specifici del metodo definiti nelle API.
• deve essere utilizzato il codice HTTP corretto, come specificato nei codici specifici del metodo (vedi ad es. TripOptionsErrorType)

Ciò consente di fornire informazioni più dettagliate su questi tipi di errori. Queste informazioni possono essere utilizzate per:

• Determinare se è possibile riprovare a eseguire un'operazione in caso di errore
  • SEGMENT_KEY_NOT_FOUND non può essere riprovato.
• Correggere le informazioni obsolete
  • Unavailable.Reason.CANCELED indica che la corsa deve essere rimossa (tieni presente che fa parte di una risposta corretta)
  • Unavailable.Reason.TEMPORARILY_UNAVAILABLE, nonché i codici di errore SEGMENT_KEY_NOT_FOUND, SUBOPTIMAL_ITINERARY, BOOKING_WINDOW_NOT_SUPPORTED e TICKETING_PROHIBITED rimuovono tutti i prezzi che abbiamo ricevuto in precedenza dalla cache.
• Fornire indicazioni pertinenti agli utenti

L'elenco attuale degli errori specifici del metodo fornito in TripOptionsError è un punto di partenza. Se sono necessari altri tipi di errori, contatta il team di Google Travel Transport.

QPS (query al secondo)

Il livello di QPS inviato da Google varia probabilmente in base all'inventario dei partner e al numero di utenti che visualizzano i dati memorizzati nella cache o fanno clic sui siti web dei partner per la prenotazione.

Latenza

Le richieste scadranno dopo 10 secondi. Non sono previste linee guida aggiuntive sulla latenza per le integrazioni dei partner beta. Tuttavia, ulteriori SLO di latenza verranno definite nelle nostre linee guida sulla qualità dei dati dei partner.

Valute, tasse e commissioni

Tutti i prezzi inviati a Google devono includere tutte le tasse e le commissioni ed essere specificati in una valuta supportata.

Valuta

La valuta di un prezzo viene specificata utilizzando il campo currency_code, che deve essere un codice valuta ISO 4217 valido.

Esempio:10,25 $

{
  "price": {
    "currency_code": "USD",
    "units": 10,
    "nanos": 250000000
  }
}

Tasse e commissioni

Il prezzo che fornisci deve essere il prezzo totale finale che l'utente pagherà, inclusivo di tutte le tasse (come l'IVA) e di eventuali commissioni aggiuntive (come quelle di prenotazione o della carta di pagamento). Puoi aggiungere una suddivisione della tariffa facoltativa utilizzando il campo ripetibile line_items. Google mostrerà all'utente il prezzo totale con un'eventuale suddivisione della tariffa.