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.

includeQuantityBasedPartialRefund

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

Примечание. Когда возвращается оставшееся общее количество покупки, соответствующая аннулированная покупка не будет иметь voidedQuantity , что служит сигналом о том, что покупка была полностью возмещена. Например, если покупка в количестве 10 возвращается 3 раза с количествами 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 как один из многих элементов комплексной стратегии по устранению нежелательного поведения. Отзыв доступа к продуктам внутри приложения обычно более эффективен в сочетании с приложением, имеющим разумные цены на покупки внутри приложения, дизайном приложения, препятствующим нежелательному поведению, сильной базой пользователей, чья культура отвергает такое поведение, а также отзывчивой и эффективной поддержкой пользователей. каналы.
• Управляйте политикой отзыва единообразно, чтобы обеспечить справедливость для всех пользователей.
• Рассмотрите возможность создания поэтапной политики при устранении нежелательного поведения. Например, начните с предупреждений в приложении о ранних нарушениях, а затем расширяйте свои ответы по мере продолжения нежелательного поведения пользователя. В крайнем случае, вы можете вообще запретить пользователю взаимодействовать с вашим приложением.
• Когда вы вводите политику отзыва и каждый раз обновляете ее, используйте каналы связи вашего приложения, чтобы информировать пользователей об изменениях. Дайте пользователям время четко понять эти изменения, прежде чем они вступят в силу в вашем приложении.
• Будьте прозрачны для своих пользователей и сообщайте им, когда вы предпринимаете какие-либо действия, например, отменяете им доступ к продукту, продаваемому через приложение. В идеале пользователи должны иметь возможность оспорить ваши решения, и к таким спорам следует относиться справедливо.
• Отслеживайте формы обратной связи и форумы сообщества, чтобы понять, что заставляет пользователей вести себя нежелательным образом и как они это делают. Действуйте на основе этих идей как на первой линии защиты.