Google Play Developer API شامل عملکرد اضافی برای گزارش کردن تراکنش‌های برنامه‌های پیوند و صورت‌حساب است. این راهنما نحوه گزارش کردن تراکنش‌های این برنامه‌های صدور صورت‌حساب را شرح می‌دهد.
چند مؤلفه وجود دارد که ممکن است برای رسیدگی به تراکنش‌های خارجی از باطن شما ضروری باشد. برای ساختن آن‌ها، باید ادغام با پس‌بخش را همان‌طور که در پیکربندی Google Play Developer API نشان داده شده است راه‌اندازی کنید. برای ساختن عملکرد پس‌بست توسعه‌دهنده که مختص برنامه‌های پیوند و صورت‌حساب نیست، سیستم صورت‌حساب Google Play را ببینید.
واژه‌نامه اصطلاحات
قراردادهای اصطلاحی که در این راهنما دنبال می‌شود:
- برنامه‌های صورت‌حساب و پیوند: برنامه‌هایی که خرید محتوای دیجیتال یا بارگیری برنامه را در خارج از Google Play تسهیل می‌کنند. این شامل برنامه‌های صورت‌حساب جایگزین و محتوای خارجی می‌شود.
- میاناهای برنامه‌سازی کاربردی تراکنش خارجی: میاناهای برنامه‌سازی کاربردی که برای گزارش دادن تراکنش‌های برنامه‌های واجدشرایط صورت‌حساب و پیوند استفاده می‌شود.
- تراکنش خارجی: تراکنش واجدشرایطی که خارج از برنامه انجام می‌شود، همان‌طور که در برنامه‌های صورت‌حساب جایگزین و محتوای خارجی تعریف شده است.
- کد تراکنش خارجی: کدی که ازطریق «کتابخانه خدمات صورت‌حساب Play» ارائه می‌شود تا وقتی کاربر تراکنش خارجی را شروع می‌کند از آن استفاده کنید. از این ژتون برای مطلع کردن Google Play از تراکنش خارجی مجاز استفاده می‌شود.
- شناسه تراکنش خارجی: شناسه یکتایی که شما برای شناسایی تراکنش خارجی ایجاد کرده‌اید.
گزارش دادن تراکنش‌های خارجی جدید به Google Play
با externaltransactions API ادغام کنید تا تراکنش‌های انجام‌شده خارج از سیستم صورت‌حساب Google Play را در کشورهای پشتیبانی‌شده، ازجمله تراکنش‌های ۰ دلاری ناشی از خریدهای دوره آزمایشی رایگان و نصب‌های برنامه، گزارش کنید. تراکنش‌ها را فقط باید در برنامه‌های صورت‌حساب و پیوند برای کشورهای واجدشرایط کاربر، طبق آنچه در برنامه‌های صورت‌حساب جایگزین و محتوای برون‌سازمانی مجاز است، شروع و گزارش کنید؛ درغیراین‌صورت، فراخوانی میانای برنامه‌سازی کاربردی رد می‌شود. این امر برای همه تراکنش‌ها، ازجمله خریدهای جدید،
تمدیدها، افزایش موجودی، ارتقا، تنزل، و بارگیری‌های برنامه اعمال می‌شود.
گزارش تراکنش خارجی
باید externaltransactions API را فراخوانی کنید تا تراکنش خارجی را
پس‌از تأیید پرداخت ازطریق برنامه صورت‌حساب و پیوند گزارش کنید.
این امر برای همه تراکنش‌ها، ازجمله هزینه‌های اولیه، تمدیدها، بازپرداخت‌ها،
و غیره اعمال می‌شود. برای اطلاع از الزامات گزارش‌دهی، به دستورالعمل‌های مربوط به برنامه صورت‌حساب و پیوند مربوطه مراجعه کنید.
هر تراکنش خارجی با شناسه تراکنش خارجی گزارش می‌شود. برای خریدهای تکرارشونده (مانند اشتراک‌های تمدیدشدنی خودکار)، باید شناسه تراکنش خارجی مرتبط با اولین تراکنش در خرید تکرارشونده را به‌عنوان پارامتری برای تراکنش‌های بعدی، ازجمله بازپرداخت‌ها، ارسال کنید. این سند مجموعه تراکنش‌های آن خرید را ثبت می‌کند. وقتی محصول تغییر می‌کند (مثلاً ارتقا یا تنزل)، یا اگر تراکنش تکرارشونده لغو یا منقضی می‌شود و همان محصول بعداً دوباره خریداری می‌شود، باید شناسه تراکنش خارجی جدیدی برای خریدها ارسال کنید. نباید هیچ‌گونه اطلاعات شخصی تشخیص‌دهنده هویت، اطلاعات اختصاصی، یا اطلاعات محرمانه را به‌عنوان بخشی از این شناسه تراکنش خارجی اضافه کنید.
گزارش تراکنش اولیه
هر بار که خرید جدید یا بارگیری برنامه‌ای در برنامه‌های صورت‌حساب و پیوند مجاز می‌شود، باید externaltransactions میانای برنامه‌سازی کاربردی را فراخوانی کنید.
externalTransactionToken دریافتی برنامه ازطریق «کتابخانه خدمات صورت‌حساب Google Play» به‌عنوان بخشی از بدنه درخواست برای بارگیری‌های برنامه، خریدهای یک‌باره، و تراکنش‌های بار اول در خرید تکرارشونده (مثل اشتراک) الزامی است. به این حالت تراکنش اولیه می‌گویند. پس‌از تراکنش اولیه، تراکنش‌های بعدی (مانند تمدید اشتراک) را با ارائه externalTransactionId یکتای جدید گزارش کنید. برای اطلاعات بیشتر،
گزارش کردن تراکنش‌های بعدی برای خرید را ببینید.
مثال:
- توسعه‌دهنده صورت‌حساب جایگزین را در برنامه‌اش پیکربندی و فعال می‌کند.
- کاربر ۱ در کره جنوبی، کشور پشتیبانی‌شده، است و می‌خواهد
product1را با قیمت ۱۲۶۳۴.۱۰ وون کره جنوبی در ماه با پیشنهاد دوره آزمایشی رایگان یک‌ماهه خریداری کند. - برنامه جریان خرید را با
ProductDetailsبرایproduct1و پیشنهاد ویژه‌ای که کاربر انتخاب کرده است راه‌اندازی می‌کند. - کاربر ۱ سیستم صورت‌حساب جایگزین توسعه‌دهنده را انتخاب می‌کند.
-
UserChoiceBillingListenerمقدارmy_tokenرا به‌عنوانexternalTransactionTokenدریافت می‌کند. - سپس توسعه‌دهنده اطلاعات مربوطه را به زیرینه خود ارسال می‌کند
(مقدار
externalTransactionTokenو محصولات خریداری‌شده). سپس، جریان خریدproduct1را در سیستم صورت‌حساب جایگزین راه‌اندازی می‌کند. این تراکنش یک شناسه تراکنش منحصربه‌فرد در سمت توسعه‌دهنده دارد که برای گزارش آن به Google Play استفاده می‌شود: ۱۲۳-۴۵۶-۷۸۹. شناسه تراکنش الزامی است، حتی اگر کاربر دوره آزمایشی رایگان دریافت کند. - پس‌از انجام تراکنش خرید در سیستم صورت‌حساب جایگزین، توسعه‌دهنده تراکنش را با درخواست زیر به 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"
}
}
هنگام گزارش کردن تراکنش اولیه، به موارد زیر توجه کنید:
-
subscriptionTypeمی‌تواندRECURRING(برای اشتراک‌های تمدید خودکار) یاPREPAID(برای اشتراک‌های پیش‌پرداخت) باشد. OtherRecurringProductباید برای نشان دادن خریدهای یک‌باره‌ای استفاده شود که به چند پرداخت یا پرداخت با تأخیر نیاز دارند. برای مثال، پیش‌سفارش ممکن است تراکنش اولیه ۰ دلاری داشته باشد و سپس تراکنش دوم در تاریخ دیگری برای قیمت SKU هنگام تکمیل پیش‌سفارش انجام شود. برای جزئیات بیشتر درباره گزارش کردن تراکنش‌های بعدی، به گزارش کردن تراکنش‌های بعدی برای خرید مراجعه کنید.- هنگام گزارش کردن تراکنش‌های پیشنهاد ویژه خارجی اولیه، باید
ExternalOfferDetailsرا ارائه دهید. این کار برای تراکنش‌های بعدی لازم نیست.
اگر با کاربری در هند تراکنش می‌کنید که مالیات او به منطقه اداری‌اش (مثل ایالت یا استان) بستگی دارد، آن منطقه را در بخش
userTaxAddress اضافه کنید. برای تقسیمات کشوری قابل‌اجرا، به فهرست ازپیش تعریف‌شده رشته‌ها در راهنمای مرجع میانای برنامه‌سازی کاربردی مراجعه کنید.
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_OFFERتنظیم کنید. - پس‌از نصب برنامه خارجی ازطریق برنامه پیشنهادهای خارجی، باید تراکنش‌های انجام‌شده در برنامه خارجی را گزارش کنید. هنگام گزارش کردن این تراکنش‌ها، آن‌ها را به رویداد بارگیری برنامه اصلی پیوند دهید:
-
externalTransactionTokenرا از رویداد بارگیری برنامه ارائه دهید. - در فیلد
externalOfferDetails،appDownloadEventExternalTransactionIdرا رویexternalTransactionIdرویداد بارگیری برنامه تنظیم کنید. فیلدهای دیگر درexternalOfferDetailsالزامی نیستند.
-
نمونه درخواست برای تراکنش در برنامه خارجی بارگیری‌شده ازطریق پیشنهادهای خارجی:
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=ABC-DEF-GHI
Body
{
"originalPreTaxAmount" : {
"priceMicros" : "990000", # 0.99 EUR
"currency" : "EUR"
},
"originalTaxAmount" : {
"priceMicros" : "90000", # 0.09 EUR
"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) مشاهده کنید.
گزارش کردن تراکنش‌های بعدی برای خرید
در برخی موارد، بیش از یک پرداخت کاربر با خرید خارجی یکسان مرتبط است، برای مثال تمدید اشتراک یا افزایش اعتبار طرح پیش‌پرداخت.
می‌توانید این تراکنش‌های بعدی را بااستفاده از همان میانای برنامه‌سازی کاربردی در
Externaltransactions گزارش کنید. همان‌طور که در گزارش خرید جدید توضیح داده شده است،
externalTransactionToken برای تراکنش‌های بعدی لازم نیست. به‌جای آن،
یک externalTransactionId یکتای جدید به‌عنوان پارامتر پُرسمان برای هر
تراکنش تمدید یا افزایش موجودی ارسال می‌شود، و شناسه تراکنش اولیه
در فیلد initialExternalTransactionId گنجانده می‌شود.
به‌دنبال مثال قبلی:
- اولین تمدید «کاربر ۱» در سیستم صورت‌حساب جایگزین انجام می‌شود. شناسه تراکنش اولیه 123-456-789 بود.
- توسعه‌دهنده تکرار تراکنش را در پارامتر پُرسمان نشانی وب
به‌عنوان شناسه تراکنش خارجی برای این تراکنش جدید گزارش می‌کند، درحالی‌که
شناسه تراکنش خارجی تراکنش اولیه را در فیلد
initialExternalTransactionIdارجاع می‌دهد.
نمونه درخواست:
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi
Body
{
"originalPreTaxAmount" : {
"priceMicros" : "12634000000", # 12634 KRW
"currency" : "KRW"
},
"originalTaxAmount" : {
"priceMicros" : "1263000000", # 1263 KRW
"currency" : "KRW"
},
"transactionTime" : "2022-02-22T12:45:00Z",
"recurringTransaction" : {
"initialExternalTransactionId" : "123-456-789",
"externalSubscription" : {
"subscriptionType" : "RECURRING"
}
},
"userTaxAddress" : {
"regionCode" : "KR"
}
}
گزارش کردن ارتقا یا تنزل
برای گزارش ارتقا یا تنزل رتبه وقتی کاربر اشتراکی در سیستم صورت‌حساب جایگزین دارد، از همان نقطه پایانی و تابع در Externaltransactions API استفاده می‌کنید و 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 را روی زمانی تنظیم کنید که کاربر در ابتدا برای هر اشتراک فعال ثبت‌نام کرده است. سپس، هر تراکنش بعدی را برای این اشتراک‌ها به‌صورت عادی ازطریق میاناهای برنامه‌سازی کاربردی گزارش کنید و 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 مربوط به تراکنش گزارش‌شده قبلی را به‌عنوان بخشی از پارامترهای نشانی وب اضافه کنید.
هنگام گزارش استرداد مبلغ خریدهای اشتراک، به
externalTransactionId تکرار خاص اشتراکی که
مبلغ آن مسترد می‌شود ارجاع دهید.
مثال: فرض کنید اشتراکی تراکنش‌های زیر را دارد:
تراکنش اولیه با شناسه تراکنش خارجی ABC.1234-5678-9012-34567
اولین تراکنش تکرارشونده با شناسه تراکنش خارجی ABC.1234-5678-9012-34567..0
دومین تراکنش تکرارشونده با شناسه تراکنش خارجی ABC.1234-5678-9012-34567..1
برای گزارش استرداد مبلغ همه تراکنش‌های اشتراک، باید سه درخواست استرداد مبلغ جداگانه ایجاد کنید: یکی برای تراکنش اولیه و دوتا برای تراکنش‌های بعدی.
این روش هم استرداد کامل (که در آن مبلغ همان مبلغی است که کاربر در تراکنش خارجی اصلی پرداخت کرده است) و هم استرداد ناتمام (که در آن مبلغ کمتر از مبلغی است که کاربر در تراکنش خارجی اصلی پرداخت کرده است) را می‌پذیرد. برای استرداد ناتمام، باید مبلغ پیش‌از مالیات را که مسترد شده است مشخص کنید.
سهمیه‌های میانای برنامه‌سازی کاربردی
Externaltransactions API مشمول سهمیه‌های API برای همه فراخوانی‌ها است، درست مانند هر نقطه پایانی دیگری در Google Play Developer API.
علاوه‌براین، Externaltransactions API دارای محدودیت ۱۲۰۰ پُرسمان در دقیقه (QPM) برای تماس‌ها با Externaltransactions.createexternaltransaction یا Externaltransactions.refundexternaltransaction است. تماس با
Externaltransactions.getexternaltransaction جزو این محدودیت ۱٬۲۰۰ تماس در دقیقه
محسوب نمی‌شود.