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