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 sulle problematiche 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 POST.

Tieni presente che, per chiarezza strutturale, la documentazione dell'interfaccia API viene fornita come definizioni di messaggi Protocol Buffer e la traduzione di una definizione di messaggio Protocol Buffer 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, OAuth 2.0 e l'autenticazione con certificato client (vedi Configurazione partner). Durante il test dell'API, il partner deve fornire a Google le credenziali giuste:

• Per Digest: nome utente e password.
• Per OAuth 2.0: client_id e client_secret.
• Per il certificato: un certificato client SSL.

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 errata	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, forse 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 corretta 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 esempio 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 riuscita)
  • 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 effettuare una 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 USD:

{
  "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 delle carte 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.