راهنمایی‌های یکپارچه‌سازی زیرینه برای درآمدزایی خارج از «خدمات صورت‌حساب Google Play»

Google Play Developer API شامل عملکرد اضافی برای گزارش کردن تراکنش‌های برنامه‌های پیوند و صورت‌حساب است. این راهنما نحوه گزارش کردن تراکنش‌های این برنامه‌های صورت‌حساب را شرح می‌دهد.

چند مؤلفه وجود دارد که ممکن است برای رسیدگی به تراکنش‌های خارجی از باطن شما ضروری باشد. برای ساختن آن‌ها، باید ادغام با پس‌بخش را همان‌طور که در پیکربندی Google Play Developer API نشان داده شده است راه‌اندازی کنید. برای ساختن عملکرد پسای توسعه‌دهنده که مختص صورت‌حساب و برنامه‌های پیوند نیست، به سیستم صورت‌حساب Google Play مراجعه کنید.

واژه‌نامه اصطلاحات

قراردادهای اصطلاحی که در این راهنما دنبال می‌شود:

  • برنامه‌های صورت‌حساب و پیوند: برنامه‌هایی که خرید محتوای دیجیتال یا بارگیری برنامه را در خارج از Google Play تسهیل می‌کنند. این شامل برنامه‌های صورت‌حساب جایگزین و محتوای خارجی می‌شود.
  • میاناهای برنامه‌سازی کاربردی تراکنش خارجی: میاناهای برنامه‌سازی کاربردی که برای گزارش کردن تراکنش‌ها برای برنامه‌های پیوند و صورت‌حساب واجدشرایط استفاده می‌شوند.
  • تراکنش خارجی: تراکنش واجدشرایطی که خارج از برنامه انجام می‌شود، همان‌طور که در برنامه‌های صورت‌حساب جایگزین و محتوای خارجی تعریف شده است.
  • کد تراکنش خارجی: کدی که ازطریق «کتابخانه خدمات صورت‌حساب Play» ارائه می‌شود تا وقتی کاربر تراکنش خارجی را شروع می‌کند از آن استفاده کنید. این ژتون برای مطلع کردن Google Play از تراکنش خارجی مجاز استفاده می‌شود.
  • شناسه تراکنش خارجی: شناسه یکتایی که شما برای شناسایی تراکنش خارجی ایجاد کرده‌اید.

پیکربندی اجازه‌های «کنسول Play»

برای فراخوانی میانای برنامه‌سازی کاربردی externaltransactions جهت گزارش کردن یا مسترد کردن تراکنش‌های خارجی، به حساب سرویس خود اجازه مدیریت سفارش‌ها و اشتراک‌ها را در «کنسول Google Play» اعطا کنید. می‌توانید این اجازه را در سطح حساب یا برای برنامه‌های خاصی اعطا کنید.

برای دستورالعمل‌های مربوط به ایجاد حساب خدمات و اعطای اجازه‌ها در «کنسول Play»، استفاده از حساب خدمات را ببینید. برای اطلاعات بیشتر درباره اجازه‌های «کنسول Play»، به افزودن کاربران حساب توسعه‌دهنده و مدیریت اجازه‌ها مراجعه کنید.

گزارش کردن تراکنش‌های خارجی جدید به Google Play

با externaltransactions API ادغام کنید تا تراکنش‌هایی را که خارج از سیستم صورت‌حساب Google Play در کشورهای پشتیبانی‌شده اتفاق می‌افتد گزارش کنید، ازجمله تراکنش‌های ۰ دلاری که ناشی از خریدهای دوره آزمایشی رایگان و نصب برنامه است. فقط باید تراکنش‌ها را در برنامه‌های صورت‌حساب و پیوند برای کشورهای واجدشرایط کاربر، طبق آنچه تحت برنامه‌های صورت‌حساب جایگزین و محتوای خارجی مجاز است، شروع و گزارش کنید؛ درغیراین‌صورت، فراخوانی میانای برنامه‌سازی کاربردی رد می‌شود. این امر برای همه تراکنش‌ها، ازجمله خریدهای جدید، تمدیدها، افزایش موجودی‌ها، ارتقاها، تنزل‌ها، و بارگیری‌های برنامه اعمال می‌شود.

گزارش تراکنش خارجی

باید externaltransactions API را فراخوانی کنید تا تراکنش خارجی را پس‌از تأیید پرداخت ازطریق برنامه صورت‌حساب و پیوند گزارش کنید. این امر برای همه تراکنش‌ها، ازجمله هزینه‌های اولیه، تمدیدها، استردادها، و غیره اعمال می‌شود. برای اطلاع از الزامات گزارش‌دهی، به دستورالعمل‌های مربوط به برنامه صورت‌حساب و پیوند مربوطه مراجعه کنید.

هر تراکنش خارجی با شناسه تراکنش خارجی گزارش می‌شود. برای خریدهای تکرارشونده (مانند اشتراک‌های تمدیدشدنی خودکار)، باید شناسه تراکنش خارجی مرتبط با اولین تراکنش در خرید تکرارشونده را به‌عنوان پارامتری برای تراکنش‌های بعدی، ازجمله بازپرداخت‌ها، ارسال کنید. این شماره مجموعه تراکنش‌های آن خرید را ثبت می‌کند. وقتی محصول تغییر می‌کند (مثلاً ارتقا یا تنزل)، یا اگر تراکنش تکرارشونده لغو یا منقضی می‌شود و همان محصول بعداً دوباره خریداری می‌شود، باید شناسه تراکنش خارجی جدیدی برای خریدها ارسال کنید. نباید هیچ‌گونه اطلاعات شناساننده شخصی، اطلاعات اختصاصی، یا محرمانه را به‌عنوان بخشی از این شناسه تراکنش خارجی اضافه کنید.

گزارش کردن تراکنش اولیه

هر بار که خرید جدید یا بارگیری برنامه در برنامه‌های صورت‌حساب و پیوند مجاز می‌شود، باید با میانای برنامه‌سازی کاربردی externaltransactions تماس بگیرید.

‫externalTransactionToken دریافتی برنامه ازطریق «کتابخانه صورت‌حساب Google Play» به‌عنوان بخشی از متن درخواست برای بارگیری برنامه، خریدهای یک‌باره، و تراکنش‌های اولیه در خرید تکرارشونده (مانند اشتراک) الزامی است. به این تراکنش، تراکنش اولیه می‌گویند. پس‌از تراکنش اولیه، تراکنش‌های بعدی (مانند تمدید اشتراک) را با ارائه externalTransactionId یکتای جدید گزارش کنید. برای اطلاعات بیشتر، گزارش کردن تراکنش‌های بعدی برای خرید را ببینید.

مثال:

  1. توسعه‌دهنده صورت‌حساب جایگزین را در برنامه‌اش پیکربندی و فعال می‌کند.
  2. کاربر ۱ در کره جنوبی، کشور پشتیبانی‌شده، است و می‌خواهد product1 را با قیمت ۱۲۶۳۴.۱۰ وون کره جنوبی در ماه با پیشنهاد دوره آزمایشی رایگان یک‌ماهه خریداری کند.
  3. برنامه جریان خرید را با ProductDetails برای product1 و پیشنهاد ویژه‌ای که کاربر انتخاب کرده است راه‌اندازی می‌کند.
  4. کاربر ۱ سیستم صورت‌حساب جایگزین توسعه‌دهنده را انتخاب می‌کند.
  5. UserChoiceBillingListener مقدار my_token را به‌عنوان externalTransactionToken دریافت می‌کند.
  6. سپس توسعه‌دهنده اطلاعات مربوطه را به باطن خود ارسال می‌کند (مقدار externalTransactionToken و محصولاتی که خریداری می‌شوند). سپس، جریان خرید product1 را در سیستم صورت‌حساب جایگزین راه‌اندازی می‌کند. این تراکنش یک شناسه تراکنش یکتا در سمت توسعه‌دهنده دارد که برای گزارش آن به Google Play استفاده می‌شود: ۱۲۳-۴۵۶-۷۸۹. شناسه تراکنش الزامی است، حتی اگر کاربر دوره آزمایشی رایگان دریافت کند.
  7. پس‌از انجام تراکنش خرید در سیستم صورت‌حساب جایگزین، توسعه‌دهنده تراکنش را با درخواست زیر به 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 گنجانده می‌شود.

به‌دنبال مثال قبلی:

  1. اولین تمدید «کاربر ۱» در سیستم صورت‌حساب جایگزین انجام می‌شود. شناسه تراکنش اولیه ۱۲۳-۴۵۶-۷۸۹ بود.
  2. توسعه‌دهنده تکرار تراکنش را در پارامتر پُرسمان نشانی وب به‌عنوان شناسه تراکنش خارجی برای این تراکنش جدید گزارش می‌کند، درحالی‌که به شناسه تراکنش خارجی تراکنش اولیه در فیلد 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 جزو این محدودیت ۱۲۰۰ درخواست در دقیقه محسوب نمی‌شود.