> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Rekomi
> شغّل برنامجًا للتسويق بالعمولة على متجرك في Dodo Payments باستخدام Rekomi. يربط مفتاح API واحد يتم لصقه بين الخدمتين، بينما يتتبّع Rekomi المبيعات ويدفع مستحقات المسوّقين بالعمولة.
## مقدمة
[Rekomi](https://rekomi.com) هي منصة لتتبّع التسويق بالعمولة وإدارته، مع تكامل أصلي مع Dodo Payments. يشارك أحد الأشخاص رابطًا تابعًا، فيسجّل Rekomi النقرة، وعندما يشتري ذلك الزائر، تصل عملية البيع من Dodo Payments ويُنسَب الفضل تلقائيًا إلى المسوّق بالعمولة المناسب. يحسب Rekomi العمولة ويدفع مستحقات المسوّقين بالعمولة نيابةً عنك أيضًا، في أكثر من 150 دولة، مع تضمين النماذج الضريبية.
يتم الاتصال عبر عملية لصق واحدة: تمنح Rekomi مفتاح API من Dodo Payments مع تفعيل صلاحية الكتابة، ثم يتحقق Rekomi من صلاحيته، وينشئ نقطة نهاية webhook في حسابك على Dodo Payments نفسه، ويجلب سر التوقيع مباشرةً. لا يوجد نموذج webhook لملئه، ولا شيء تحتاج إلى لصقه مرة أخرى في Dodo Payments.
تُنسَب "عملية البيع" إلى مسوّق بالعمولة عندما يُكمل عميل مُحال إليه دفعة لمرة واحدة، أو يبدأ اشتراكًا مدفوعًا، أو يدفع رسوم تجديد. وتؤدي عمليات ردّ الأموال والنزاعات إلى استرداد العمولة تلقائيًا.
## آلية العمل
تستضيف Dodo Payments صفحة الدفع على نطاقها الخاص، لذلك ينتقل إحالة المسوّق بالعمولة إلى عملية البيع باعتبارها metadata لصفحة الدفع:
1. ينقر زائر على رابط تابع ويصل إلى موقعك، حيث يخزّن نص Rekomi البرمجي الإحالة في متصفحه.
2. ينتقل الزائر إلى صفحة الدفع، وتُرفق تلك الإحالة بالدفعة باعتبارها metadata من نوع `rekomi_ref`.
3. تعالج Dodo Payments الدفعة وترسل webhook موقّعًا من نوع `payment.succeeded` إلى نقطة النهاية التي أنشأها Rekomi.
4. يطابق Rekomi الإحالة مع المسوّق بالعمولة، ويحسب العمولة على مبلغ البيع قبل الضريبة، ويسجّلها.
تصل عمليات تجديد الاشتراكات بالطريقة نفسها، لذلك لا تتطلب العمولات المتكررة أي عمل إضافي، كما تمر عمليات ردّ الأموال والنزاعات عبر نقطة النهاية نفسها.
## المتطلبات الأساسية
قبل إعداد هذا التكامل، تأكد من توفر ما يلي لديك:
1. [حساب Dodo Payments](https://app.dodopayments.com) في الوضع المباشر
2. [حساب Rekomi](https://app.rekomi.com/sign-up)
3. مفتاح API من Dodo Payments مع تفعيل **صلاحية الكتابة** (لا يمكن للمفاتيح ذات صلاحية القراءة فقط إنشاء webhooks)
## البدء
في لوحة تحكم Dodo Payments، انتقل إلى **Developer → API Keys** وأنشئ مفتاحًا (سمّه "Rekomi") مع تحديد **Enable write access**. راجع [دليل مفتاح API](/api-reference/introduction#api-key-management-and-authentication) للحصول على تعليمات تفصيلية.
فعّل صلاحية الكتابة على المفتاح: تمر المفاتيح ذات صلاحية القراءة فقط بمرحلة التحقق، لكنها لا تستطيع إنشاء نقطة نهاية webhook، ولذلك سيفشل الاتصال في منتصف العملية.
في Rekomi، افتح **Setup → Connect payment processor**، واختر Dodo Payments، ثم الصق المفتاح. يتحقق Rekomi من صلاحيته مباشرةً، وينشئ نقطة نهاية webhook في حسابك، ويجلب سر التوقيع بنفسه.
بعد الاتصال، يُستخدم المفتاح فقط لإدارة نقطة نهاية webhook وإجراء فحوصات دورية لحالة الخدمة. تصل مبيعاتك عبر webhook الموقّع، وليس عبر API.
أضف نص Rekomi البرمجي للتتبّع إلى موقعك التسويقي حتى يتم تسجيل نقرات المسوّقين بالعمولة. تجد المقتطف البرمجي بعد تعبئته بمعرّف البرنامج ضمن **Setup → Install** في Rekomi.
```html theme={null}
```
أرفق الإحالة المسجّلة بكل دفعة باعتبارها metadata من نوع `rekomi_ref`. راجع أمثلة التنفيذ أدناه.
تُنسَب المبيعات وعمليات التجديد وعمليات ردّ الأموال والنزاعات إلى العمولات أو تُسترد تلقائيًا، ويتولى Rekomi دفع مستحقات المسوّقين بالعمولة.
## دليل التنفيذ
### جلسات الدفع عبر API
اقرأ الإحالة في الواجهة الأمامية باستخدام `window.Rekomi.getReferral()`، وأرسلها إلى الواجهة الخلفية مع طلب الدفع، ثم عيّنها في `metadata`:
```typescript Node.js theme={null}
import DodoPayments from 'dodopayments';
const client = new DodoPayments();
export async function createCheckout(productId: string, rekomiRef?: string) {
const session = await client.checkoutSessions.create({
product_cart: [{ product_id: productId, quantity: 1 }],
customer: {
email: 'customer@example.com',
name: 'John Doe',
},
return_url: 'https://yoursite.com/success',
metadata: {
...(rekomiRef ? { rekomi_ref: rekomiRef } : {}),
},
});
return session.checkout_url;
}
```
يعمل الحقل `metadata.rekomi_ref` نفسه مع منتجات الاشتراك، لذلك تنسب الدفعة الأولية وكل عملية تجديد لاحقة الفضل إلى المسوّق بالعمولة نفسه.
### Payments API
يستخدم المثال أدناه `POST /payments`، وهو **deprecated**. لا يزال يعمل مع التكاملات الحالية، لكن ينبغي أن تستخدم التكاملات الجديدة [Checkout Sessions](/developer-resources/checkout-session) (`POST /checkouts`) — ويتم تمرير `metadata` بالطريقة نفسها.
```typescript Node.js theme={null}
import DodoPayments from 'dodopayments';
const client = new DodoPayments();
export async function createPayment(productId: string, rekomiRef?: string) {
const payment = await client.payments.create({
billing: {
city: 'New York',
country: 'US',
state: 'NY',
street: '123 Main St',
zipcode: '10001',
},
customer: {
email: 'customer@example.com',
name: 'John Doe',
},
product_cart: [{ product_id: productId, quantity: 1 }],
payment_link: true,
metadata: {
...(rekomiRef ? { rekomi_ref: rekomiRef } : {}),
},
});
return payment;
}
```
### روابط الدفع الثابتة
أضف إلى الرابط مَعلمة استعلام metadata المسطّحة (وليس صيغة الأقواس):
```javascript theme={null}
const ref = window.Rekomi?.getReferral?.();
let url = 'https://checkout.dodopayments.com/buy/YOUR_PRODUCT_ID';
if (ref) url += `?metadata_rekomi_ref=${encodeURIComponent(ref)}`;
// use url as the href on your Buy button
```
تضمّن Dodo Payments معلمات استعلام `metadata_*` في metadata الخاصة بالدفعة، حيث يقرأها Rekomi.
## ما يتم تتبّعه
| الحدث | ما يحدث |
| --------------- | --------------------------------------------------------------- |
| دفعة لمرة واحدة | تُحتسب العمولة على مبلغ البيع قبل الضريبة |
| تجديد الاشتراك | عمولة متكررة، تصل كل دفعة باعتبارها حدث دفع مستقلًا |
| ردّ الأموال | تُسترد العمولة تلقائيًا، وبما لا يتجاوز المبلغ الذي سبق احتسابه |
| نزاع | تُسترد العمولة فور فتح النزاع |
تُحسب العمولات على مبلغ البيع قبل الضريبة: Dodo Payments هي Merchant of Record وتحصّل الضريبة، لذلك يكسب المسوّقون بالعمولة من عملية البيع نفسها، وليس من الضريبة التي أضافتها دولة المشتري.
## ملاحظات مهمة
* يسجّل Rekomi نقطة نهاية webhook بالأحداث التي يحتاج إليها بالضبط. تجنّب تعديل قائمة الأحداث لنقطة النهاية تلك في لوحة تحكم Dodo Payments؛ إذ ستُبلغ فحوصات الحالة في Rekomi عن وجود مشكلة في الاتصال إذا أزيلت أي أحداث.
* لا تُرسل التجارب أي دفعة حتى تنتهي فترة التجربة، لذلك لا توجد عمولة حتى يتم تحصيل أول دفعة فعلية.
* يؤدي قطع الاتصال في Rekomi إلى حذف نقطة نهاية webhook من حسابك على Dodo Payments مرة أخرى.
## موارد إضافية
دليل الإعداد الكامل، واستكشاف الأخطاء وإصلاحها، وتفاصيل الأمان في مستندات Rekomi.
جميع خيارات تكامل التسويق بالعمولة مع Dodo Payments.
هل تحتاج إلى المساعدة؟ تواصل مع دعم Rekomi عبر [support@rekomi.com](mailto:support@rekomi.com)، أو مع دعم Dodo Payments عبر [support@dodopayments.com](mailto:support@dodopayments.com) للحصول على المساعدة بشأن التكامل.