إرشادات حول دمج الخلفية لتحقيق الربح خارج خدمة "الفوترة في Google Play"

تتضمّن Google Play Developer API وظائف إضافية لإعداد تقارير عن المعاملات من برامج الفوترة والربط. يوضّح هذا الدليل كيفية الإبلاغ عن المعاملات من برامج الفوترة هذه.

هناك بعض المكوّنات التي قد تكون ضرورية للتعامل مع المعاملات الخارجية من الخلفية. لإنشاء هذه المكونات، عليك إعداد عملية الدمج مع الخلفية كما هو موضّح في إعداد Google Play Developer API. لإنشاء وظائف خلفية للمطوّرين غير مرتبطة ببرامج الفوترة والربط، يُرجى الاطّلاع على نظام الفوترة في Google Play.

مسرد المصطلحات

يتّبِع هذا الدليل معنى المصطلحات التالية:

• برامج الفوترة والربط: برامج تسهّل عمليات شراء المحتوى الرقمي أو تنزيل التطبيقات من خارج Google Play. ويشمل ذلك برنامجَي نظام الفوترة البديل والمحتوى الخارجي.
• واجهات برمجة التطبيقات للمعاملات الخارجية: هي واجهات برمجة تطبيقات تُستخدَم لإعداد تقارير عن المعاملات في برامج الفوترة والربط المؤهَّلة.
• المعاملة الخارجية: هي معاملة مؤهَّلة تتم خارج التطبيق على النحو المحدّد في برنامجي نظام الفوترة البديل والمحتوى الخارجي.
• رمز المعاملة الخارجية: هو رمز توفّره Play Billing Library ليستخدمه المطوّرون عندما يبدأ المستخدم معاملة خارجية. يُستخدَم هذا الرمز المميز لإعلام Google Play بمعاملة خارجية معتمَدة.
• معرّف المعاملة الخارجية: هو معرّف فريد تنشئه لتحديد معاملة خارجية.

إبلاغ Google Play بالمعاملات الخارجية الجديدة

يمكنك الدمج مع واجهة برمجة التطبيقات externaltransactions من أجل إعداد تقارير عن المعاملات التي تتم خارج نظام الفوترة في Google Play في البلدان المؤهَّلة، بما في ذلك المعاملات التي تبلغ قيمتها 0 دولار أمريكي الناتجة عن عمليات شراء تجريبية مجانية وعمليات تثبيت التطبيقات. يجب عدم بدء المعاملات وإعداد تقارير عنها في برامج الفوترة والربط إلا في بلدان المستخدمين المؤهَّلة على النحو المسموح به بموجب برنامجَي نظام الفوترة البديل والمحتوى الخارجي، وإلا سيتم رفض طلب البيانات من واجهة برمجة التطبيقات. ينطبق ذلك على جميع المعاملات، بما في ذلك عمليات الشراء الجديدة والتجديد وإضافة الرصيد والترقية وخفض المستوى وتنزيل التطبيقات.

إعداد تقارير المعاملات الخارجية

يجب طلب البيانات من واجهة برمجة التطبيقات externaltransactions لإعداد تقرير عن معاملة خارجية بعد السماح بعملية الدفع من خلال برنامج فوترة وربط. ينطبق ذلك على جميع المعاملات، بما في ذلك الرسوم الأولية وعمليات التجديد وردّ الأموال وغيرها. يُرجى الاطّلاع على الإرشادات الخاصة ببرنامج الفوترة والربط المعنيَّين لمعرفة متطلبات إعداد التقارير.

يتم تسجيل كل معاملة خارجية باستخدام معرّف معاملة خارجية. بالنسبة إلى عمليات الشراء المتكرّرة (مثل الاشتراكات التي يتم تجديدها تلقائيًا)، عليك إرسال معرِّف المعاملة الخارجية المرتبط بالمعاملة الأولى في عملية الشراء المتكرّرة كمعلَمة لأي معاملات لاحقة، بما في ذلك عمليات ردّ الأموال. تسجّل هذه السمة سلسلة المعاملات الخاصة بعملية الشراء هذه. عليك إرسال معرّف معاملة خارجية جديد لعمليات الشراء عند تغيير المنتج (مثل الترقية أو الرجوع إلى إصدار أقدم)، أو إذا تم إلغاء المعاملة المتكررة أو انتهت صلاحيتها وتم شراء المنتج نفسه مرة أخرى لاحقًا. يجب عدم تضمين أي معلومات تكشف الهوية الشخصية أو معلومات مملوكة أو سرية في معرّف المعاملة الخارجية هذا.

الإبلاغ عن معاملة أولية

في كل مرة يتم فيها السماح بعملية شراء جديدة أو تنزيل تطبيق جديد في برامج الفوترة والربط، يجب طلب واجهة برمجة التطبيقات externaltransactions.

يجب تضمين externalTransactionToken التي يتلقّاها التطبيق من خلال Google Play Billing Library ضمن نص الطلب الخاص بعمليات تنزيل التطبيقات وعمليات الشراء لمرة واحدة والمعاملات التي تتم لأول مرة في عملية شراء متكررة (مثل الاشتراك). ويُعرف ذلك باسم المعاملة الأولية. بعد المعاملة الأولية، يجب إعداد تقارير عن المعاملات اللاحقة (مثل تجديد الاشتراكات) من خلال تقديم externalTransactionId جديد وفريد. لمزيد من المعلومات، اطّلِع على مقالة الإبلاغ عن معاملات لاحقة لعملية شراء.

مثال:

1. يضبط المطوّر نظام الفوترة البديل ويفعّله في تطبيقه.
2. يتواجد المستخدم 1 في كوريا الجنوبية، وهي بلد متاح فيه العرض، ويحاول شراء product1 مقابل 12,634.10 وون كوري جنوبي شهريًا، مع عرض يشمل فترة تجريبية مجانية لمدة شهر واحد.
3. يطلق التطبيق مسار الشراء باستخدام ProductDetails لـ product1 والعرض الذي اختاره المستخدم.
4. يختار المستخدم 1 نظام الفوترة البديل الذي يوفّره المطوّر.
5. يتلقّى UserChoiceBillingListener القيمة my_token كـ externalTransactionToken.
6. بعد ذلك، يرسل المطوّر المعلومات ذات الصلة إلى الخلفية (قيمة externalTransactionToken والمنتجات التي يتم شراؤها). بعد ذلك، يبدأ مسار شراء product1 في نظام الفوترة البديل. يتم تخصيص معرّف معاملة فريد لهذه المعاملة من جهة المطوّر ويُستخدَم في إرسال تقرير بها إلى Google Play:‏ 123-456-789. يجب تقديم معرّف المعاملة، حتى إذا كان المستخدم سيحصل على فترة تجريبية مجانية.
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 لتمثيل عمليات الشراء لمرة واحدة التي تتطلّب دفعات متعدّدة أو دفعة متأخرة. على سبيل المثال، قد يتضمّن الطلب المُسبق معاملة أولية بقيمة 0 دولار أمريكي، تليها معاملة ثانية في تاريخ لاحق بسعر رمز التخزين التعريفي عند تنفيذ الطلب المُسبق. لمزيد من التفاصيل حول الإبلاغ عن المعاملات اللاحقة، يُرجى الاطّلاع على مقالة الإبلاغ عن المعاملات اللاحقة لعملية شراء.
• يجب تقديم 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_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 المعدَّلة لأنواع المعاملات المختلفة في مقالة التغييرات في برنامج العروض الترويجية الخارجية للمستخدمين في المنطقة الاقتصادية الأوروبية.

الإبلاغ عن معاملات لاحقة لعملية شراء

في بعض الحالات، يكون هناك أكثر من دفعة واحدة للمستخدم مرتبطة بعملية الشراء الخارجية نفسها، مثل تجديدات الاشتراك أو عمليات إضافة الرصيد إلى خطة الدفع المُسبَق. يمكنك الإبلاغ عن هذه المعاملات اللاحقة باستخدام واجهة برمجة التطبيقات نفسها في Externaltransactions. كما هو موضّح في مقالة الإبلاغ عن عملية شراء جديدة، لا تكون المَعلمة externalTransactionToken ضرورية للمعاملات اللاحقة. بدلاً من ذلك، يتم إرسال externalTransactionId جديد وفريد كمَعلمة طلب بحث لكل معاملة تجديد أو إضافة رصيد، مع تضمين معرّف المعاملة الأولية في حقل initialExternalTransactionId.

استنادًا إلى المثال السابق:

1. يتم تجديد اشتراك المستخدم 1 لأول مرة من خلال نظام الفوترة البديل. كان معرّف المعاملة الأوّلي هو ‎123-456-789.
2. يُبلغ المطوِّر عن تكرار المعاملة في مَعلمة طلب البحث في عنوان URL باعتبارها معرّف المعاملة الخارجية لهذه المعاملة الجديدة، مع الإشارة إلى معرّف المعاملة الخارجية للمعاملة الأولية في الحقل 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، وإرسال 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"
 }
}

نقل البيانات من إعداد التقارير يدويًا لمعاملات نظام الفوترة البديل

ملاحظة: سيتم إيقاف إعداد التقارير يدويًا بشأن نظام الفوترة البديل فقط وميزة "الفوترة حسب اختيار المستخدم". لمزيد من التفاصيل حول المواعيد النهائية لنقل البيانات، يُرجى الاطّلاع على معلومات عن ميزة "الفوترة حسب اختيار المستخدم" على Google Play. احرص على نقل جميع الاشتراكات النشطة التي بدأت عندما كنت توفِّر نظام فوترة بديلاً غير مزود بميزة إعداد التقارير آليًا من خلال واجهة برمجة التطبيقات externaltransactions قبل إيقاف ميزة إعداد التقارير يدويًا.

لنقل الاشتراكات النشطة التي بدأت أثناء توفير نظام فوترة بديل بدون إعداد التقارير آليًا، يمكنك إنشاء معاملة جديدة بدون تكلفة باستخدام الحقل migratedTransactionProgram بدلاً من تحديد initialExternalTransactionId أو externalTransactionToken. اضبط transactionTime على الوقت الذي اشترك فيه المستخدم في البداية لكل اشتراك نشط. بعد ذلك، أبلِغ عن كل معاملة لاحقة لهذه الاشتراكات كالمعتاد من خلال واجهات برمجة التطبيقات، مع تقديم initialExternalTransactionId الذي تم استخدامه سابقًا لإنشاء معاملات التجديد. بعد نقل الاشتراك، لن تحتاج إلى إعداد تقارير يدويًا عن المعاملات اللاحقة للاشتراك، شرط أن يتم إعداد التقارير من خلال الطرق الآلية الموضّحة في هذه الصفحة.

أثناء نقل الاشتراكات، يُرجى الانتباه إلى حدود الحصة المعمول بها للتأكّد من أنّ عملية النقل لا تؤدي إلى انقطاع في الحصة. إذا كان هناك العديد من الاشتراكات التي يجب نقلها، يمكنك توزيعها على مدار عدة أيام أو طلب زيادة في الحصة.

ملاحظة: لن يتمكّن من ضبط الحقل migratedTransactionProgram إلا المطوّرون الذين أتاحوا نظام فوترة بديلاً بدون إعداد تقارير تلقائية. إذا كنت توفّر في السابق نظام فوترة بديلاً غير مزوّد بميزة إعداد التقارير آليًا وظهرت لك رسالة خطأ عند محاولة تقديم طلب لنقل الاشتراك، يمكنك التواصل مع فريق الدعم للحصول على المساعدة.

لا يمكن استخدام الحقل 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

على المطوّرين المشاركين في برامج الشركاء، مثل برنامج Google Play Media Experience، تقديم transaction_program_code عند الإبلاغ عن المعاملات الخارجية. إذا كنت مطوّرًا مؤهَّلاً، يُرجى التواصل مع مدير تطوير الأعمال للحصول على مزيد من المعلومات حول كيفية ضبط هذا الحقل.

الإبلاغ عن عمليات ردّ الأموال المدفوعة مقابل عمليات الشراء إلى Google Play

يمكنك إجراء تكامل مع واجهة برمجة التطبيقات externaltransactions لإعداد تقارير عن المعاملات التي تم ردّ أموالها إلى المستخدمين خارج نظام الفوترة في Google Play. لكي يتمكّن Play من تحديد المعاملة التي تم ردّ أموالها بشكل صحيح، يجب تضمين externalTransactionId المقابل للمعاملة التي تم الإبلاغ عنها سابقًا كجزء من مَعلمات عنوان URL.

عند الإبلاغ عن عمليات ردّ الأموال المدفوعة مقابل عمليات شراء الاشتراكات، يُرجى الإشارة إلى externalTransactionId للتكرار المحدّد للاشتراك الذي يتم ردّ الأموال المدفوعة مقابله.

مثال: لنفترض أنّ أحد الاشتراكات يتضمّن المعاملات التالية:

• معاملة أولية تحمل معرّف معاملة خارجية ABC.1234-5678-9012-34567

• أول معاملة متكرّرة تحمل معرّف معاملة خارجية ABC.1234-5678-9012-34567..0

• ثاني معاملة متكرّرة تحمل معرّف معاملة خارجية ABC.1234-5678-9012-34567..1

للإبلاغ عن ردّ أموال جميع معاملات الاشتراك، عليك تقديم ثلاثة طلبات منفصلة لردّ الأموال، أحدها للمعاملة الأولية واثنان للمعاملات اللاحقة.

تقبل هذه الطريقة كلاً من عمليات ردّ الأموال بالكامل (حيث يكون المبلغ هو نفسه الذي دفعه المستخدم في المعاملة الخارجية الأصلية) وردّ جزء من الأموال (حيث يكون المبلغ أقل من المبلغ الذي دفعه المستخدم في المعاملة الخارجية الأصلية). بالنسبة إلى عمليات ردّ جزء من الأموال، عليك تحديد المبلغ الذي تم ردّه قبل الضريبة.

حصص واجهة برمجة التطبيقات

تخضع واجهة برمجة التطبيقات Externaltransactions للحصص المفروضة على واجهات برمجة التطبيقات لجميع الطلبات، مثل أي نقطة نهاية أخرى في Google Play Developer API.

بالإضافة إلى ذلك، تفرض واجهة برمجة التطبيقات Externaltransactions حدًا أقصى يبلغ 1,200 طلب في الدقيقة على الطلبات التي يتم إرسالها إلى Externaltransactions.createexternaltransaction أو Externaltransactions.refundexternaltransaction. لا يتم احتساب الطلبات إلى Externaltransactions.getexternaltransaction ضمن الحدّ الأقصى البالغ 1,200 طلب بحث في الدقيقة.