رابط برنامهنویسی کاربردی توسعهدهندگان گوگل پلی شامل قابلیتهای اضافی برای گزارش تراکنشها از برنامههای صورتحساب و پیوند دادن آنها است. این راهنما نحوه گزارش تراکنشها از این برنامههای صورتحساب را شرح میدهد.
چند مؤلفه وجود دارد که ممکن است برای مدیریت تراکنشهای خارجی از backend شما ضروری باشند. برای ساخت آنها، باید ادغام backend خود را همانطور که در پیکربندی Google Play Developer API نشان داده شده است، تنظیم کنید. برای ایجاد قابلیت backend توسعهدهنده که مختص صورتحساب نیست و برنامههای پیوند را ایجاد میکند، به سیستم صورتحساب Google Play مراجعه کنید.
واژهنامه اصطلاحات
قراردادهای اصطلاحاتی که در این راهنما دنبال میشوند:
- برنامههای صورتحساب و پیوند : برنامههایی که خرید محتوای دیجیتال یا دانلود برنامهها را خارج از Google Play تسهیل میکنند. این شامل برنامههای صورتحساب جایگزین و پیشنهادهای خارجی میشود.
- APIهای تراکنش خارجی : APIهایی که برای گزارش تراکنشها برای صورتحسابهای واجد شرایط و پیوند دادن برنامهها استفاده میشوند.
- تراکنش خارجی : تراکنشی واجد شرایط که خارج از برنامه و طبق الزامات برنامه انجام میشود. این شامل خرید محتوای دیجیتال و دانلود برنامه میشود.
- توکن تراکنش خارجی : توکنی که از طریق کتابخانه پرداخت گوگل پلی در اختیار شما قرار میگیرد تا هنگام تکمیل تراکنش خارجی توسط کاربر، از آن استفاده کنید. این توکن برای اطلاعرسانی به گوگل پلی در مورد موفقیتآمیز بودن تراکنش خارجی استفاده میشود.
- شناسه تراکنش خارجی : شناسه منحصر به فردی که توسط شما برای شناسایی یک تراکنش خارجی ایجاد میشود.
گزارش تراکنشهای خارجی جدید به گوگل پلی
با API externaltransactions ادغام شوید تا تراکنشهای خارج از سیستم صورتحساب گوگل پلی در کشورهای پشتیبانیشده، از جمله تراکنشهای بدون دلار حاصل از خریدهای آزمایشی رایگان و نصب برنامهها، گزارش شوند . شما فقط باید تراکنشهای مربوط به صورتحساب را شروع و گزارش کنید و برنامهها را برای کشورهای کاربر واجد شرایط، طبق دستورالعملهای صورتحساب جایگزین یا پیشنهادات خارجی ، لینک کنید. در غیر این صورت، فراخوانی API رد میشود. این امر در مورد همه تراکنشها، از جمله خریدهای جدید، تمدیدها، افزایشها، ارتقاءها، تنزلها و دانلودهای برنامه صدق میکند.
گزارش تراکنشهای خارجی
شما باید پس از تأیید پرداخت از طریق یک برنامه صدور صورتحساب و پیوند، API externaltransactions را برای گزارش یک تراکنش خارجی فراخوانی کنید. این امر در مورد همه تراکنشها، از جمله هزینههای اولیه، تمدیدها، بازپرداختها و موارد دیگر صدق میکند. برای الزامات گزارش، به دستورالعملهای مربوط به برنامه صدور صورتحساب و پیوند مربوطه مراجعه کنید.
هر تراکنش خارجی با یک شناسه تراکنش خارجی گزارش میشود. برای خریدهای مکرر (مانند اشتراکهای تمدید خودکار)، باید شناسه تراکنش خارجی مرتبط با اولین تراکنش در خرید مکرر را به عنوان پارامتری برای هرگونه تراکنش بعدی، از جمله بازپرداختها، ارسال کنید. این کار سری تراکنشهای آن خرید را ثبت میکند. شما باید برای خریدهایی که محصول تغییر میکند (مانند ارتقاء یا تنزل رتبه)، یا اگر تراکنش مکرر لغو یا منقضی شده و همان محصول بعداً دوباره خریداری میشود، یک شناسه تراکنش خارجی جدید ارسال کنید. شما نباید هیچ گونه اطلاعات شخصی قابل شناسایی، اطلاعات اختصاصی یا محرمانه را به عنوان بخشی از این شناسه تراکنش خارجی وارد کنید.
گزارش تراکنش اولیه
هر بار که یک خرید جدید یا دانلود برنامه در برنامههای صورتحساب و پیوند موفقیتآمیز باشد، باید API externaltransactions را فراخوانی کنید.
externalTransactionToken که توسط برنامه از طریق UserChoiceBillingListener ، AlternativeBillingOnlyReportingDetailsListener یا BillingProgramReportingDetailsListener دریافت میشود، به عنوان بخشی از بدنه درخواست برای دانلود برنامه، خریدهای یکباره و تراکنشهای بار اول در یک خرید تکرارشونده (مانند اشتراک) مورد نیاز است. این تراکنش اولیه نامیده میشود. پس از تراکنش اولیه، تراکنشهای بعدی (مانند تمدید اشتراک) را با ارائه یک externalTransactionId منحصر به فرد جدید گزارش دهید. برای جزئیات بیشتر در مورد نحوه گزارش تراکنشهای بعدی، به بخش «گزارش تراکنشهای بعدی برای یک خرید» مراجعه کنید.
مثال :
- یک توسعهدهنده، پرداخت جایگزین را در برنامه خود پیکربندی و فعال میکند.
- کاربر ۱ در کره جنوبی، یک کشور پشتیبانیشده، است و در تلاش است
product1با قیمت ۱۲۶۳۴.۱۰ وون کره جنوبی در ماه، به همراه یک ماه استفاده آزمایشی رایگان، خریداری کند. - برنامه، جریان خرید را با
ProductDetailsبرایproduct1و پیشنهادی که کاربر انتخاب کرده است، راهاندازی میکند. - کاربر ۱ سیستم پرداخت جایگزین توسعهدهنده را انتخاب میکند.
-
UserChoiceBillingListenerمقدارmy_tokenرا به عنوانexternalTransactionTokenدریافت میکند. - سپس توسعهدهنده اطلاعات مربوطه (مقدار
externalTransactionTokenو محصولات خریداری شده) را به backend خود ارسال میکند. سپس، آنها جریان خرید را برایproduct1در سیستم صورتحساب جایگزین راهاندازی میکنند. به این تراکنش یک شناسه تراکنش منحصر به فرد در سمت توسعهدهنده اختصاص داده میشود که برای گزارش آن به Google Play استفاده میشود: 123-456-789 . شناسه تراکنش مورد نیاز است، حتی اگر کاربر یک دوره آزمایشی رایگان دریافت کند. - پس از انجام تراکنش خرید در سیستم پرداخت جایگزین، توسعهدهنده تراکنش را با درخواست زیر به گوگل پلی گزارش میدهد. در ابتدا به عنوان یک تراکنش صفر دلاری گزارش میشود زیرا کاربر یک ماه رایگان دریافت میکند.
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"
}
}
هنگام گزارش اولین تراکنش، به موارد زیر توجه کنید:
-
subscriptionTypeمیتواندRECURRING(برای اشتراکهای تمدید خودکار) یاPREPAID(برای اشتراکهای پیشپرداخت) باشد. - برای نمایش خریدهای یکباره که نیاز به پرداختهای متعدد یا پرداخت با تأخیر دارند، باید از
OtherRecurringProductاستفاده شود. برای مثال، یک پیشسفارش ممکن است یک تراکنش اولیه با مبلغ ۰ دلار داشته باشد و به دنبال آن، پس از تکمیل پیشسفارش، تراکنش دوم در تاریخ بعدی برای قیمت SKU انجام شود. برای جزئیات بیشتر در مورد گزارش تراکنشهای بعدی، به بخش «گزارش تراکنشهای بعدی برای یک خرید» مراجعه کنید. - هنگام گزارش اولین تراکنشهای پیشنهاد خارجی، باید
ExternalOfferDetailsرا ارائه دهید. این مورد برای تراکنشهای بعدی لازم نیست.
اگر با کاربری در هند تراکنش انجام میدهید که مالیات به منطقه اداری او (مانند ایالت یا استان) بستگی دارد، آن منطقه را در قسمت 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"
}
}
پیشنهادهای خارجی
اگر تراکنش گزارششده تحت برنامه پیشنهادهای خارجی باشد، باید فیلد externalOfferDetails را تنظیم کنید، اگر تراکنش یک تراکنش یکباره یا اولین تراکنش از یک سری تراکنشهای تکرارشونده باشد:
- هنگام گزارش تراکنشهای دانلود برنامه،
linkTypeرویLINK_TO_APP_DOWNLOADتنظیم کنید و مقادیر مناسب را برایinstalledAppPackageوinstalledAppCategoryارائه دهید. برای جزئیات بیشتر به بخش گزارش دانلود برنامه مراجعه کنید. - هنگام گزارش تراکنشهای پیشنهاد محتوای دیجیتال،
linkTypeرویLINK_TO_DIGITAL_CONTENTتنظیم کنید. - پس از نصب یک برنامه خارجی از طریق برنامه پیشنهادات خارجی، باید تراکنشهای انجام شده در برنامه خارجی را گزارش دهید. هنگام گزارش این تراکنشها، این تراکنشها را به رویداد دانلود برنامه اصلی پیوند دهید:
-
externalTransactionTokenرا از رویداد دانلود برنامه ارائه دهید. - در فیلد
externalOfferDetails، مقدارappDownloadEventExternalTransactionIdبرابر باexternalTransactionIdرویداد دانلود برنامه قرار دهید. فیلدهای دیگر درexternalOfferDetailsالزامی نیستند.
-
مثال درخواست تراکنش در یک برنامه خارجی که از طریق پیشنهادات خارجی دانلود شده است:
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=ABC-DEF-GHI
Body
{
"originalPreTaxAmount" : {
"priceMicros": "100000",
"currency": "EUR"
},
"originalTaxAmount" : {
"priceMicros": "10000",
"currency": "EUR"
},
"transactionTime" : "2025-11-22T12:45:00Z",
"oneTimeTransaction" : {
"externalTransactionToken": my_external_transaction_token_for_link_to_download_event"
},
"userTaxAddress" : {
"regionCode": "DE"
},
"externalOfferDetails" : {
"appDownloadEventExternalTransactionId": "my_external_transaction_id_for_link_to_download_event"
}
}
جزئیات بهروز شده هزینه خدمات Play برای انواع مختلف تراکنش را میتوانید در «تغییرات در برنامه پیشنهادات خارجی برای کاربران منطقه اقتصادی اروپا (EEA)» بیابید.
گزارش تراکنشهای بعدی برای یک خرید
در برخی موارد، بیش از یک پرداخت کاربر با یک خرید خارجی مرتبط است، به عنوان مثال تمدید اشتراک یا شارژ طرح پیشپرداخت. میتوانید این تراکنشهای بعدی را با استفاده از همان API در Externaltransactions گزارش دهید. همانطور که در گزارش خرید جدید توضیح داده شد، externalTransactionToken برای تراکنشهای بعدی ضروری نیست. در عوض، یک externalTransactionId منحصر به فرد جدید به عنوان پارامتر پرس و جو برای هر تراکنش تمدید یا شارژ ارسال میشود، که شناسه تراکنش اولیه در فیلد initialExternalTransactionId گنجانده شده است.
طبق مثال قبلی :
- اولین تمدید حساب کاربر ۱ در سیستم صورتحساب جایگزین انجام میشود. شناسه تراکنش اولیه ۱۲۳-۴۵۶-۷۸۹ بوده است.
- توسعهدهنده، تکرار تراکنش را در پارامتر کوئری URL به عنوان شناسه تراکنش خارجی برای این تراکنش جدید گزارش میدهد، در حالی که شناسه تراکنش خارجی تراکنش اولیه را در فیلد
initialExternalTransactionIdارجاع میدهد.
نمونه درخواست :
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"
}
}
گزارش ارتقا یا تنزل رتبه
برای گزارش ارتقا یا تنزل رتبه زمانی که کاربر در سیستم پرداخت جایگزین اشتراک دارد، از همان نقطه پایانی و عملکرد در API Externaltransactions استفاده میکنید و externalTransactionToken را که برای تراکنش ارتقا یا تنزل رتبه به برنامه ارائه شده است، ارسال میکنید. این کار مشابه گزارش یک خرید جدید عمل میکند.
گزارش دانلود برنامه
برای گزارش نصب برنامه در سیستم صورتحساب پیشنهادات خارجی، باید Externaltransactions.createexternaltransaction را فراخوانی کنید و externalTransactionToken ارائه شده به برنامه را ارسال کنید. این را به عنوان یک تراکنش بدون هزینه و یک بار گزارش دهید؛ این فرآیند مشابه گزارش یک تراکنش اولیه است. حتماً ExternalOfferDetails در بدنه درخواست وارد کنید.
نمونه درخواست :
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789
Body
{
"originalPreTaxAmount" : {
"priceMicros": "0",
"currency": "USD"
},
"originalTaxAmount" : {
"priceMicros": "0",
"currency": "USD"
},
"transactionTime" : "2025-12-22T12:45:00Z",
"oneTimeTransaction" : {
"externalTransactionToken": "my_token",
},
"userTaxAddress" : {
"regionCode": "US"
}
"externalOfferDetails" : {
"linkType" : "LINK_TO_APP_DOWNLOAD",
"installedAppPackage" : "my.external.app",
"installedAppCategory" : "APP"
}
}
از گزارش دستی تراکنشهای صورتحساب جایگزین، به حالت قبل مهاجرت کنید
برای انتقال اشتراکهای فعالی که در زمان ارائه صورتحساب جایگزین بدون گزارش خودکار شروع شدهاند، به جای مشخص کردن initialExternalTransactionId یا externalTransactionToken ، با استفاده از فیلد migratedTransactionProgram یک تراکنش بدون هزینه جدید ایجاد کنید. 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 Media Experience Program شرکت میکنند، باید هنگام گزارش تراکنشهای خارجی، کد transaction_program_code را ارائه دهند. اگر شما یک توسعهدهنده واجد شرایط هستید، برای اطلاعات بیشتر در مورد نحوه تنظیم این فیلد با مدیر توسعه کسبوکار خود تماس بگیرید.
گزارش بازپرداخت خرید به Google Play
با API externaltransactions ادغام شوید تا تراکنشهای بازپرداختشده به کاربران خارج از سیستم صورتحساب Google Play را گزارش دهید. برای اینکه Play بتواند به درستی تشخیص دهد کدام تراکنش بازپرداخت شده است، باید externalTransactionId مربوط به تراکنش گزارششده قبلی را به عنوان بخشی از پارامترهای URL وارد کنید.
هنگام گزارش بازپرداخت خریدهای اشتراک، به externalTransactionId مربوط به دوره خاص اشتراکی که بازپرداخت میشود، مراجعه کنید.
مثال : فرض کنید یک اشتراک شامل تراکنشهای زیر است:
یک تراکنش اولیه با شناسه تراکنش خارجی ABC.1234-5678-9012-34567
اولین تراکنش تکرارشونده با شناسه تراکنش خارجی ABC.1234-5678-9012-34567..0
دومین تراکنش تکرارشونده با شناسه تراکنش خارجی ABC.1234-5678-9012-34567..1
برای گزارش بازپرداخت تمام تراکنشهای اشتراک، باید سه درخواست بازپرداخت جداگانه ارسال کنید: یکی برای تراکنش اولیه و دو تا برای تراکنشهای بعدی.
این روش هم بازپرداخت کامل (که در آن مبلغ همان مبلغی است که کاربر در تراکنش خارجی اصلی پرداخت کرده است) و هم بازپرداخت جزئی (که در آن مبلغ کمتر از مبلغی است که کاربر در تراکنش خارجی اصلی پرداخت کرده است) را میپذیرد. برای بازپرداخت جزئی، باید مبلغ قبل از کسر مالیات که بازپرداخت شده است را مشخص کنید.
سهمیههای API
API مربوط به Externaltransactions API) برای همه فراخوانیها، درست مانند هر نقطه پایانی دیگری در API توسعهدهندگان گوگل پلی، مشمول سهمیه API است.
علاوه بر این، API Externaltransactions محدودیت ۱۲۰۰ پرسوجو در دقیقه (QPM) برای فراخوانیهای Externaltransactions.createexternaltransaction یا Externaltransactions.refundexternaltransaction دارد. فراخوانیهای Externaltransactions.getexternaltransaction جزو این محدودیت ۱۲۰۰ پرسوجو در دقیقه محسوب نمیشوند.