Segments API

أنشئ شرائح المستخدمين الديناميكية وأدرها برمجياً.

كل النقاط هنا نسبية إلى عنوان الأساس https://api-eu1.joryio.com. راجع نظرة عامة على API.

المصادقة

تتطلب كل الطلبات مصادقة مفتاح API:

Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

إنشاء شريحة

أنشئ شريحة مستخدمين جديدة بفلاتر.

POST /segments

الحقل	النوع	مطلوب	الوصف
name	string	نعم	اسم الشريحة، حتى 255 حرفاً.
description	string	لا	وصف الشريحة، حتى 1000 حرف.
filterGroups	array	نعم	مصفوفة مجموعات فلاتر، حتى 20.
excludeFilterGroups	array	لا	يُزال المستخدمون المطابقون لأي مجموعة منها، حتى 20.
groupOperator	string	نعم	دمج المجموعات بـ AND أو OR.
tags	array	لا	أسماء وسوم لتنظيم الشرائح.

بنية الفلتر

تضم كل مجموعة فلاتر حتى 50 فلتر:

{
  filters: [
    {
      type: 'attribute' | 'default_attribute' | 'event' | 'ecommerce'
          | 'behavioral' | 'segment' | 'canvas_execution'
          | 'list_membership' | 'channel_subscription' | 'app'
          | 'entity' | 'bounce_status' | 'wallet_pass',
      field?: string,
      operator: string,
      value?: any,
      eventName?: string,
      withinDays?: number,
      startDate?: string,
      endDate?: string,
      segmentId?: string,
      listId?: string,
      channel?: string
    }
  ],
  operator: 'AND' | 'OR'
}

• استخدم field لفلاتر السمات، وeventName لفلاتر الأحداث.
• withinDays نافذة زمنية نسبية للأحداث، بينما startDate وendDate نافذة مطلقة بتنسيق ISO 8601.
• تستخدم فلاتر الشرائح segmentId، وفلاتر عضوية القائمة listId، وفلاتر اشتراك القناة channel.

أمثلة للطلبات

فلتر سمة بسيط:

{
  "name": "Premium Users",
  "description": "Users on premium plan",
  "filterGroups": [{
    "filters": [{ "type": "attribute", "field": "plan", "operator": "equals", "value": "premium" }],
    "operator": "AND"
  }],
  "groupOperator": "AND"
}

شريحة سلوكية: تجمع مستخدمي trial الذين نفذوا Session Started خلال آخر 7 أيام مع شرط AND.

شريحة معقدة: اجمع شرط الخطة المدفوعة وقيمة عمر العميل المرتفعة مع شرط عدم تنفيذ Login خلال 14 يوماً، باستخدام مجموعتي فلاتر وعامل AND.

الاستجابة

يعاد كائن الشريحة مباشرة، من دون غلاف. معرّفات الشرائح UUID ولا يخزن عدد الأعضاء داخل الشريحة؛ استخدم GET /segments/:id/size.

{
  "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "name": "Premium Users",
  "description": "Users on premium plan",
  "filterGroups": [{ "filters": [{ "type": "attribute", "field": "plan", "operator": "equals", "value": "premium" }], "operator": "AND" }],
  "excludeFilterGroups": [],
  "groupOperator": "AND",
  "tags": [],
  "status": "active",
  "createdAt": "2024-01-20T10:30:00.000Z",
  "updatedAt": "2024-01-20T10:30:00.000Z"
}

الحصول على شريحة

GET /segments/:id

id هو معرّف الشريحة. يعيد كائن الشريحة مباشرة؛ للحصول على عدد الأعضاء الحالي استخدم GET /segments/:id/size.

عرض الشرائح

GET /segments

المعامل	النوع	الافتراضي	الوصف
limit	number	100	نتائج الصفحة، بحد أقصى 100.
offset	number	0	عدد الشرائح المتجاوزة.
q	string	-	بحث نصي حر في اسم الشريحة.
status	string	-	active أو archived.
tags	string	-	أسماء وسوم مفصولة بفاصلة.
createdBy	string	-	معرّفات منشئين مفصولة بفاصلة.
editedBy	string	-	معرّفات آخر محررين مفصولة بفاصلة.

يعيد الطلب كائن data للشرائح وpagination يتضمن total وpage وlimit وoffset وtotalPages وhasMore.

تحديث شريحة

PUT /segments/:id

يستخدم التحديث PUT ولا توجد نقطة PATCH. الحقول المحذوفة تبقى بلا تغيير. يمكنك تحديث الاسم أو الوصف أو مجموعات الفلاتر أو غيرها من حقول الشريحة.

{
  "name": "Updated Name",
  "description": "Updated description",
  "filterGroups": [...]
}

يعيد كائن الشريحة المحدّث مباشرة.

أرشفة شريحة

لا يمكن حذف الشرائح نهائياً، لأن الحملات والرحلات تحتفظ بمراجع لها. الأرشفة فقط ممكنة: تتوقف الشريحة المؤرشفة عن الظهور في القوائم النشطة ويمكن استعادتها في أي وقت.

POST /segments/:id/archive
POST /segments/:id/unarchive

• لا تحذف الأرشفة المستخدمين في الشريحة.
• تتأثر الحملات النشطة التي تستخدم الشريحة.
• استخدم POST /segments/:id/unarchive للاستعادة.

الحصول على مستخدمي شريحة

GET /segments/:id/users

المعامل	النوع	الافتراضي	الوصف
limit	number	100	عدد المستخدمين المعاد.
offset	number	0	عدد المستخدمين المتجاوز.

تعيد النقطة مصفوفة JSON مجردة من مستندات المستخدمين، بلا غلاف ترقيم؛ استخدم limit وoffset للصفحات. تتضمن الوثائق _id وexternalId وemail وattributes.

الحصول على حجم الشريحة

GET /segments/:id/size

الحجم افتراضياً تقدير سريع. مرر ?exact=true للحصول على عدد دقيق، وهو أبطأ لمساحات العمل الكبيرة. العدد هو الشيء الوحيد التقريبي؛ تبقى العضوية الفعلية والإرسالات دقيقة دائماً.

{
  "segmentId": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "size": 1234,
  "approximate": true
}

عوامل تشغيل الفلاتر

عوامل السمات

العامل	الوصف	المثال
equals	مطابقة تامة	plan equals "premium"
not_equals	لا يساوي	plan not_equals "free"
in	قيمة في قائمة	plan in ["premium", "enterprise"]
not_in	قيمة ليست في قائمة	plan not_in ["free", "trial"]
contains	النص يحتوي	email contains "@company.com"
not_contains	النص لا يحتوي	email not_contains "@competitor.com"
gt / gte	أكبر من أو أكبر أو يساوي	lifetimeValue > 1000 وage >= 18
lt / lte	أصغر من أو أصغر أو يساوي	loginCount < 5 وmrr <= 99
exists / not_exists	الحقل موجود أو غير موجود	phone exists
within_next_days	تاريخ ضمن N أيام تالية	trialEndsDate within_next_days 7

عوامل الأحداث

العامل	الوصف	المثال
performed	نفذ المستخدم الحدث	Performed "Order Completed"
not_performed	لم ينفذ المستخدم الحدث	Not performed "Onboarding Completed"
performed_count_gte	عدد الحدث أكبر أو يساوي N في value	Performed "Login" >= 10 times
performed_count_lte	عدد الحدث أصغر أو يساوي N في value	Performed "Login" <= 5 times
performed_in_last_days	نُفذ خلال N أيام الماضية في value	Performed "Login" in last 7 days
not_performed_in_last_days	لم يُنفذ خلال N أيام الماضية في value	No "Login" in last 14 days

أمثلة للفلاتر

// String matching
{ "type": "attribute", "field": "email", "operator": "contains", "value": "@company.com" }

// Numeric comparison
{ "type": "attribute", "field": "lifetimeValue", "operator": "gte", "value": 500 }

// Multiple values
{ "type": "attribute", "field": "plan", "operator": "in", "value": ["premium", "enterprise"] }

// Event in timeframe
{ "type": "event", "eventName": "Order Completed", "operator": "performed", "withinDays": 30 }

// Event count
{ "type": "event", "eventName": "Login", "operator": "performed_count_gte", "value": 10, "withinDays": 30 }

// User in another segment
{ "type": "segment", "segmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "operator": "in_segment" }

أمثلة شرائح شائعة

• فرصة تحويل تجربة: مستخدمو trial الذين تنتهي تجربتهم خلال 3 أيام ولم ينفذوا Order Completed.
• مستخدمون متقدمون: نفذوا Login 20 مرة أو أكثر وFeature Used 50 مرة أو أكثر خلال 30 يوماً.
• عملاء مدفوعون معرضون للخطر: خطط premium أو enterprise وقيمة عمر 500 فأكثر ولم ينفذوا Login في آخر 14 يوماً.

التحديثات الديناميكية

الشرائح ديناميكية: لا تُخزن العضوية كقائمة، بل تُقيّم فلاتر الشريحة مقابل بيانات الملف والأحداث الحالية كلما استخدمت الشريحة، كاستهداف حملة أو بوابة رحلة أو فحص عضوية. لا يوجد ما يحتاج إلى تحديث أو إعادة حساب عبر API.

# Get current size (approximate by default; add ?exact=true for a precise count)
curl -X GET https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/size \
  -H "Authorization: Bearer jry_live_your_api_key"

استجابات الأخطاء

تستخدم كل الأخطاء نص الخطأ القياسي. راجع نظرة API العامة: استجابة الخطأ.

{
  "statusCode": 400,
  "message": "Bad Request Exception",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/segments",
  "errors": ["filterGroups.0.filters.0.operator must be one of the following values: equals, not_equals, contains, ..."]
}

تُعاد 404 عندما لا توجد شريحة بالمعرّف في المسار.

حدود المعدل

لا توجد حالياً حدود معدل ثابتة لكل نقطة نهاية في Segments API. راجع نظرة API العامة: حدود المعدل.

أفضل الممارسات

1. حافظ على تركيز الشرائح: أنشئ شرائح محددة مستهدفة، لا «كل المستخدمين» بلا فلاتر.
2. استخدم أسماء وصفية: مثل «مستخدمو trial - تنتهي هذا الأسبوع» و«عملاء مرتفعو القيمة معرضون للخطر».
3. ادمج الفلاتر منطقياً: يستخدم AND للتضييق وOR للتوسيع.
4. راقب حجم الشريحة: استعلم دورياً عن /segments/${segmentId}/size واعرض ≈ عندما تكون approximate صحيحة.

الخطوات التالية

• دليل إنشاء الشرائح
• استخدام الشرائح في الحملات
• توثيق سمات المستخدم
• دليل تتبع الأحداث