API соответствует набору стандартов HTTP API и поддерживает механизм идемпотентности, повышающий надежность интеграции.
URL в Google
В документации по каждому методу, размещенному в Google, указан базовый URL, включающий название метода и номер основной версии. Чтобы получить полный URL, в конец нужно добавить идентификатор аккаунта платежного интегратора. Например, в документации по методу echo на стороне Google указан следующий URL:
https://vgw.googleapis.com/secure-serving/gsp/v1/echo
Если инициатору вызова присвоен идентификатор аккаунта платежного интегратора со значением INTEGRATOR_1, то этот идентификатор следует добавить в конец URL:
https://vgw.googleapis.com/secure-serving/gsp/v1/echo/INTEGRATOR_1
URL на стороне партнера
В документации по каждому методу API на стороне партнера можно найти базовый URL, включающий название метода и номер основной версии. К URL, размещенным в вашей системе, не следует добавлять идентификатор аккаунта платежного интегратора (PIAID).
Тестовая и рабочая среды
Chargeback Alert API размещены в тестовой и рабочей средах. Тестовая среда предназначена для разработки и тестирования. Запросы, отправленные в тестовой среде Google, не накладывают никаких реальных финансовых обязательств. Тестовая среда полностью отделена от рабочей. Ключи и информация о транзакциях в них не пересекаются.
Ожидается, что ваша тестовая среда будет всегда доступна, поскольку специалисты Google тестируют в ней изменения и новые функции.
Базовый путь тестовой среды Google
https://vgw.sandbox.google.com/secure-serving/gsp/
Базовый путь рабочей среды Google
https://vgw.googleapis.com/secure-serving/gsp/
В этом руководстве используются конечные точки рабочей среды.
Тип контента и шифрование
Полезные нагрузки сообщений, зашифрованные по протоколу PGP, должны использовать тип контентаapplication/octet-stream; charset=utf-8.
Полезные нагрузки сообщений, зашифрованные по протоколу JWE, должны использовать тип контента application/jose; charset=utf-8.
Тела запросов при отправке должны кодироваться в Base64URL, как определено в разделе 5 спецификации RFC 4648.
Коды статуса HTTP
Для всех запросов, которые могут быть обработаны сервером, Chargeback Alert API возвращают код статуса HTTP 200. Это относится и к успешным, и к отклоненным запросам (с точки зрения коммерческой логики и логики приложения). Для запросов, которые не удалось обработать, не должен возвращаться код статуса HTTP 200, поскольку при обмене данными между Google и партнером возникла ошибка. В этом случае API должен возвращать подходящий код статуса HTTP из списка ниже вместе с необязательным объектом ErrorResponse.
| Ошибки HTTP и их причины | |
|---|---|
| 400 |
BAD REQUEST
Клиент указал недопустимый аргумент. Этот код также должен быть возвращен, если операция отклонена из-за того, что условиям ее выполнения не соответствует состояние системы. Если повторные запросы обработать не удается, этот код ошибки рекомендуется возвращать до тех пор, пока состояние системы не будет явным образом исправлено. Например, если не выполнен запрос на возврат средств, поскольку он ссылается на несуществующую операцию списания, повторные попытки будут заканчиваться неудачей до тех пор, пока эта операция не появится в системе интегратора.
|
| 401 |
UNAUTHORIZED
В запросе отсутствуют действительные учетные данные для выполнения операции. Например, код 401 должен возвращаться при недопустимой или неизвестной подписи. |
| 403 |
FORBIDDEN / PERMISSION DENIED
У инициатора вызова нет разрешения на выполнение указанной операции. |
| 404 |
NOT FOUND
Запрошенный объект, например платеж или пользователь, не найден. |
| 409 |
CONFLICT / ABORTED
Операция была прервана. Как правило, это происходит из-за ошибок параллелизма, например из-за сбоев проверки последовательностей, прерывания транзакций и т. д. |
| 412 |
PRECONDITION FAILED
Этот код следует возвращать в случае повторного использования ключа идемпотентности с другими параметрами. |
| 429 |
RESOURCE EXHAUSTED / TOO MANY REQUESTS
Исчерпана квота для одного из ресурсов системы. |
| 499 |
CANCELLED
Операция отменена (как правило, инициатором вызова). |
| 500 |
INTERNAL ERROR
Внутренние ошибки. Это означает, что некоторые инварианты, ожидаемые базовой системой, недопустимы. |
| 501 |
UNIMPLEMENTED
Операция не реализована, не включена или не поддерживается в этом сервисе. |
| 503 |
UNAVAILABLE
Сервис в данный момент недоступен. Эта ошибка обычно свидетельствует о временном условии и может быть исправлена при повторной попытке. |
| 504 |
GATEWAY TIMEOUT / DEADLINE EXCEEDED
Крайний срок истек до завершения операции. Если операция изменяет состояние системы, то эта ошибка может быть возвращена, даже если операция выполнена успешно. Например, успешный ответ сервера мог быть отправлен с существенной задержкой, из-за чего время ожидания ответа истекло. |
Идемпотентность запроса
Идемпотентность запроса – это ключевая стратегия, которая используется в Chargeback Alert API для обеспечения надежного и отказоустойчивого взаимодействия между системами Google и партнеров. Идемпотентными называются запросы, которые можно отправить несколько раз, но результат во всех случаях будет таким же, что и при однократном выполнении. Это гарантирует, что данные о состоянии ресурсов в обеих системах будут согласованы в конечном счете.
Принцип идемпотентности в API позволяет:
- легко отслеживать и проверять все действия, чтобы свести расхождения к минимуму;
- предотвратить состояние гонки, поскольку несколько идентичных запросов от одного клиента не могут привести к разным конечным результатам;
- свести к минимуму зависимость от состояния, поскольку запросы могут быть понятны обособленно, а также снизить нагрузку на сервер, связанную с хранением данных, и повысить производительность и скорость обработки;
- не использовать дополнительные поля для обозначения повторных запросов.
Примеры
Пример 1. Подключение потеряно до получения ответа
Сценарий
- Google отправляет интегратору запрос на списание средств.
- Сервер интегратора получает запрос и успешно его обрабатывает.
- На сервере Google происходит сбой питания, в результате чего получить ответ, переданный на шаге 2, не удается.
- После того как питание на сервере Google восстановлено, на сервер интегратора передается тот же самый запрос на списание средств с теми же параметрами (меняется лишь значение
requestTimestamp, а идентификатор запроса и сведения о запросе остаются прежними).
Результат
В этом случае сервер интегратора должен отправить тот же ответ, что и на шаге 2, поскольку все параметры, за исключением responseTimestamp, остаются прежними.
Средства со счета пользователя списываются один раз (на шаге 2). На шаге 4 никакие денежные операции не выполняются.
Пример 2. Запрос отправлен на сервер, находящийся на обслуживании
Сценарий
- База данных сервера интегратора отключена для проведения техобслуживания.
- Google отправляет интегратору запрос.
- Интегратор корректно возвращает код статуса
UNAVAILABLE. - Сервер Google принимает ответ и назначает время повторной попытки.
- После завершения техобслуживания база данных интегратора возобновляет работу.
- Google повторно отправляет тот же запрос транзакции, что и на шаге 2 (меняется лишь значение
requestTimestamp, а идентификатор запроса и сведения о запросе остаются прежними). Обратите внимание, что идентификаторы обоих запросов должны быть одинаковыми. - Сервер интегратора принимает запрос и возвращает код статуса OK вместе с полным ответом.
Результат
В этом случае сервер интегратора должен обработать запрос на шаге 7 и не возвращать код ошибки HTTP 503 (UNAVAILABLE). Вместо этого сервер интегратора должен полностью обработать запрос и вернуть код статуса OK с соответствующим сообщением. Обратите внимание, что, когда система находится в состоянии UNAVAILABLE, Google может повторно отправлять запросы, аналогичные запросу на шаге 2. Результатом каждого запроса должно быть сообщение, аналогичное сообщению на шаге 3.
В конечном итоге будут выполнены шаги 6 и 7.
Пример 3. Повторно отправленное сообщение отличается от исходного из-за ошибки при восстановлении
Сценарий
- Google отправляет интегратору запрос.
- Сервер интегратора получает запрос и успешно его обрабатывает.
- На сервере Google происходит сбой питания, в результате чего получить ответ, переданный на шаге 2, не удается.
- После того как питание на сервере Google восстановлено, на сервер интегратора передается тот же самый запрос, но с измененными параметрами.
Результат
В этом случае сервер интегратора должен вернуть код ошибки HTTP 412 (PRECONDITION FAILED), означающий, что в системе Google есть ошибка.