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