# الوكالات والفرق وواجهة API

كيف تُعلن الوكالات لعملائها على Agilis باسم كل عميل، وكيف تعمل أدوار الفريق والأرصدة والفواتير، وكيفية استخدام Agilis REST API.

**باختصار:** تسجّل الوكالة مرة واحدة باسمها القانوني، وتُعلن لعملائها بإدخال اسم كل عميل في **الاسم الظاهر للأعضاء**. تدفع الوكالة وتحتفظ بالأرصدة وتتلقى الفواتير. ويمكن للمطوّرين إنشاء العروض والفعاليات وإدارتها عبر **Agilis REST API** (https://ads.agilis.dating) باستخدام مفاتيح API من بوابة الإعلانات؛ مفاتيح الاختبار مجانية، وما يُنشأ بها لا يُعرض أبدًا للأعضاء.

## للوكالات

1. **سجّلوا الوكالة** باسمها القانوني. → [طريقة التسجيل](https://www.agilis.dating/ar/business/guide/register)
2. عند إنشاء عرض أو فعالية، أدخلوا **اسم عميلكم** في **الاسم الظاهر للأعضاء**. يرى الأعضاء اسم العميل لا اسمكم.
3. يجب أن تكونوا مفوَّضين من كل عميل للإعلان نيابةً عنه. وتُحمِّل شروط الإعلان الوكالةَ مسؤولية ذلك.

**من يدفع، ومن تصدر الفاتورة باسمه**

- يتم الدفع من حساب وكالتكم، بعملة الفوترة الخاصة بها.
- لكل شخص في وكالتكم رصيده الخاص ويدفع منه. ورصيد المؤسسة هو المجموع. → [كيف تعمل الأرصدة](https://www.agilis.dating/ar/business/guide/pricing)
- تصدر الفواتير والنتائج باسم وكالتكم، فاتورة واحدة لكل دفعة، لتتمكنوا من إعادة فوترة كل عميل.
- لفصل إنفاق كل عميل، خصّصوا عرضًا أو فعالية لكل عميل وأعيدوا الفوترة من فاتورته.

## أدوار الفريق

يعمل مسؤولو المؤسسة والمُعلِنون في بوابة الإعلانات، بينما يعمل المطوّرون عبر واجهة API. لا يمكن للمطوّرين إنشاء عروض أو فعاليات في بوابة الإعلانات، لكن يمكنهم بمفاتيح API الخاصة بهم إنشاؤها ونشرها والدفع مقابلها عبر واجهة API، ونشاطكم التجاري مسؤول عن طريقة استخدام مفاتيحه. الجدول الكامل في [أدوار الفريق والصلاحيات](https://www.agilis.dating/ar/business/guide/getting-started).

## واجهة Agilis REST API

- **العنوان الأساسي:** https://ads.agilis.dating
- **المرجع:** www.agilis.dating/api-doc، مع أمثلة بلغات cURL وPython وNode.js وPHP، ومساعد لواجهة API
- **بصيغة قابلة للقراءة آليًا:** OpenAPI 3.1 على www.agilis.dating/openapi.json، وMarkdown على www.agilis.dating/api-doc.md، والنص الكامل لأدوات الذكاء الاصطناعي على www.agilis.dating/llms-full.txt
- **العروض:** عرض قائمة بفئاتكم والاهتمامات؛ تقدير سعر العرض قبل إنشائه؛ إنشاء العروض وعرض قائمتها وإيقافها مؤقتًا واستئنافها وحذفها؛ الاطلاع على نتائج كل عرض
- **الفعاليات:** معاينة الفعاليات ونشرها وعرض قائمتها وتعديلها وتغيير موعدها وإلغاؤها وحذفها؛ الاطلاع على نتائج كل فعالية

### الحصول على مفتاح API

1. سجّلوا الدخول إلى بوابة الإعلانات بصفة مسؤول المؤسسة أو مطوِّر.
2. اختاروا **الوضع التجريبي** أو الوضع الفعلي باستخدام زر التبديل أعلى الصفحة.
3. انتقلوا إلى **مفاتيح API** → **إنشاء مفتاح جديد**، وامنحوه اسمًا، وتاريخ انتهاء إن شئتم.
4. **انسخوا المفتاح فورًا.** لن تتمكنوا من رؤيته مجددًا.

تبدأ مفاتيح الاختبار بالبادئة `pk_test_`، وتبدأ المفاتيح الفعلية بالبادئة `pk_live_`. يمكن لكل شخص امتلاك ما يصل إلى 10 مفاتيح في كل وضع. يستبدل **استبدال** المفتاحَ فورًا، لذا حدّثوا أنظمتكم أولًا. أرسلوا المفتاح في ترويسة الطلب `x-api-key`: `x-api-key: pk_test_…`.

### طوّروا بأمان

- طوّروا واختبروا باستخدام مفتاح `pk_test_`: العروض والفعاليات التجريبية مجانية ولا تُعرض أبدًا للأعضاء.
- قدّروا سعر العرض باستخدام نقطة نهاية تقدير السعر (price-estimate) قبل إنشائه.
- أبقوا المفاتيح خارج مستودعات الشيفرة والمتصفحات؛ واستدعوا واجهة API من خادمكم.

## أسئلة

### هل يمكن لوكالة إدارة عدة عملاء من حساب واحد؟

نعم. سجّلوا الوكالة مرة واحدة وحدّدوا اسم العميل في كل عرض أو فعالية.

### هل يمكن أن تكون لكل عميل فاتورته الخاصة؟

تصدر الفواتير باسم وكالتكم، فاتورة واحدة لكل دفعة. أعيدوا فوترة عملائكم بناءً عليها.

### هل توجد بيئة اختبار معزولة؟

نعم. الوضع التجريبي، مع مفاتيح `pk_test_`، بيئة اختبار معزولة كاملة. لا يُحصَّل أي مبلغ ولا يُعرض أي شيء للأعضاء.

### هل يمكنني ربط أدوات البرمجة بالذكاء الاصطناعي؟

نعم. وجّهوا أداتكم إلى www.agilis.dating/api-doc.md أو www.agilis.dating/openapi.json.

Source: https://www.agilis.dating/ar/business/guide/agencies-and-api