واجهة جهات الاتصال — مركز المساعدة

تقرأ هذه المسارات الأشخاص والشركات في مساحة عملك وتنشئهم. وهي تتبع قواعد الشاشات نفسها: يُكتشف التكرار، وتسري حدود الباقة، والجهات الممحوة أو المدمجة لا تظهر. القواعد المشتركة للمفاتيح وJSON والحدود في واجهة REST.

كائن جهة الاتصال

كل مسارات جهات الاتصال تعيد الجهات بهذه الحقول:

الحقل	النوع	المعنى
`id`	نص	معرف الجهة (UUID)
`name`	نص	الاسم الكامل للشخص، أو اسم الشركة
`company_name`	نص أو null	الشركة التي يعمل فيها الشخص
`job_title`	نص أو null	المسمى الوظيفي
`email`	نص أو null	البريد الإلكتروني بأحرف صغيرة
`phone`	نص أو null	الهاتف بصيغة واحدة قابلة للمقارنة، مثل `+966500000000`
`status`	نص	`lead` أو `prospect` أو `customer` أو `inactive`
`source`	نص	`manual` أو `website` أو `referral` أو `phone` أو `messaging` أو `social` أو `event` أو `other`
`country`	نص أو null	رمز الدولة من حرفين، مثل `SA`
`preferred_locale`	نص أو null	`en` أو `ar` أو `tr` أو `fr`
`marketing_opt_out`	منطقي	`true` إن كانت الجهة لا تقبل الرسائل التسويقية
`archived`	منطقي	`true` إن كانت الجهة مؤرشفة

المسؤول عن الجهة ورقم المراجعة والسجل الداخلي ليست جزءًا من الواجهة.

عرض جهات الاتصال والبحث فيها

GET /contacts?q=SEARCH&page=1

المعامل	القواعد
`q`	اختياري. حتى 120 حرفًا. يطابق كلمات في الاسم واسم الشركة والبريد والهاتف
`page`	اختياري. عدد صحيح من 1 إلى 99999، والافتراضي 1

curl "https://rutbacrm.com/api/v1/contacts?q=maryam" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

{
  "data": [
    {
      "id": "CONTACT_ID",
      "archived": false,
      "marketing_opt_out": false,
      "name": "Maryam Saleh",
      "company_name": null,
      "job_title": null,
      "email": "maryam@example.com",
      "phone": "+966500000001",
      "preferred_locale": "ar",
      "country": "SA",
      "source": "website",
      "status": "lead"
    }
  ],
  "page": 1,
  "pages": 1,
  "total": 1
}

تأتي النتائج 25 في الصفحة، الأحدث تحديثًا أولًا. وتُستبعد الجهات المؤرشفة، والجهات التي دُمجت في غيرها أو مُحيت. والمعامل q الأطول من 120 حرفًا أو page غير الصالح يرد 422.

قراءة جهة واحدة

GET /contacts/CONTACT_ID

تعود الجهة مع حقلين إضافيين:

الحقل	المعنى
`tags`	أسماء وسوم الجهة بالترتيب الأبجدي، حتى 20 وسمًا
`custom_fields`	كائن بمفاتيح الحقول المخصصة وقيمها، عندما تشمل باقتك الحقول المخصصة. القيم نصوص، أو `null` إن كانت فارغة، ومربع الاختيار المؤشَّر قيمته `"1"`. ومن دون الميزة، أو إن لم توجد حقول، تكون قائمة فارغة `[]`

{
  "data": {
    "id": "CONTACT_ID",
    "archived": false,
    "marketing_opt_out": false,
    "name": "Maryam Saleh",
    "company_name": null,
    "job_title": null,
    "email": "maryam@example.com",
    "phone": "+966500000001",
    "preferred_locale": "ar",
    "country": "SA",
    "source": "website",
    "status": "lead",
    "tags": ["VIP"],
    "custom_fields": {
      "city": "Riyadh"
    }
  }
}

يُشتق مفتاح الحقل المخصص من عنوانه لحظة إنشائه، فالحقل المعنون «City» مفتاحه city. والجهة المؤرشفة تعود كما هي مع "archived": true. أما الجهة الممحوة أو المدمجة في غيرها فترد 404، وكذلك أي معرف من شركة أخرى.

إنشاء جهة

POST /contacts

يحتاج مفتاحًا بصلاحية قراءة وكتابة ومنشئه عضو أو مسؤول أو مالك.

الحقل	مطلوب	القواعد
`name`	نعم	حتى 160 حرفًا
`email`	لا	عنوان صالح حتى 254 حرفًا، ويُحفظ بأحرف صغيرة
`phone`	لا	من 6 إلى 15 رقمًا مع `+` اختيارية في البداية. تُزال المسافات والشرطات والأقواس، وتُقبل الأرقام العربية، وتصبح `00` في البداية `+`
`company_name`	لا	حتى 160 حرفًا
`job_title`	لا	حتى 120 حرفًا
`status`	لا	`lead` أو `prospect` أو `customer` أو `inactive`، والافتراضي `lead`
`source`	لا	أحد المصادر في الجدول أعلاه، والافتراضي `manual`
`country`	لا	حرفان، ويُحفظ بأحرف كبيرة
`preferred_locale`	لا	`en` أو `ar` أو `tr` أو `fr`
`confirm_duplicate`	لا	`true` لإنشاء الجهة حتى لو احتمل أنها مكررة

تُتجاهل الحقول الأخرى. والجهات المنشأة عبر الواجهة أشخاص دائمًا، ودون مسؤول. ولا يمكن ضبط الوسوم ولا الحقول المخصصة عبر الواجهة.

curl -X POST https://rutbacrm.com/api/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name": "Maryam Saleh", "email": "maryam@example.com", "phone": "+966 50 000 0001", "source": "website"}'

الجهة الجديدة ترد 201:

{
  "data": {
    "id": "CONTACT_ID"
  }
}

جهة مكررة محتملة

إن كانت لجهة أخرى البريد نفسه أو الهاتف نفسه فلا يُنشأ شيء، ويكون الرد 409 مع معرفات ما يصل إلى خمس جهات مطابقة:

{
  "message": "Possible duplicate.",
  "matches": ["EXISTING_CONTACT_ID"]
}

استخدم الجهة الموجودة، أو أرسل الطلب نفسه مع "confirm_duplicate": true إن كان شخصًا آخر فعلًا.

أخطاء التحقق

الحقول غير الصالحة ترد 422 مع كائن errors:

{
  "message": "The Name field is required. (and 1 more error)",
  "errors": {
    "name": ["The Name field is required."],
    "email": ["The Email field must be a valid email address."]
  }
}

وإن كان في باقتك حد لعدد جهات الاتصال وبلغته، فالرد 422 والخطأ تحت limit.

قراءة طلبات الجهة

GET /contacts/CONTACT_ID/orders

يعيد الطلبات التي أرسلتها المتاجر المربوطة لهذه الجهة. ولا تدخل فيها طلبات عروض الأسعار.

{
  "data": {
    "orders": [
      {
        "number": "1001",
        "status": "completed",
        "total": "1,250.50 SAR",
        "campaign": "ramadan-sale",
        "placed_at": "2026-11-06T10:00:00.000000Z"
      }
    ],
    "count": 3,
    "totals": {
      "SAR": "3,480.00 SAR"
    }
  }
}

الحقل	المعنى
`orders`	أحدث 10 طلبات، الأحدث أولًا
`orders[].number`	رقم الطلب في المتجر، أو معرف الطلب في المتجر إن لم يرسل رقمًا
`orders[].status`	الحالة التي أرسلها المتجر، بأحرف صغيرة
`orders[].total`	المجموع منسقًا مع عملته، للعرض
`orders[].campaign`	اسم الحملة، أو مصدرها، أو `null`
`count`	عدد طلبات الجهة التي تُحسب مبيعات: `paid` أو `processing` أو `completed` أو `delivered`
`totals`	مجموع تلك المبيعات لكل عملة، منسقًا

إضافة ملاحظة

POST /contacts/CONTACT_ID/notes

يحتاج مفتاحًا بصلاحية قراءة وكتابة ومنشئه عضو أو مسؤول أو مالك.

الحقل	مطلوب	القواعد
`body`	نعم	نص حتى 5000 حرف، وتُزال المسافات من طرفيه

curl -X POST https://rutbacrm.com/api/v1/contacts/CONTACT_ID/notes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"body": "Asked about delivery to Jeddah."}'

{
  "data": {
    "saved": true
  }
}

تظهر الملاحظة في صفحة الجهة وفي نشاطها باسم منشئ المفتاح. والجهة الممحوة أو المدمجة ترد 404 ولا تقبل الملاحظة.

معلومات مفيدة

الجهات المنشأة عبر الواجهة لا تُعد عملاء محتملين جددًا في الأتمتة والمتابعات ولا في الحدث وصول عميل محتمل جديد. هذا الحدث يأتي من نماذج المواقع والمتاجر وقنوات المراسلة.
لا تكتب الواجهة فوق بيانات جهة أبدًا. ولتعديل جهة استخدم التطبيق.
لا تُمنع الملاحظات المكررة، فإرسال الملاحظة نفسها مرتين يضيفها مرتين.
دمج الجهات في التطبيق يجعل الجهة المدمجة ترد 404. ابحث عن الشخص مجددًا بـGET /contacts?q= لتجد الجهة التي بقيت.