Standardy protokołów

Interfejs API jest zgodny z zestawem standardów interfejsów API HTTP i obsługuje mechanizm idempotentności, który ułatwia ścisłą integrację.

Adresy URL hostowane przez Google

Dokumentacja poszczególnych metod hostowanych przez Google zawiera podstawowy adres URL, który obejmuje nazwę metody i numer wersji głównej. Pełny adres URL tworzy się, dodając na końcu identyfikator konta integratora płatności elementu wywołującego. Na przykład dokumentacja hostowanej przez Google metody echa zawiera adres URL:

https://vgw.googleapis.com/gsp/refundable-one-time-payment-code-v1/echo

Jeśli identyfikator konta integratora płatności użytkownika wywołującego to INTEGRATOR_1, należy go dodać na końcu adresu URL, by otrzymać:

https://vgw.googleapis.com/gsp/refundable-one-time-payment-code-v1/echo/INTEGRATOR_1

Adresy URL hostowane przez partnera

Dokumentacja poszczególnych metod API hostowanych przez partnerów zawiera podstawowy adres URL, który obejmuje nazwę metody i numer wersji głównej. Partner nie powinien dołączać identyfikatora konta integratora płatności (PIAID) w adresach URL, które hostuje.

Piaskownica i środowiska produkcyjne

Google hostuje interfejs API kodu płatności jednorazowej zarówno w piaskownicy (w celach dotyczących programowania i testowania), jak i w środowisku produkcyjnym. Żądania w środowisku piaskownicy Google nie skutkują żadną rzeczywistą odpowiedzialnością finansową. Środowisko piaskownicy i środowisko produkcyjne są całkowicie oddzielone i nie współużytkują kluczy ani danych dotyczących transakcji.

Google oczekuje, że Twoja piaskownica będzie stale dostępna, ponieważ będziemy jej używać, by najpierw przetestować zmiany i nowe funkcje.

Ścieżka bazowa piaskownicy Google

https://vgw.sandbox.google.com/gsp/

Ścieżka bazowa środowiska produkcyjnego Google

https://vgw.googleapis.com/gsp/

W tym przewodniku będą używane produkcyjne punkty końcowe.

Typ treści i kodowanie

Ładunki komunikatów, w których jest używane szyfrowanie PGP, muszą korzystać z typu treści application/octet-stream; charset=utf-8. Ładunki komunikatów, w których jest używane szyfrowanie JWE, muszą korzystać z typu treści application/jose; charset=utf-8. Treści żądań muszą być wysyłane przy użyciu kodowania base64url, zgodnie z definicją w dokumencie rfc4648 §5.

Kody stanów HTTP

Interfejsy API kodu płatności jednorazowej zostały zaprojektowane w taki sposób, aby zwracać kod stanu HTTP 200 w przypadku wszystkich żądań, które może przetworzyć serwer. Obejmuje to zarówno udane, jak i odrzucone żądania z punktu widzenia logiki biznesowej lub aplikacji. Żądania, których nie można przetworzyć, nie powinny zwracać kodu stanu 200 HTTP, ponieważ reprezentują błąd występujący między Google a partnerem. Zamiast tego odpowiedź interfejsu API powinna używać odpowiednich poniższych kodów stanu HTTP z opcjonalnym obiektem ErrorResponse.

Błędy HTTP i ich przyczyny
400 BAD REQUEST

Klient podał nieprawidłowy argument.

Ten kod błędu może też być zwracany, jeśli operacja została odrzucona, ponieważ system nie znajduje się w stanie wymaganym do jej wykonania.

Należy go użyć, jeśli kolejne próby żądania nie mogą się powieść, dopóki stan systemu nie zostanie jawnie poprawiony. Jeśli na przykład żądanie zwrotu środków kończy się niepowodzeniem, ponieważ odwołuje się do nieistniejącego zapisu, ponowne próby nie powiodą się, dopóki zapis nie pojawi się w systemie integratora.

401 UNAUTHORIZED

Żądanie nie ma prawidłowych danych uwierzytelniających dla tej operacji. Kod 401 powinien być na przykład zwracany w przypadku nieprawidłowych lub nieznanych podpisów.

403 FORBIDDEN / PERMISSION DENIED

Element wywołujący nie ma uprawnień do wykonania określonej operacji.

404 NOT FOUND

Nie znaleziono żądanego elementu, takiego jak płatność lub użytkownik.

409 CONFLICT / ABORTED

Operacja została przerwana, najczęściej z powodu problemu równoczesności, np. w przypadku nieudanych kontroli sekwencera, przerwanych transakcji itp.

412 PRECONDITION FAILED

Tego kodu należy używać w sytuacjach, gdy klucz idempotentności jest używany ponownie z innymi parametrami.

429 RESOURCE EXHAUSTED / TOO MANY REQUESTS

Któryś zasób systemowy został wyczerpany.

499 CANCELLED

Operacja została anulowana (zwykle przez element wywołujący).

500 INTERNAL ERROR

Błędy wewnętrzne. Oznacza to, że pewne niezmienniki oczekiwane przez system bazowy zostały uszkodzone.

501 UNIMPLEMENTED

Operacja nie jest wdrożona, obsługiwana lub włączona w tej usłudze.

503 UNAVAILABLE

Usługa jest obecnie niedostępna. Jest to najczęściej stan przejściowy, który można rozwiązać, ponawiając próbę.

504 GATEWAY TIMEOUT / DEADLINE EXCEEDED

Termin upłynął przed wykonaniem operacji. W przypadku operacji, które zmieniają stan systemu, ten błąd może zostać zwrócony nawet wówczas, gdy operacja zakończyła się pomyślnie. Na przykład pomyślna odpowiedź serwera mogła być tak opóźniona, że termin upłynął.

Idempotentność żądań

Idempotentność żądań to podstawowa strategia używana w interfejsach API kodu płatności jednorazowej stosowana w celu zapewnienia niezawodności i odporności na awarie systemowych interakcji między Google a partnerami. Żądania idempotentne to żądania, które można wysyłać wielokrotnie, ale ich efekt jest taki sam jak żądania pojedynczego. Strategia ta ułatwia zachowanie spójności wynikowej między systemami przez zapewnienie bezpieczeństwa wykonywania ponownych prób, co pozwala naszym systemom osiągać zgodność co do stanu zasobu.

Nasz interfejs API wykorzystuje idempotentność do:

  • ograniczania problemów związanych z uzgadnianiem przez ułatwienie śledzenia i kontrolowania wszystkich działań;
  • zapobiegania sytuacjom wyścigu przez zapewnienie, że wiele identycznych żądań od tego samego klienta prowadzi do identycznego stanu końcowego;
  • minimalizacji stanu przez umożliwienie rozumienia żądań w izolacji, czego efektem jest większa wydajność i przepustowość ze względu na mniejsze obciążenie serwera związane z przechowywaniem danych;
  • unikania konieczności stosowania dodatkowych pól wskazujących, czy żądanie jest ponowną próbą.

Przykłady

Przykład 1: utrata połączenia przed otrzymaniem odpowiedzi

Scenariusz:

  1. Google wysyła żądanie zapisu transakcji do integratora.
  2. Serwer integratora odbiera to żądanie i przetwarza je.
  3. Serwer Google traci zasilanie przed otrzymaniem odpowiedzi w kroku nr 2.
  4. Zasilanie serwera Google zostaje przywrócone i to samo żądanie zapisu transakcji jest wysyłane z tymi samymi parametrami (taki sam identyfikator i szczegóły żądania, ale zaktualizowany element requestTimestamp) do serwera integratora.

Wynik:

W tym przypadku serwer integratora musi udzielić takiej samej odpowiedzi jak w kroku nr 2, ponieważ wszystkie parametry z wyjątkiem responseTimestamp są takie same. Konto użytkownika zostaje obciążone tylko raz, w kroku nr 2. Zdarzenie w kroku nr 4 nie ma żadnych skutków finansowych dla użytkownika.

Przykład 2: żądanie wysłane do serwera poddawanego konserwacji

Scenariusz:

  1. Baza danych na serwerze integratora nie działa z powodu konserwacji.
  2. Google wysyła żądanie do integratora.
  3. Integrator prawidłowo zwraca kod stanu UNAVAILABLE.
  4. Serwer Google odbiera odpowiedź i planuje ponowienie próby.
  5. Baza danych na serwerze integratora zostaje przywrócona online.
  6. Google ponownie wysyła żądanie z kroku nr 2 (taki sam identyfikator i szczegóły żądania, ale zaktualizowany element requestTimestamp). Zwróć uwagę, że identyfikatory obu żądań muszą być takie same.
  7. Serwer integratora otrzymuje żądanie i zwraca kod stanu OK wraz z pełną odpowiedzią.

Wynik:

W tym przypadku serwer integratora musi przetworzyć żądanie w kroku nr 7 i nie może zwrócić kodu HTTP 503 (UNAVAILABLE). Zamiast tego powinien do końca przetworzyć żądanie i zwrócić kod OK z odpowiednim komunikatem. Zwróć uwagę, że gdy system jest w stanie UNAVAILABLE, Google może wielokrotnie wysłać żądania podobne do wysłanego w kroku nr 2. Każde takie żądanie powinno skutkować zwróceniem komunikatu podobnego do zwróconego w kroku nr 3. W konsekwencji wystąpią kroki 6 i 7.

Przykład 3: ponawiany komunikat nie pasuje do początkowego komunikatu z powodu błędu odzyskiwania

Scenariusz:

  1. Google wysyła żądanie do integratora.
  2. Serwer integratora odbiera to żądanie i przetwarza je.
  3. Serwer Google traci zasilanie przed otrzymaniem odpowiedzi w kroku nr 2.
  4. Zasilanie serwera Google zostaje przywrócone i podejmuje on próbę wysłania tego samego żądania, ale niestety niektóre parametry są inne.

Wynik:

W tym przypadku serwer integratora powinien udzielić odpowiedzi z kodem błędu HTTP 412 (PRECONDITION FAILED), który informuje Google, że w tym systemie występuje błąd.