واجهة REST

تتيح واجهة REST لأنظمتك قراءة جهات الاتصال والملاحظات والفرص وإنشاءها، وقراءة المسارات وطلبات المتاجر، وإرسال إنفاق الإعلانات اليومي، والاشتراك في الإشعارات الصادرة. تشرح هذه الصفحة القواعد المشتركة بين كل المسارات، أما المسارات نفسها ففي جهات الاتصال والمسارات والفرص وإنفاق الإعلانات والإشعارات الصادرة.

قبل أن تبدأ

تحتاج مفتاح API. ينشئ المالكون والمسؤولون المفاتيح من جهات الاتصال ثم أدوات ثم مفاتيح API، عندما تشمل الباقة واجهة API. راجع مفاتيح API.

العنوان الأساسي

كل المسارات تحت عنوان أساسي واحد:

https://rutbacrm.com/api/v1

كل المسارات في هذا الدليل نسبية إليه، فعبارة GET /contacts تعني GET https://rutbacrm.com/api/v1/contacts.

HTTPS إلزامي. والطلب عبر HTTP العادي يُرفض بالرد 403 HTTPS is required. ولا يُحوَّل، لأن المفتاح يكون قد عبر الشبكة دون حماية. وإن حدث ذلك فألغِ المفتاح وأنشئ غيره.

المصادقة

أرسل المفتاح رمزًا من نوع Bearer في ترويسة Authorization مع كل طلب:

curl https://rutbacrm.com/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

يذكر الرد الشركة التي يخصها المفتاح، فهو اختبار أول مناسب:

{
  "organization": {
    "id": "ORGANIZATION_ID",
    "name": "Your company"
  }
}

المفتاح المفقود والخاطئ والملغى تلقى الرد نفسه، 401 مع {"message": "Invalid API key."}، فلا يكشف الرد هل المفتاح موجود أم لا.

الطلبات والردود

الردود الناجحة تضع النتيجة داخل data، عدا GET /me ومسارات الإشعارات الصادرة التي تعيد حقولها في المستوى الأعلى.

المسارات

المقصود بالدور دور الشخص الذي أنشأ المفتاح. والمشاهدون يقرؤون فقط.

ويوجد أيضًا GET https://rutbacrm.com/api/v1/organizations/ORGANIZATION_ID/context، ويستخدمه التطبيق نفسه مع جلسة متصفح مسجلة الدخول. لا يقبل مفاتيح API، وليس مخصصًا للتكامل.

الصفحات

المسار GET /contacts وحده مقسم إلى صفحات، في كل صفحة 25 جهة:

{
  "data": [],
  "page": 1,
  "pages": 4,
  "total": 87
}

اطلب الصفحة التالية بإضافة ?page=2. أرقام الصفحات من 1 إلى 99999، والصفحة بعد الأخيرة تعيد قائمة data فارغة، فتوقف حين يساوي page قيمة pages. أما القوائم الأخرى فقصيرة وكاملة: حتى 20 مسارًا في كل منها حتى 12 مرحلة، وأحدث 10 طلبات للجهة.

البحث والتصفية

يقبل GET /contacts المعامل q، وهو بحث حتى 120 حرفًا يطابق كلمات في الاسم واسم الشركة والبريد والهاتف. تأتي النتائج بترتيب آخر تحديث، الأحدث أولًا. وتُستبعد من القائمة الجهات المؤرشفة والمدمجة والممحوة. ولا توجد تصفية أخرى: التصفية بالحالة والمسؤول والوسم موجودة في التطبيق لا في الواجهة.

حدود الطلبات

الترويستان X-RateLimit-Limit وX-RateLimit-Remaining في كل رد تصفان حد العنوان المُرسِل، لا حد المفتاح. احتفظ بعدّ خاص بك لتبقى تحت 120 طلبًا في الدقيقة لكل مفتاح، أو وزّع العمل على مفاتيح مستقلة لأنظمة مستقلة. والطلبات المرفوضة في فحص المفتاح أو الباقة أو JSON لا تُحسب على المفتاح.

الأخطاء

الأخطاء بصيغة JSON وفيها message، وأخطاء التحقق تضيف كائن errors مفاتيحه أسماء الحقول. القائمة الكاملة لرموز الحالة وأسبابها في الأخطاء والحدود.

تكرار الطلب

لا توجد ترويسة لمنع التكرار (idempotency)، فخطط لإعادة المحاولة على هذا الأساس:

• POST /contacts يحميك من التكرار: الجهة الثانية بالبريد نفسه أو الهاتف نفسه ترد 409 ما لم تؤكدها.
• POST /contacts/CONTACT_ID/notes وPOST /deals ينشئان سجلًا جديدًا مع كل استدعاء. فإن انتهت مهلة الطلب فتحقق قبل أن تعيد إرساله.
• POST /ad-spend آمن للتكرار: إرسال اليوم نفسه مرة أخرى يستبدل الرقم السابق أو يبقيه، ولا يضيف إليه.
• POST /ad-conversions/confirm آمن للتكرار: البيع المؤكد من قبل لا يُحسب مرة أخرى، ويذكر الرد عدد ما أُكّد للتو.

الإصدارات

الإصدار الحالي والوحيد هو v1، وهو جزء من العنوان الأساسي. لا توجد ترويسة للإصدار.

ما لا تفعله الواجهة

لا تستطيع الواجهة تعديل جهات الاتصال أو الفرص أو حذفها، ولا نقل الفرص بين المراحل، ولا إنشاء المهام، ولا إرسال الرسائل. ولا يوجد OAuth ولا ملف OpenAPI. ولتتفاعل مع ما يحدث في التطبيق استخدم الإشعارات الصادرة بدل السؤال المتكرر.