ربط Paddle

Paddle هو التاجر المسجّل (merchant of record) للبرمجيات التي تبيعها خارج متاجر التطبيقات: تطبيقات سطح المكتب وتطبيقات الويب وخطط SaaS والتراخيص. يتم الربط بمفتاح API واحد للقراءة فقط بدلًا من OAuth. تُنشئ المفتاح في لوحة تحكم Paddle، وتلصقه في Revenue Sensor، ثم تختار منتجات Paddle التي تريد مزامنتها. يُخزَّن المفتاح مشفّرًا ولا يغادر خادمنا أبدًا؛ ولا يُستخدم حساب دخولك إلى Paddle مطلقًا.

قبل أن تبدأ

• صلاحية الوصول إلى لوحة تحكم Paddle لحساب البائع الذي تريد تتبع مبيعاته، مع إذن إنشاء مفاتيح API ضمن Developer tools.
• أن تعرف ما إذا كنت تريد الحساب الفعلي (live) أم بيئة الاختبار (sandbox). يُصدر Paddle مفاتيح منفصلة لكل منهما، والمفتاح هو ما يحدد أيهما نقرأ؛ ولا يوجد شيء آخر لاختياره.

إنشاء مفتاح API للقراءة فقط

1. 1

   افتح Developer tools

   في لوحة تحكم Paddle، انتقل إلى Developer tools → Authentication وأنشئ مفتاح API جديدًا. أعطه اسمًا ستتعرف عليه لاحقًا، مثل "Revenue Sensor".

2. 2

   امنح صلاحيات القراءة فقط

   فعّل صلاحية القراءة لكل من Transactions وAdjustments وProducts وAddresses. يظهر Addresses ضمن Customers وهو ما يعطينا دولة المشتري، فأبقِه مفعّلًا حتى لو بدا غير ذي صلة. لا حاجة لأي صلاحيات كتابة.

3. 3

   انسخ المفتاح مرة واحدة

   يعرض Paddle المفتاح مرة واحدة فقط عند إنشائه. انسخه فورًا؛ وإذا فقدته فألغِه وأنشئ مفتاحًا آخر.

اربط الحساب

1. 1

   الصق المفتاح

   انتقل إلى Integrations → Paddle → Connect في وحدة تحكم Revenue Sensor والصق مفتاح API. يقرأ Revenue Sensor بادئة المفتاح ليميّز بين مفتاح live ومفتاح sandbox، ويؤكد أيهما سيستخدم قبل أن تتابع.

2. 2

   اختر منتجاتك

   الوحدات التي تزامنها هي منتجات Paddle وليست تطبيقات المتاجر. اختر المنتجات التي تريدها في السجل؛ يظهر كل منها كسطر مستقل في الإيرادات ويمكن ربطه بتطبيق إن كان تابعًا له. لا يُجلب إلا ما تختاره، ولا يُحتسب على خطتك إلا ما تختاره.

3. 3

   دع المزامنة الأولى تكتمل

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

ما يُستورد

التحديثات الفورية (اختياري)

يزامن Revenue Sensor بيانات Paddle كل 30 دقيقة. إذا كنت تفضّل رؤية عملية بيع أو استرداد جديدة خلال دقيقة أو دقيقتين، فوجّه وجهة إشعارات في Paddle إلينا. تظل الأرقام قادمة من واجهة Paddle البرمجية؛ ولا يفعل الـ webhook سوى إخبارنا بالمزامنة مبكرًا.

1. 1

   انسخ عنوان URL الخاص بالـ webhook

   افتح اتصال Paddle في وحدة تحكم Revenue Sensor. تعرض لوحة "Real-time updates" عنوان URL خاصًا بهذا الاتصال وحده؛ انسخه.

2. 2

   أنشئ وجهة إشعارات

   في Paddle انتقل إلى Developer tools → Notifications → New destination. الصق عنوان URL، واختر Webhook كنوع، واشترك في أحداث transaction وadjustment وsubscription.

3. 3

   احفظ المفتاح السري

   يعرض Paddle مفتاح توقيع سريًا عند إنشاء الوجهة. الصقه في لوحة "Real-time updates" واحفظه. نستخدمه للتحقق من كل عملية تسليم ورفض أي شيء غير موقّع؛ ويُخزَّن مشفّرًا ولا يُعرض مرة أخرى.

استكشاف الأخطاء

• المفتاح مرفوض: تأكد من أن لديه صلاحية قراءة على العناصر الأربعة كلها: Transactions وAdjustments وProducts وAddresses. المفتاح الذي يفتقر إلى Addresses يجتاز الفحص الأساسي لكنه يفشل في المزامنة.
• لا تظهر أي منتجات: المفتاح يعود لحساب مختلف، أو لبيئة sandbox بينما كنت تتوقع live (أو العكس). بادئة المفتاح تخبرك أيهما.
• هناك عملية بيع مفقودة: لا تُستورد إلا المعاملات المدفوعة والمكتملة. المسودات والفواتير غير المدفوعة والمعاملات الملغاة ليست إيرادات بعد.
• الإيرادات تبدو أعلى من المبلغ المحوَّل إليك: هذا متوقع. تُحفظ الضريبة منفصلة ولا تُخصم رسوم Paddle، لذا فالرقم هو إجمالي الإيرادات قبل حصة Paddle.
• يظهر الاسترداد في يوم مختلف عن يوم البيع: تُسجَّل الاستردادات في يوم اعتمادها ولا يُعاد تأريخها إلى عملية الشراء الأصلية.