تقارير عمليات الدفع

نظرة عامة

يتناول هذا المستند محتوى التقارير ويوضح API التي يتم استخدامها لطلبها ويحدد أيضًا التنسيق الذي سيتم عرضها به.

• تنزيل التقارير اليومية
• محتوى التقارير
• أوقات طلب التقارير
• تنزيل التقارير اليومية عبر API
• تنسيق التقارير اليومية
• عنوان التقرير
• عنوان القسم
• عنوان العمود
• بيانات القسم
• تذييل القسم
• تذييل التقرير
• عينة من التقارير

تنزيل التقارير اليومية

لتنزيل تقرير يومي للتطبيقات، بإمكان مسؤول الأعمال الانتقال إلى صفحة إعدادات الشركة، وتحديد الشركة التي يريدها للحصول على التقارير لها والانتقال إلى علامة تبويب "التقارير". سيتمكن في هذه الصفحة من تحديد تاريخ التقرير من خلال أداة التقويم، ونوع التقرير من القائمة المنسدلة للتقرير الذي تريد تنزيله.

كإجراء بديل، بإمكان المسؤول أيضًا الوصول إلى إعدادات الشركة عن طريق الانتقال إلى:

• بالنسبة إلى ألعاب اللوحة: عمليات دفع الويب > عمليات دفع الويب > الشركة > عرض/تعديل
• بالنسبة إلى الألعاب الفورية: الشراء داخل التطبيق > الحساب > الانتقال إلى إعدادات الشركة

بعد تحديد هذه الخيارات، انقر على تنزيل لبدء تنزيل التقرير اليومي لشركتك.

محتوى التقارير

يغطي كل تقرير يوم واحد فقط، وذلك من الساعة 12 صباحًا إلى 11:59:59 مساءً بتوقيت المحيط الهادئ بالولايات المتحدة (التوقيت العالمي المتفق عليه -8/-7)، ويتضمن كل المعاملات التي تمت عبر كل التطبيقات، والتي تم دفعها للشركة ذاتها في ذلك اليوم.

بالنسبة لأي يوم محدد، يوجد تقريران منفصلان يمكنك طلبهما.

• يحتوي التقرير detail على سجل واحد لكل معاملة فردية، أي لكل عملية بيع وكل عملية استرداد أموال، وهكذا. يتم إرسال تقرير التفاصيل من منظور فيسبوك.
• يقدم تقرير digest ملخصًا لكل المعاملات من نوع معين لتطبيق معين.

تقارير الألعاب الفورية متشابهة، ولكنها تحمل أسماءً مختلفة:

• يحتوي التقرير ig_detail على سجل واحد لكل معاملة فردية، أي لكل عملية بيع وكل عملية استرداد أموال، وهكذا.
• يقدم تقرير ig_digest ملخصًا لكل المعاملات من نوع معين للعبة فورية معينة.

تحتوي تقارير عمليات الدفع في الوقت الحالي على قسمين اثنين، وذلك على الرغم من أنه لا يجوز لك أن تعتمد على ذلك عند كتابة أداة التحليل، وذلك لأنه قد تم تصميم تنسيق التقارير ليتم توسيعه بسهولة.

• القسم الأول، credits_digest أو credits_detail حسب التقرير الذي تقوم بقراءته، ويغطي كل المعاملات باستخدام ميزة "نقاط فيسبوك"، ويتضمن كل عمليات الشراء داخل اللعبة والتي تتم من خلال إجراء مربع حوار الدفع buy_item. لقد تم إيقاف استخدام هذا القسم لأنه لم يعد بإمكان المُطوّرين تلقي عمليات الدفع على شكل نقاط فيسبوك بعد الآن.

• القسم الآخر payment_digest أو payment_detail يغطي المعاملات التي تستخدم ميزة عمليات الدفع على فيسبوك، وبالتحديد الاشتراكات وعمليات الدفع.

أوقات طلب التقارير

نُنشئ التقارير الجديدة مرة واحدة يوميًا، ونوفرها اعتبارًا من الظهر بتوقيت المحيط الهادئ بالولايات المتحدة (التوقيت العالمي المتفق عليه -8/-7)، وبذلك عادةً ما يصبح أحدث تاريخ تتوفر فيه التقارير هو اليوم الذي يسبق الطلب. بالنسبة إلى الألعاب الفورية، يوجد تأخير لمدة يومين.

تنزيل التقارير اليومية عبر API

تتوفر تقارير عمليات الدفع عبر API على الويب، وهو ما يتيح لك طلب ملخص أو تقرير مُفصل للغاية للمعاملات التي تمت أثناء يوم معين.

توجد 3 خطوات للحصول على التقارير:

1. الحصول على معرف الشركة والمفتاح السري للشركة
2. الحصول على Company access_token
3. تنزيل ملفات التقرير

الحصول على معرف الشركة والمفتاح السري للشركة

قبل أن تتمكن من المتابعة، ستحتاج إلى التأكد من قيامك بتمكين تطبيق لعمليات الدفع، بما في ذلك إعداد شركة لتلقي عمليات الدفع.

بمجرد قيامك بذلك، ستجد معرف شركتك والمفتاح السري لشركتك في صفحة إعداد الشركة الخاصة بك في علامة التبويب بيانات الاعتماد.

يتم طلب زوج معرف /مفتاح سري واحد فقط للشركة المحددة، ويتم استخدامه في كل تطبيقات تلك الشركة. ستحتاج إلى بيانات الاعتماد هذه حتى تتمكن من الحصول على access_token المطلوب لتنزيل تقارير المعاملات اليومية لتطبيقاتك.

الحصول على Company Access Token

يتيح لك Company Access Token الوصول إلى التقارير الخاصة بكل التطبيقات المقترنة بالشركة التي تم إصدار الرمز نيابةً عنها. للحصول على تقرير، قم بإجراء طلب GET على

https://graph.facebook.com/oauth/access_token?

من خلال معلمات الاستعلام التالية:

لن تنتهي صلاحية هذا الرمز إلا إذا قمتَ بإعادة تعيين المفتاح السري لشركتك؛ لذا يجب تخزينه وإعادة استخدامه بدلاً من إنشاء رمز جديد في كل مرة تقوم فيها بطلب تقارير.

مثال على طلب access_token لصالح شركة

عينة من الطلب:

https://graph.facebook.com/oauth/access_token?
                                 client_id=COMPANY_ID&
                                 client_secret=COMPANY_SECRET&
                                 grant_type=client_credentials

عينة من الاستجابة من فيسبوك:

access_token=230001349987723|aBc_dEFaEUZberrtkrp8pbtwXyZ

تنزيل الملفات اليومية

بمجرد حصولك على access_token لشركتك، يمكنك استخدامه لطلب ملفات تقارير يومية تقوم بتغطية كل تطبيقات شركتك. ننشئ نوعين من التقارير، كما هو مذكور أعلاه:

• يحتوي التقرير digest على صف بيانات لكل زوج مكون من نوع المعاملة والتطبيق، ويقدم ملخصًا لأحداث عمليات البيع وعمليات استرداد الأموال والمعاملات الأخرى لكل تطبيق
• تقرير detail، ويحتوي كما يتضح من اسمه على صف لكل معاملة فردية

لتنزيل ملفات التقرير ليوم معين، قم بإرسال طلب GET إلى

https://paymentreports.facebook.com/COMPANY_ID/report?

من خلال معلمات الاستعلام التالية:

لا يمكن أن يكون date بتاريخ اليوم، كما هو مذكور أعلاه أيضًا. تتوفر التقارير الخاصة بيوم معين بعد الساعة 8 صباحًا بتوقيت المحيط الهادئ بالولايات المتحدة (التوقيت العالمي المتفق عليه -8/-7) في اليوم التالي.

أمثلة على طلبات التقارير اليومية

عينة من طلب مطوّر بخصوص تقرير detail يومي:

wget "https://paymentreports.facebook.com/23459934998762/report?
                                          date=2012-05-15&
                                          type=detail&                                     access_token=234599349987627|aBc_dEFaEUZbqpatkrp8pbtwXyZ"

يقوم التقرير المذكور أعلاه بإرجاع ملف يحمل اسم 23459934998762_detail_2012-05-15.csv.zip.

عينة من طلب مطوّر بخصوص تقرير digest:

wget "https://paymentreports.facebook.com/23459934998762/report?
                                          date=2012-05-15&
                                          type=digest&
                                          access_token=23459934998762|aBc_dEFaEUZbqpatkrp8pbtwXyZ"

يقدم لك التقرير المذكور أعلاه ملفًا يحمل اسم 23459934998762_digest_2012-05-15.csv.zip.

تنسيق التقرير

تشترك كل التطبيقات في بنية عامة شائعة:

• التقارير عبارة عن ملفات نصية لقيم مفصولة بفاصلات (CSV).
• فواصل السطر عبارة عن نمط Unix "\n" (خط جديد).
• يتم وضع الحقول التي تحتوي على فاصلات بين علامتي اقتباس مزدوجة حتى يتم استيرادها إلى Excel بسهولة.
• العمود الأول في كل صف عبارة عن رمز نوع الصف، وهو ما يحدد طريقة تفسير باقي الأعمدة.
• تستخدم التقارير 6 أنواع من الصفوف مقسمة كما يلي:
• عنوان تقرير واحد (نوع الرمز RH)
• قسم واحد أو أكثر، ويتكون كل قسم من
• عنوان قسم واحد (SH)
• عنوان عمود واحد (CH)
• بلا صفوف أو أكثر من صف بيانات قسم (SD)
• تذييل قسم واحد (SF)
• تذييل تقرير واحد (RF)

يمكن عرض هذه البنية كما يلي:

RH,     ...

  SH,   ...
    CH, ...
    SD, ...
    [More section data rows]
  SF,   ...

  SH,   ...
    CH, ...
    SD, ...
    [More section data rows]
  SF,   ...

  [Possibly more sections]

RF,     ...

يُرجى العلم أن المسافة البادئة والتباعد المذكورين أعلاه عبارة عن وسائل للمساعدة على القراءة، ولا يتم وضع مسافة بادئة في التقارير الفعلية، كما أنها لا تتضمن أي مسافات إلا في البيانات في الحقول التي تتضمن مسافات.

ستجد أمثلة تتضمن حقولاً تمت تعبئتها بالكامل في قسم نماذج ملفات في نهاية هذا المستند.

عنوان التقرير (RH)

الصف الأول هو عنوان التقرير، ويحتوي على بيانات تُطبَّق على كل الصفوف أسفله وصولاً إلى تذييل التقرير التالي، وهو ما يحدد نهاية التقرير. تحتوي صفوف RH على الحقول التالية:

مثال على عنوان التقرير

عينة من الصف:

RH,213030545409781,daily_detail,2011-11-21 00:00:00 PST,2011-11-21 23:59:59 PST,1

كيفية قراءة عينة من الصف:

عنوان القسم (SH)

كل صف بين عنوان وتذييل التقرير عبارة عن جزء من قسم. ويظهر في مقدمة كل قسم من أقسام التقرير عنوان قسم، كما يبدأ القسم من عنوانه حتى تذييل القسم التالي. وتحتوي صفوف SH على الحقول التالية:

مثال على عنوان القسم

عينة من الصف:

SH,213030545409781,payment_detail

كيفية قراءة عينة من الصف:

عنوان العمود (CH)

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

أمثلة على عنوان العمود

مثال على صف CH من قسم payment_detail:

CH,app_id,payment_type,product_type,payment_id,time_completed,recv_currency,recv_amount,fx_batch_id,fx_rate,settle_currency,reference_id,tax_country

مثال على صف CH من قسم payment_digest:

CH,app_id,app_name,payment_type,product_type,recv_currency,
,fx_batch_id,fx_rate,settle_currency,settle_amount

بيانات القسم (SD)

بعد عنوان العمود في القسم، لا توجد أي صفوف أو يوجد المزيد من صفوف section data التي تحصل على أسماء حقولها من صف CH. يعتمد معنى الصفوف على نوع القسم: في أقسام detail، كل صف عبارة عن معاملة فردية، أما في أقسام digest، كل صف عبارة عن مجموع كل المعاملات لنوع معين ضمن تطبيق معين (على سبيل المثال، "كل عمليات البيع لمعرف التطبيق 276999562313463"، "كل عمليات استرداد أموال الاشتراكات بالين الياباني لمعرف التطبيق 276899562313544"). توجد حاليًا 4 أنواع من الأقسام موضحة أدناه.

أمثلة على بيانات القسم

صف payment_detailSD

الحقول:

عينة من صف الاشتراك:

SD,266989143414,S,S,267668373345994,2012-07-22 00:07:23 PDT,USD,19.99,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000007,US,0.99

كيفية قراءة عينة من صف الاشتراك:

عينة من صف عمليات الدفع:

SD,480369938658210,S,P,362736900505327,2013-06-12 16:33:52 PDT,USD,1,6E5D989082A04A68AA801DB17A30721A,1,USD,QQ6C7XaxeMyCW4RdZXFGwKTQM1IkMBIOpeWtFFJelHUdSC9NaeYlBXEMJd3LO17k,US,0.09

كيفية قراءة عينة من صف عمليات الدفع:

صف payment_digestSD

الحقول:

عينة من صف الاشتراك:

SD,200000000000002,Game2,S,S,CNY,5000.0,FXBATCHID1,0.2,USD,1000.0,9.99

كيفية قراءة عينة من صف الاشتراك:

عينة من صف عمليات الدفع:

SD,900000000000009,Game9,S,P,CNY,5000.0,FXBATCHID1,0.2,USD,1000.0,9.99

كيفية قراءة عينة من صف عملية الدفع:

تذييل القسم (SF)

كل قسم ينتهي بصف "تذييل القسم"، وهو ما قد يُتبَع إما بقسم جديد يبدأ بصف SH أو بصف "تذييل التقرير"، وهو ما يشير إلى نهاية التقرير. العمود الفردي للبيانات التي تتبع حقل النوع يحتوي على:

مثال على تذييل القسم

عينة من الصف:

SF,7

كيفية قراءة عينة من الصف:

تذييل التقرير (RF)

التقرير ينتهي بصف "تذييل التقرير"، وهو ما يجب أن يكون آخر صف في الملف. يتضمن جزأين من بيانات الملخص بعد عمود النوع الخاص به:

مثال على تذييل التقرير

عينة من الصف:

RF,2,7

كيفية قراءة عينة من الصف:

عينة من التقارير

يمكنك قراءة هذه العينات وفقًا للتعليمات المذكورة أعلاه. يُرجى أيضًا مراعاة ما يلي:

• السطور في الجزء العلوي من كل نموذج من نماذج التقرير عبارة عن عناوين التقرير الشائعة.
• القالب التالي من النص يتضمن القسم credits_detail أو _digest.
• قالب النص بعد ذلك (أعلى التذييل مباشرةً) يتضمن قسم payment_detail أو payment_digest.
• السطور في الجزء السفلي من كل نموذج عبارة عن تذييلات التقرير الشائعة.

عينة من تقرير detail

RH,10808080808080808,daily_detail,2012-04-24 00:00:00 PDT,2012-04-24 23:59:59 PDT,1

SH,10808080808080808,credits_detail
CH,app_id,txn_type,txn_id,order_id,txn_time,value,credits

SH,10808080808080808,payment_detail
CH,app_id,payment_type,product_type,payment_id,time_completed,recv_currency,recv_amount,fx_batch_id,fx_rate,settle_currency,reference_id,tax_country
SD,266989143414,S,S,267668373345994,2012-07-22 00:07:23 PDT,USD,19.99,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000007,US
SD,266989143414,S,S,272014936246430,2012-07-22 00:08:18 PDT,USD,21.09,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000008,US
SD,266989143414,S,S,272990136150221,2012-07-22 00:09:18  PDT,USD,22.99,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000009,CY
SD,266989143414,S,S,278092248972451,2012-07-22 00:08:34 PDT,USD,19.99,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000010,US 
SD,266989143414,S,P,376727629107629,2012-07-22 00:08:34 PDT,USD,19.99,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000010,US 
SF,4 

RF,2,13

عينة من تقرير digest

RH,108080808080808,daily_digest,2012-04-25 00:00:00 PDT,2012-04-25 23:59:59 PDT,1

SH,108080808080808,credits_digest
CH,app_id,app_name,txn_type,value,credits

SH,108080808080808,payment_digest
CH,app_id,app_name,payment_type,product_type,recv_currency,recv_amount,fx_batch_id,fx_rate,settle_currency,settle_amount
SD,200000000000002,Game2,S,S,CNY,5000.0,FXBATCHID1,0.2,USD,1000.0
SD,200000000000002,Game2,R,S,CNY,2000.0,FXBATCHID1,0.2,USD,400.0
SD,200000000000002,Game2,S,P,CNY,1000.0,FXBATCHID1,0.2,USD,200.0
SF,2

RF,2,5

الحسابات

للمساعدة في حساب صافي إيرادات المطوّرين، يُرجى استخدام المعلومات التالية.

عمليات شراء Facebook Pay

تتم الإشارة إلى هذه المعاملات من خلال platform تساوي "F" في تقرير ig_detail أو كل المعاملات في تقرير detail.

افترض أن tax_country "للولايات المتحدة" تعني أن الشراء غير شامل الضريبة وأن الحساب يتبع هذه الصيغة:
net_developer_revenue = (recv_amount - tax_amount) * fx_rate * rev_share

بخلاف ذلك، افترض أن الشراء يشمل الضريبة وأن الحساب يتبع هذه الصيغة:
net_developer_revenue = (recv_amount * fx_rate) * rev_share - (tax_amount * fx_rate)

عمليات شراء Google Play

تتم الإشارة إلى هذه المعاملات مع platform تساوي "G" في تقرير ig_detail.

الحساب يتبع هذه الصيغة:
net_developer_revenue = recv_amount * fx_rate

ملاحظة: هذا مجرد تقدير استنادًا إلى بيانات الإيداعات؛ قد يتم تطبيق رسوم إضافية قبل العوائد. سيجعل التحديث المستقبلي لهذه التقارير الحساب أكثر دقة وسهولة.