ממשק API של Google Play למפתחים כולל פונקציונליות נוספת לדיווח על עסקאות מחיוב ומתוכניות קישור. במדריך הזה מוסבר איך לדווח על עסקאות מתוכניות החיוב האלה.
יכול להיות שיהיה צורך בכמה רכיבים כדי לטפל בעסקאות חיצוניות מה-backend שלכם. כדי ליצור אותם, צריך להגדיר את השילוב של קצה העורפי כמו שמתואר במאמר הגדרת ממשק ה-API של Google Play למפתחים. כדי לפתח פונקציונליות בקצה העורפי של המפתח שלא קשורה ספציפית לחיוב ולתוכניות קישור, אפשר לעיין במאמר מערכת החיוב של Google Play.
מילון מונחים
מוסכמות לגבי מונחים שמופיעים במדריך הזה:
- תוכניות חיוב ותוכניות קישורים: תוכניות שמסייעות ברכישת תוכן דיגיטלי או בהורדת אפליקציות מחוץ ל-Google Play. התוכניות האלה כוללות את התוכניות מערכת חיוב חלופית ותוכן חיצוני.
- ממשקי API לעסקאות חיצוניות: ממשקי API שמשמשים לדיווח על עסקאות בתוכניות חיוב וקישורים שעומדות בדרישות.
- עסקה חיצונית: עסקה שעומדת בדרישות ומתרחשת מחוץ לאפליקציה, כפי שמוגדר בתוכניות מערכת חיוב חלופית ותוכן חיצוני.
- טוקן של עסקה חיצונית: טוקן שסופק דרך ספריית החיוב של Play כדי שתוכלו להשתמש בו כשהמשתמש יוזם עסקה חיצונית. הטוקן הזה משמש כדי להודיע ל-Google Play על עסקה חיצונית מורשית.
- מזהה עסקה חיצוני: מזהה ייחודי שנוצר על ידכם כדי לזהות עסקה חיצונית.
דיווח על עסקאות חיצוניות חדשות ל-Google Play
משלבים את ה-API של externaltransactions כדי לדווח על עסקאות שמתרחשות מחוץ למערכת החיוב של Google Play במדינות נתמכות, כולל עסקאות בסך 0 $ שנובעות מרכישות של תקופות ניסיון בחינם ומהתקנות של אפליקציות. צריך להתחיל ולדווח על עסקאות בתוכניות חיוב וקישור רק במדינות של משתמשים שעומדים בדרישות, כפי שמותר במסגרת התוכניות של מערכת חיוב חלופית ותוכן חיצוני. אחרת, הקריאה ל-API תידחה. התנאים האלה חלים על כל העסקאות, כולל רכישות חדשות, חידושים, טעינות, שדרוגים, שדרוגים לאחור והורדות של אפליקציות.
דיווח על עסקאות חיצוניות
צריך להפעיל את externaltransactions API כדי לדווח על עסקה חיצונית אחרי שהתשלום אושר דרך תוכנית חיוב וקישור.
ההנחה חלה על כל העסקאות, כולל חיובים ראשוניים, חידושים, החזרים כספיים ועוד. כדי לראות את דרישות הדיווח, אפשר לעיין בהנחיות לגבי תוכנית הקישור והחיוב הרלוונטיות.
כל עסקה חיצונית מדווחת עם מזהה עסקה חיצוני. ברכישות חוזרות (כמו מינויים שמתחדשים אוטומטית), צריך לשלוח את מזהה העסקה החיצוני שמשויך לעסקה הראשונה ברכישה החוזרת כפרמטר לכל העסקאות הבאות, כולל החזרים כספיים. האירוע הזה מתעד את סדרת העסקאות של הרכישה. צריך לשלוח מזהה עסקה חיצוני חדש לרכישות כשהמוצר משתנה (למשל, שדרוג או שדרוג לאחור), או אם העסקה החוזרת מבוטלת או פג תוקפה ואותו מוצר נרכש שוב מאוחר יותר. אסור לכלול פרטים אישיים מזהים, מידע קנייני או מידע סודי במסגרת מזהה העסקה החיצוני הזה.
דיווח על עסקה ראשונית
בכל פעם שמאושרת רכישה חדשה או הורדה של אפליקציה בתוכניות החיוב והקישור, צריך להפעיל את ה-API של externaltransactions.
הערך של externalTransactionToken שהאפליקציה מקבלת דרך ספריית החיובים של Google Play נדרש כחלק מגוף הבקשה להורדות של אפליקציות, לרכישות חד-פעמיות ולעסקאות ראשונות ברכישה חוזרת (כמו מינוי). העסקה הזו נקראת עסקה ראשונית. אחרי העסקה הראשונית, כדי לדווח על עסקאות נוספות (כמו חידוש מינוי), צריך לספק מזהה עסקה ייחודי חדש externalTransactionId. מידע נוסף זמין במאמר בנושא דיווח על טרנזקציות שבוצעו אחרי רכישה.
דוגמה:
- מפתחים מגדירים ומפעילים מערכת חיוב חלופית באפליקציה שלהם.
- משתמש 1 נמצא בדרום קוריאה, מדינה נתמכת, ומנסה לקנות את
product1, במחיר של 12,634.10KRW לחודש, עם מבצע של תקופת ניסיון בחינם למשך חודש. - האפליקציה מפעילה את תהליך הרכישה עם
ProductDetailsעבורproduct1וההצעה שהמשתמש בחר. - משתמש 1 בוחר במערכת החיוב החלופית של המפתח.
- השדה
UserChoiceBillingListenerמקבל את הערךmy_tokenבתורexternalTransactionToken. - לאחר מכן, המפתח שולח את המידע הרלוונטי לקצה העורפי שלו (הערך של
externalTransactionTokenוהמוצרים שנרכשים). לאחר מכן, הם מפעילים את תהליך הרכישה שלproduct1במערכת החיוב החלופית. לעסקה הזו מוקצה מזהה עסקה ייחודי בצד המפתח, שמשמש לדיווח על העסקה ל-Google Play: 123-456-789. חובה להזין את מזהה העסקה, גם אם המשתמש מקבל תקופת ניסיון בחינם. - אחרי שהעסקה לרכישה מתבצעת במערכת החיוב החלופית, המפתח מדווח על העסקה ל-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 Reference Guide.
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).
דיווח על עסקאות נוספות של רכישה
במקרים מסוימים, יש יותר מתשלום אחד של משתמש שמשויך לאותה רכישה חיצונית, למשל חידושי מינוי או טעינות של מינוי בתשלום מראש.
אפשר לדווח על העסקאות הבאות באמצעות אותו API ב-Externaltransactions. כמו שמתואר במאמר דיווח על רכישה חדשה, אין צורך בפרמטר externalTransactionToken בעסקאות הבאות. במקום זאת, מזהה חדש וייחודי externalTransactionId נשלח כפרמטר השאילתה לכל עסקה של חידוש או טעינה, ומזהה העסקה הראשונית נכלל בשדה initialExternalTransactionId.
בהמשך לדוגמה הקודמת:
- החידוש הראשון של משתמש 1 מתבצע במערכת החיוב החלופית. מזהה העסקה הראשוני היה 123-456-789.
- המפתח מדווח על העסקה החוזרת בפרמטר של השאילתה בכתובת ה-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 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"
}
}
מעבר מדיווח ידני על עסקאות במערכת חיוב חלופית
כדי להעביר מינויים פעילים שהתחילו כשהצעתם מערכת חיוב חלופית בלי דיווח אוטומטי, צריך ליצור עסקה חדשה ללא עלות באמצעות השדה 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 של המינוי הספציפי שמתחדש באופן קבוע ושעליו ניתן החזר כספי.
דוגמה: נניח שיש מינוי עם העסקאות הבאות:
עסקה ראשונית עם מזהה עסקה חיצוני ABC.1234-5678-9012-34567
העסקה החוזרת הראשונה עם מזהה העסקה החיצוני ABC.1234-5678-9012-34567..0
העסקה החוזרת השנייה עם מזהה העסקה החיצוני ABC.1234-5678-9012-34567..1
כדי לדווח על החזר כספי של כל העסקאות במינוי, צריך לשלוח שלוש בקשות נפרדות להחזר כספי: אחת לעסקה הראשונית ושתיים לעסקאות הבאות.
השיטה הזו מקבלת גם החזרים כספיים מלאים (כשהסכום זהה לסכום שהמשתמש שילם בעסקה החיצונית המקורית) וגם החזרים כספיים חלקיים (כשהסכום קטן יותר מהסכום שהמשתמש שילם בעסקה החיצונית המקורית). במקרה של החזרים כספיים חלקיים, צריך לציין את הסכום לפני מס שהוחזר.
מכסות ל-API
ממשק Externaltransactions API כפוף למכסות API לכל הקריאות, בדיוק כמו כל נקודת קצה אחרת בממשק API של Google Play למפתחים.
בנוסף, ל-Externaltransactions API יש מגבלה של 1,200 שאילתות לדקה (QPM) על קריאות ל-Externaltransactions.createexternaltransaction או ל-Externaltransactions.refundexternaltransaction. קריאות ל-Externaltransactions.getexternaltransaction לא נכללות במגבלה של 1,200 QPM.