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 שמתקבל מהאפליקציה דרך ספריית החיוב של Google Play נדרש כחלק מגוף הבקשה להורדות של אפליקציות, לרכישות חד-פעמיות ולעסקאות ראשונות ברכישה חוזרת (כמו מינוי). הפעולה הזו נקראת עסקה ראשונית. אחרי העסקה הראשונית, צריך לדווח על עסקאות עוקבות (כמו חידוש מינוי) על ידי ציון 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_OFFER. - אחרי התקנה של אפליקציה חיצונית דרך תוכנית המבצעים על אפליקציות חיצוניות, חובה לדווח על עסקאות שבוצעו באפליקציה החיצונית. כשמדווחים על העסקאות האלה, צריך לקשר אותן לאירוע המקורי של הורדת האפליקציה:
- מזינים את
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
בדומה לכל נקודת קצה אחרת ב-Google Play Developer API, Externaltransactions API כפוף למכסות API לכל הקריאות.
בנוסף, ל-Externaltransactions API יש מגבלה של 1,200 שאילתות לדקה (QPM) על קריאות ל-Externaltransactions.createexternaltransaction או ל-Externaltransactions.refundexternaltransaction. שיחות אל Externaltransactions.getexternaltransaction לא נכללות במגבלה של 1,200 בקשות לדקה.