API аннулированных покупок

API аннулированных покупок Google Play предоставляет список заказов, связанных с покупками, которые пользователь отменил. Информацию из этого списка можно использовать для реализации системы отзыва, которая заблокирует пользователю доступ к товарам из этих заказов.

Этот API применяется к разовым заказам в приложении и подпискам на приложение.

Покупку можно аннулировать следующими способами:

• Пользователь запрашивает возврат средств за свой заказ.
• Пользователь отменяет свой заказ.
• Заказ списан.

• Застройщик отменяет заказ или возвращает деньги.

  Примечание: в API аннулированных покупок будут отображаться только отозванные заказы. Если разработчик возвращает средства за покупку, не установив опцию отмены, заказ не будет возвращен API.

• Google отменяет или возвращает деньги за заказ.

Используя этот API, вы помогаете создать более сбалансированный и справедливый опыт для всех пользователей вашего приложения, особенно если ваше приложение представляет собой игру.

Примечание: В отличие от других источников данных о заказах, API аннулированных покупок учитывает покупки, по которым платежные системы списали средства. Поэтому вы можете столкнуться с несоответствиями между информацией из этого API и информацией из других источников данных о заказах.

Примечание: API аннулированных покупок возвращает аннулированные покупки только в случае необходимости их отмены. Разработчики могут использовать этот API в качестве подсказки для принятия дополнительных мер. Однако некоторые покупки могут быть возвращены по причине того, что покупка не была подтверждена разработчиком и, следовательно, может отсутствовать в его записях.

Получение доступа

Для работы с API аннулированных покупок вам необходимо разрешение на просмотр финансовой информации. Авторизация осуществляется через OAuth-клиент или сервисную учётную запись. Если вы используете сервисную учётную запись, включите разрешение «Просмотр финансовых отчётов» в этой учётной записи.

Дополнительную информацию о получении авторизованного доступа к API разработчиков Google Play см. в следующих руководствах:

• Настройка клиентов API-доступа
• Добавьте пользователей учетной записи разработчика и управляйте разрешениями

Просмотр аннулированных покупок

Используйте метод GET для запроса списка аннулированных покупок. В запросе укажите полное имя пакета вашего приложения, например, com.google.android.apps.maps , и токен авторизации, полученный при получении доступа к API.

GET https://www.googleapis.com/androidpublisher/v3/applications/
your_package_name/purchases/voidedpurchases?access_token=your_auth_token

Вы также можете включить в свой запрос следующие параметры, каждый из которых является необязательным:

время начала

Время (в миллисекундах с начала эпохи Unix ) самой старой аннулированной покупки, которую вы хотите увидеть в ответе. По умолчанию startTime равно 30 дням назад.

API может отображать только аннулированные покупки, совершённые за последние 30 дней. Более старые аннулированные покупки не включаются в ответ, независимо от значения, указанного для startTime .

Примечание: аннулированные покупки в ответе фильтруются по времени, когда данная запись рассматривается API как аннулированная, а не по значению voidedTimeMillis , возвращаемому в ответе.

время окончания

Время (в миллисекундах с начала эпохи Unix ) последней аннулированной покупки, которую вы хотите увидеть в ответе. По умолчанию endTime равен текущему времени.

Примечание: аннулированные покупки в ответе фильтруются по времени, когда данная запись рассматривается API как аннулированная, а не по значению voidedTimeMillis , возвращаемому в ответе.

maxResults

Максимальное количество аннулированных покупок, отображаемых в каждом ответе. По умолчанию это значение равно 1000. Обратите внимание, что максимальное значение для этого параметра также равно 1000.

токен

Токен продолжения предыдущего ответа, позволяющий просмотреть больше результатов.

тип

Тип аннулированных покупок, отображаемых в каждом ответе. Если установлено значение 0, будут возвращены только аннулированные покупки в приложении. Если установлено значение 1, будут возвращены как аннулированные покупки в приложении, так и аннулированные покупки по подписке. Значение по умолчанию — 0.

Примечание: Прежде чем запрашивать получение аннулированных покупок подписок, необходимо использовать в ответе orderId, который однозначно идентифицирует разовые покупки и подписки. В противном случае вы получите несколько заказов подписок с одним и тем же PurchaseToken.

включаюЧастичноеВозмещениеНаОсновеКоличества

Включать ли аннулированные покупки в частичные возвраты на основе количества, которые применимы только к покупкам с несколькими суммами. Если true , дополнительные аннулированные покупки могут быть возвращены с voidedQuantity , указывающим сумму возврата при частичном возврате на основе количества. Значение по умолчанию — false .

Примечание: При возврате оставшейся суммы покупки, соответствующая аннулированная покупка не будет иметь voidedQuantity , что служит сигналом о полном возврате средств. Например, если покупка в количестве 10 возвращается трижды с количеством 2, 3 и 5, будет 3 аннулированных покупки. Первые две аннулированные покупки будут иметь voidedQuantity 2 и 3, а третья аннулированная покупка не будет иметь voidedQuantity .

Ответ представляет собой строку JSON, содержащую список аннулированных покупок. Если количество результатов превышает число, указанное в параметре запроса maxResults , ответ включает значение nextPageToken , которое можно передать в последующий запрос для просмотра дополнительных результатов. Первый результат в списке отображает самую старую аннулированную покупку.

{
  "tokenPagination": {
    "nextPageToken": "next_page_token"
  },
  "voidedPurchases": [
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_purchase_token",
      "purchaseTimeMillis": "1468825200000",
      "voidedTimeMillis": "1469430000000",
      "orderId": "some_order_id",
      "voidedSource": "0",
      "voidedReason": "4"
    },
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_other_purchase_token",
      "purchaseTimeMillis": "1468825100000",
      "voidedTimeMillis": "1470034800000",
      "orderId": "some_other_order_id",
      "voidedSource": "2",
      "voidedReason": "5"
    },
  ]
}

Квоты

API аннулированных покупок устанавливает следующие квоты для каждого пакета:

• 6000 запросов в день. (День начинается и заканчивается в полночь по тихоокеанскому времени.)
• 30 запросов в течение любого 30-секундного периода.

Руководство по первоначальным запросам

Во время первого запроса к API вам может потребоваться получить все доступные данные для вашего приложения. Хотя это маловероятно, этот процесс может исчерпать вашу дневную квоту. Чтобы получить данные об аннулированных покупках более безопасным и последовательным способом, следуйте этим рекомендациям:

• Используйте значение по умолчанию для параметра maxResults . Таким образом, если вы используете всю квоту запросов за день, вы сможете получить информацию о 6 000 000 аннулированных покупок.
• Если ответ содержит значение nextPageToken , присвойте это значение параметру token во время следующего запроса.

Лучшие практики

Примечание: Помимо использования этого API, разработчикам следует интегрировать уведомления для разработчиков в режиме реального времени (RTDN) . С помощью RTDN вы будете получать уведомления от Google при каждом изменении прав пользователя в вашем приложении, в том числе при отмене покупки .

Используя этот API в своём приложении, помните, что существует множество причин для отмены покупки, и не существует универсального решения, подходящего во всех случаях. При разработке политик и стратегий отзыва следует учитывать интересы пользователей. Для этого можно использовать следующие рекомендации:

• Используйте этот API как один из многих элементов комплексной стратегии борьбы с нежелательным поведением. Запрет доступа к продуктам внутри приложения обычно более эффективен в сочетании с разумными ценами на покупки внутри приложения, дизайном, препятствующим нежелательному поведению, сильной пользовательской базой, культура которой отвергает такое поведение, а также отзывчивыми и эффективными каналами поддержки пользователей.
• Администрируйте политику отзыва единообразно, чтобы обеспечить справедливость для всех пользователей.
• Рассмотрите возможность создания поэтапной политики реагирования на нежелательное поведение. Например, начните с предупреждений в приложении о ранних нарушениях, а затем ужесточайте меры реагирования по мере продолжения нежелательного поведения пользователя. В крайнем случае, вы можете вообще запретить пользователю взаимодействовать с вашим приложением.
• При внедрении политики отзыва и при каждом её обновлении используйте каналы связи в вашем приложении, чтобы информировать пользователей об изменениях. Дайте пользователям время, чтобы чётко понять эти изменения, прежде чем они вступят в силу в вашем приложении.
• Будьте прозрачны для своих пользователей и сообщайте им о любых ваших действиях, например, о закрытии доступа к продукту в приложении. В идеале пользователи должны иметь возможность оспорить ваши решения, и такие споры должны рассматриваться справедливо.
• Следите за формами обратной связи и форумами сообщества, чтобы понять, что побуждает пользователей вести себя нежелательно и как они это делают. Используйте эти данные в качестве первой линии защиты.