Google Play 开发者 API 现在包含了额外的功能，可以报告来自 替代计费 或 外部优惠 系统的交易。本指南介绍了如何报告替代计费或外部优惠交易。
可能需要一些组件来处理来自您后端的应用内购买。要构建它们，您需要根据 配置 Google Play 开发者 API 中的说明设置您的后端集成。对于所有不特定于替代计费或外部优惠 API 的开发者后端功能，Google Play 计费系统文档 中的说明适用。
向 Google Play 报告新的外部交易
与 Externaltransactions API 集成以 **报告在支持的国家/地区 Google Play 计费系统之外发生的交易，包括从免费试用购买产生的 0 美元交易**。替代计费或外部优惠系统上的交易应仅在根据 替代计费 或 外部优惠 计划允许的合格用户国家/地区启动和报告，否则 API 调用将被拒绝。这适用于所有交易，包括新购买、续订、充值、升级、降级和其他交易。
外部交易报告
您应在通过替代计费或外部优惠系统授权付款后，调用 Externaltransactions API 来报告外部交易。这适用于所有交易，包括首次收费、续订、退款和其他交易。所有交易都需要在交易发生后的 24 小时内报告。
每个外部交易都使用外部交易 ID 进行报告。对于循环购买（例如自动续订订阅），您需要在任何后续交易（包括退款）中将与循环购买中的首次交易相关的外部交易 ID 作为参数发送。这会记录该购买的一系列交易。当产品发生变化（例如升级或降级），或者当循环交易被取消或过期并且稍后再次购买相同产品时，您会发送一个新的外部交易 ID 用于购买。您不得将任何个人身份信息、专有信息或机密信息作为此外部交易 ID 的一部分包含在内。
报告新购买
每次在替代计费或外部优惠系统中成功进行新购买时，都需要调用 Externaltransactions API。对于这些新购买，您需要在后端提供与购买相关的 **唯一** externalTransactionId 作为查询参数。此 externalTransactionId 不能在同一应用程序的包 ID 中重复使用。
应用通过 UserChoiceBillingListener、AlternativeBillingOnlyReportingDetailsListener 或 ExternalOfferReportingDetailsListener 回调接收到的 externalTransactionToken 也是一次性购买和循环购买（如订阅）中首次交易的请求主体的一部分。这两种情况都称为*初始交易*。在初始交易后，不再需要 externalTransactionToken，您可以通过提供新的唯一 externalTransactionId 来报告后续交易（如订阅续费）。有关如何报告后续交易的更多详细信息，请参阅 报告购买的后续交易。
示例:
- 开发人员在他们的应用中配置和启用替代计费。
- 用户 1 位于韩国（支持的国家/地区），正在尝试以 12634.10KRW/月的价格购买
product1，并享受为期一个月的免费试用优惠。 - 应用使用
ProductDetails启动购买流程，用于product1和用户选择的优惠。 - 用户 1 选择开发人员的替代计费系统。
UserChoiceBillingListener接收my_token作为externalTransactionToken的值。- 然后，开发人员将相关信息发送到他们的后端（
externalTransactionToken值和正在购买的产品）。然后，他们启动替代计费系统中product1的购买流程。此交易在开发人员端分配了一个唯一的交易 ID，用于将其报告给 Google Play：123-456-789。即使用户正在享受免费试用，也需要此交易 ID。 - 在替代计费系统中完成购买交易后，开发人员将使用以下请求将交易报告给 Google Play。它最初被报告为零美元交易，因为用户获得了免费试用期。
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789
Body
{
"originalPreTaxAmount" : {
"priceMicros": "0",
"currency": "KRW"
},
"originalTaxAmount" : {
"priceMicros": "0",
"currency": "KRW"
},
"transactionTime" : "2022-02-22T12:45:00Z",
"recurringTransaction" : {
"externalTransactionToken": "my_token",
"externalSubscription" {
"subscriptionType": "RECURRING"
}
},
"userTaxAddress" : {
"regionCode": "KR"
}
}
如果您与居住在印度的用户进行交易，而印度的税收因其行政区域（如州或省）而异，那么请确保在 userTaxAddress 下包含该区域。有关适用行政区域的预定义字符串列表，请参阅 API 参考指南。
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789
Body
{
"originalPreTaxAmount" : {
"priceMicros": "0",
"currency": "INR"
},
"originalTaxAmount" : {
"priceMicros": "0",
"currency": "INR"
},
"transactionTime" : "2023-11-01T12:45:00Z",
"recurringTransaction" : {
"externalTransactionToken": "my_token",
"externalSubscription" {
"subscriptionType": "RECURRING"
}
},
"userTaxAddress" : {
# Tax varies in India based on state, so include that information in
# administrativeArea
"regionCode": "IN"
"administrativeArea": "KERALA"
}
}
报告购买的后续交易
在某些情况下，同一外部购买会关联多个用户付款（例如，订阅续订或预付计划充值）。您可以使用 Externaltransactions 中的相同 API 报告这些后续交易。如 报告新的购买 中所述，externalTransactionToken 不需要用于后续交易。相反，每个续订或充值交易都将发送新的唯一 externalTransactionId 作为查询参数，并将初始交易的 ID 包含在 initialExternalTransactionId 字段中。
继续前面的示例
- 用户 1 的第一次续费发生在替代计费系统中。初始交易 ID 为 123-456-789。
- 开发人员在 URL 查询参数中报告交易循环作为此新交易的外部交易 ID，同时在
initialExternalTransactionId字段中引用初始交易的外部交易 ID。
示例请求:
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi
Body
{
"originalPreTaxAmount" : {
"priceMicros": "12634000000",
"currency": "KRW"
},
"originalTaxAmount" : {
"priceMicros": "1263000000",
"currency": "KRW"
},
"transactionTime" : "2022-02-22T12:45:00Z",
"recurringTransaction" : {
"initialExternalTransactionId": "123-456-789",
"externalSubscription" {
"subscriptionType": "RECURRING"
}
},
"userTaxAddress" : {
"regionCode": "KR"
}
}
报告升级或降级
当用户在替代计费系统中拥有订阅时，要报告升级或降级，请使用 Externaltransactions API 中的相同端点和功能，发送提供给应用用于升级或降级交易的 externalTransactionToken。这与 报告新的购买 类似。
从手动报告替代计费交易迁移
要迁移在您提供替代计费（未进行自动化报告）时开始的活动订阅，请使用 migratedTransactionProgram 字段创建一个新的零成本交易，而不是指定 initialExternalTransactionId 或 externalTransactionToken。将 transactionTime 设置为用户最初注册每个活动订阅的时间。之后，通过 API 以正常方式报告这些订阅的每个后续交易，提供上面用于创建续订交易的 initialExternalTransactionId。一旦订阅迁移完成，您将不再需要手动报告订阅的后续交易，前提是这些交易通过本页面中描述的自动化方法进行报告。
在迁移订阅时，请注意 配额限制，以确保迁移不会导致配额不足。如果需要迁移大量订阅，请将它们分散到多个日期，或者 请求提高配额。
migratedTransactionProgram 字段仅可在从手动报告迁移时使用。当不再支持手动报告时，它将被弃用。
示例请求:
# Note that the externalTransactionId specified here will used to report subsequent
# transactions.
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi
Body
{
# Be sure to set the price to 0 for this transaction since it does not reflect
# an actual subscription renewal.
"originalPreTaxAmount" : {
"priceMicros": "0",
"currency": "KRW"
},
"originalTaxAmount" : {
"priceMicros": "0",
"currency": "KRW"
},
# The transaction time should be set to when the user signed up for this
# subscription.
"transactionTime" : "2022-02-22T12:45:00Z",
"recurringTransaction" : {
"migratedTransactionProgram": "USER_CHOICE_BILLING",
"externalSubscription" {
"subscriptionType": "RECURRING"
}
},
"userTaxAddress" : {
"regionCode": "KR"
}
}
报告 Play 合作伙伴计划
参与合作伙伴计划（如 Play 媒体体验计划）的开发人员必须在报告外部交易时提供 transaction_program_code。如果您是合格的开发人员，请联系您的业务发展经理，以获取有关如何设置此字段的更多信息。
将购买退款报告给 Google Play
与 Externaltransactions API 集成，以报告在 Google Play 计费系统之外向用户退款的交易。为了使 Play 正确识别已退款的交易，您应将先前报告交易的相应 externalTransactionId 作为 URL 参数的一部分包括在内。
在报告订阅购买退款时，请引用正在退款的订阅的特定循环的 externalTransactionId。
示例：假设订阅有以下交易
- 外部交易 ID 为 ABC.1234-5678-9012-34567 的初始交易
- 外部交易 ID 为 ABC.1234-5678-9012-34567..0 的第一次循环交易
- 外部交易 ID 为 ABC.1234-5678-9012-34567..1 的第二次循环交易
要报告订阅的所有交易的退款，您需要进行三个单独的退款请求：一个用于初始交易，两个用于后续交易。
此方法接受 全额退款（金额与用户在原始外部交易中支付的金额相同）和 部分退款（金额小于用户在原始外部交易中支付的金额）。对于部分退款，您需要指定已退款的税前金额。
API 配额
Externaltransactions API 与 Google Play 开发者 API 中的任何其他端点一样，受 每日 API 配额 的约束。
此外，Externaltransactions API 对 Externaltransactions.createexternaltransaction 或 Externaltransactions.refundexternaltransaction 的调用有每分钟 1200 次查询（QPM）的限制。对 Externaltransactions.getexternaltransaction 的调用不计入此 1200 QPM 限制。