Standard di protocollo

L'API segue una serie di standard API HTTP e supporta idempotenza per facilitare una valutazione e integrazione.

URL ospitati da Google

La documentazione relativa a ciascun metodo ospitato da Google fornisce un URL di base, che include il nome del metodo e il numero di versione principale. Viene creato l'URL completo aggiungendo l'ID account dell'integratore pagamenti del chiamante alla fine. Ad esempio, la documentazione per il metodo eco in hosting su Google specifica l'URL:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo

Se l'ID account dell'integratore pagamenti del chiamante è INTEGRATOR_1, deve aggiungere che si trova alla fine dell'URL per formare:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo/INTEGRATOR_1

Nota: la pagina della documentazione degli endpoint per il metodo specifico che stai utilizzando avrà l'URL più preciso per la tua richiesta.

URL ospitati dai partner

La documentazione relativa a ciascun metodo API ospitato dai partner fornisce un URL di base, include il nome del metodo e il numero di versione principale. Non devi includere i campi ID account integratore pagamenti (PIAID) negli URL che ospiti.

Ambienti di sandbox e produzione

Google ospita le API di pagamento standard in entrambe le sandbox (per le applicazioni test) e produzione. Richieste nell'ambiente sandbox di Google non comportano alcuna responsabilità finanziaria reale. La sandbox e ambienti di produzione sono completamente separati e non condividono chiavi le informazioni sulla transazione.

Google si aspetta che la sandbox sia sempre disponibile poiché utilizzeremo la sandbox per testare le modifiche e le nuove funzionalità.

Percorso di base sandbox di Google

https://vgw.sandbox.google.com/secure-serving/gsp/

Nota: se l'integrazione è già stata avviata e richiama il https://billpaynotification.sandbox.googleapis.com host, puoi continuare a farlo. Le nuove integrazioni devono chiamare "vgw.sandbox.google.com" .

Percorso base di produzione di Google

https://vgw.googleapis.com/secure-serving/gsp/

Nota: se l'integrazione è già stata avviata e richiama il https://billpaynotification.googleapis.com, puoi continuare a farlo. Le nuove integrazioni devono chiamare "vgw.googleapis.com" .

Questa guida utilizzerà gli endpoint di produzione.

Tipo di contenuti e codifica

I payload dei messaggi che utilizzano la crittografia PGP devono usare il tipo di contenuto application/octet-stream; charset=utf-8. Gli corpi delle richieste PGP devono essere inviate utilizzando la codifica base64url, come definita in rfc4648 §5. I payload dei messaggi che utilizzano la crittografia JWE devono utilizzare il tipo di contenuto application/jose; charset=utf-8. L'opzione Serializzazione compatta supportato da JWE/JWS e gestisce la codifica per il corpo della richiesta finale.

Codici di stato HTTP

Le API di pagamento standard sono progettate per restituire un codice di stato HTTP 200 per tutte le richieste che possono essere elaborate dal server. Sono inclusi richieste accettate e rifiutate dal punto di vista aziendale o della logica dell'applicazione. Le richieste che non possono essere elaborate non devono comportare il codice di stato HTTP 200, poiché rappresenta un errore tra Google e partner. La risposta dell'API deve invece utilizzare lo stato HTTP appropriato seguenti con un oggetto ErrorResponse facoltativo.

Errori e motivi HTTP
400	BAD REQUEST Il client ha specificato un argomento non valido. Questo valore può essere restituito anche se l'operazione è stata rifiutata perché il sistema non è nello stato richiesto per l'esecuzione dell'operazione. Utilizza questa opzione se i nuovi tentativi della richiesta non possono andare a buon fine fino allo stato del sistema sia stato risolto esplicitamente. Ad esempio, se una richiesta di rimborso non va a buon fine perché fa riferimento a un'acquisizione che non esiste, il nuovo tentativo non avrà esito positivo finché l'acquisizione non esiste nel sistema degli integratori. Nota: non è possibile utilizzare BAD_REQUEST (400) per le situazioni in cui è disponibile un errore dell'applicazione appropriato. Per ad esempio, valute errate dovrebbero restituire ACCOUNT_DOES_NOT_SUPPORT_CURRENCY con il codice 200 se la risposta standard contiene quel campo o enum.
401	UNAUTHORIZED La richiesta non dispone di credenziali di autenticazione valide per il operativa. Ad esempio, le firme non valide o sconosciute restituisce un codice 401.
403	FORBIDDEN / PERMISSION DENIED Il chiamante non dispone dell'autorizzazione per eseguire l'operazione specificata.
404	NOT FOUND Alcune entità richieste, come il pagamento o l'utente, non sono state trovate.
409	CONFLICT / ABORTED L'operazione è stata interrotta, in genere a causa di un problema di contemporaneità come errori nel controllo del sequencer, interruzioni delle transazioni e così via.
412	PRECONDITION FAILED Questo codice deve essere usato in situazioni in cui una chiave di idempotenza viene riutilizzati con parametri diversi.
429	RESOURCE EXHAUSTED / TOO MANY REQUESTS Alcune risorse di sistema sono esaurite.
499	CANCELLED L'operazione è stata annullata (in genere dal chiamante).
500	INTERNAL ERROR Errori interni. Ciò significa alcune caratteristiche invarianti previste dal sistema sottostante. è stato danneggiato.
501	UNIMPLEMENTED L'operazione non è implementata, supportata o abilitata in questo servizio.
503	UNAVAILABLE Il servizio non è al momento disponibile. Molto probabilmente si tratta di un caso e può essere corretta riprovando.
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED La scadenza è scaduta prima del completamento dell'operazione. Per le operazioni modificare lo stato del sistema, questo errore potrebbe essere restituito anche se l'operazione è stata completata correttamente. Ad esempio, una risposta positiva da un server potrebbe essere stato ritardato abbastanza a lungo perché la scadenza scadono.

Richiedi idempotenza

L'idempotenza della richiesta è una strategia centrale utilizzata nei pagamenti standard API utilizzate per garantire che le interazioni di sistema tra Google e i partner robuste e a tolleranza di errore. Le richieste idempotenti sono richieste che possono potrebbero essere inviate più volte, ma hanno lo stesso effetto di una singola richiesta. Questa strategia agevola la coerenza finale tra i sistemi rendendo nuovi tentativi in sicurezza, il che consente ai nostri sistemi di raggiungere un accordo lo stato desiderato della risorsa.

La nostra API sfrutta l'idempotenza per:

• a ridurre i problemi di riconciliazione rendendo tutte le azioni facilmente tracciabili verificabile.
• impediscono le racecondition, assicurando che più richieste identiche nello stesso client non risultano in uno stato finale diverso.
• minimizzare lo stato consentendo la comprensione delle richieste in modo isolato, per migliorare le prestazioni e la velocità effettiva rimuovendo il carico del server causato conservazione dei dati.
• evitare la necessità di campi aggiuntivi per indicare se una richiesta è un nuovo tentativo.

di Gemini Advanced.

Nota: i risultati degli errori non devono mai essere memorizzati nella cache o restituiti idempotentemente. Inoltre, i nuovi tentativi automatici per rilevare errori devono usare una strategia di backoff esponenziale.

Esempi

Esempio 1: connettività persa prima della ricezione di una risposta

Scenario:

1. Google invia una richiesta all'integratore.
2. L'integratore server riceve questa richiesta e la elabora correttamente.
3. Il server di Google si spegne prima di ricevere la risposta nel passaggio 2.
4. Viene ripristinata la corrente del server di Google e viene inviata la stessa richiesta con gli stessi parametri (stesso ID e dettagli della richiesta, ma aggiornati requestTimestamp) al server dell'integratore.

Risultato:

In questo caso il server di integrazione deve rispondere con la stessa risposta fornita su passaggio 2 perché tutti i parametri, tranne responseTimestamp, sono uguali. L'effetto collaterale si verifica una sola volta, nel passaggio 2. Il passaggio 4 non ha alcun effetto collaterale.

Esempio 2: richiesta inviata a un server in fase di manutenzione

Scenario:

1. Il database del server di integrazione non è attivo per manutenzione.
2. Google invia una richiesta all'integratore.
3. L'integratore restituisce correttamente il codice di stato UNAVAILABLE.
4. Il server di Google riceve la risposta e pianifica un nuovo tentativo.
5. Il database del server di integrazione è di nuovo online.
6. Google invia di nuovo la richiesta dal passaggio 2 (stesso ID richiesta e stessi dettagli della richiesta) ma ha aggiornato requestTimestamp). Tieni presente che gli ID richiesta di entrambe le richieste dovrebbe essere lo stesso.
7. Il server integratore riceve la richiesta e restituisce un codice di stato OK con una risposta completa.

Risultato:

In questo caso il server di integrazione deve elaborare la richiesta nel passaggio 7 e non restituisce HTTP 503 (UNAVAILABLE). Al contrario, il server dell'integratore dovrebbe elaborare la richiesta e restituire l'approvazione con messaggi appropriati. Tieni presente che mentre il sistema è UNAVAILABLE Google potrebbe effettuare richieste ripetute simili a passaggio 2. Ogni richiesta dovrebbe generare un messaggio simile al passaggio 3. Infine, verranno eseguiti i passaggi n. 6 e n. 7.

Esempio 3: il messaggio ripetuto non corrisponde al messaggio iniziale a causa di un errore di recupero

Scenario:

1. Google invia una richiesta all'integratore.
2. L'integratore server riceve questa richiesta e la elabora correttamente.
3. Il server di Google si spegne prima di ricevere la risposta nel passaggio 2.
4. Viene ripristinata la corrente del server di Google e tenta di inviare la stessa richiesta ma sfortunatamente alcuni parametri sono diversi.

Risultato:

In questo caso l'integratore server deve rispondere con un 412 HTTP (PRECONDITION FAILED) che indica a Google che è presente in questo sistema.