Segments API

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

كل النقاط هنا نسبية إلى عنوان الأساس https://api-eu1.joryio.com/api. راجع نظرة عامة على 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`.
`includeCrawlers`	boolean	لا	احتساب ملفات الزواحف (البوتات) كأعضاء. الافتراضي `false` - صفحة الجمهور تخفيها أيضًا.
`tags`	array	لا	أسماء وسوم لتنظيم الشرائح.

بنية الفلتر

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

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

يقارن فلتر random_bucket رقم الدلو العشوائي الثابت لجهة الاتصال (0-9999، لا يتغير أبدًا للشخص نفسه): قيمة operator واحدة من equals, not_equals, less_than, less_than_or_equal, greater_than, greater_than_or_equal, between؛ وvalue عدد صحيح من 0 إلى 9999، أو [from, to] مع between (يشمل الطرفين). تُرفض أي قيمة أخرى برمز 400. راجع رقم الدلو العشوائي.

يطابق فلتر contact_import ("جاء من استيراد") جهات الاتصال حسب عمليات استيراد جهات الاتصال التي أنشأتها أو حدّثتها: operator هو any_of أو none_of، وvalue قائمة من 1 إلى 100 معرّف استيراد من GET /users/import/sources. يشمل none_of جهات الاتصال التي لم تلمسها أي عملية استيراد. تُرفض القائمة الفارغة بالرمز 400. جهات الاتصال المستوردة قبل إطلاق هذه الميزة غير موسومة، لذلك تطابق none_of فقط. راجع جاء من استيراد.

يطابق فلتر message_activity ("نشاط الرسائل") الأشخاص حسب ما حدث للرسائل المرسلة إليهم. operator هو الإجراء: received (الحدث message.sent) أو delivered أو opened أو clicked أو bounced أو unsubscribed أو failed. messageSource هو campaign (مع campaignId) أو campaign_tag (مع tagIds) أو any_campaign أو journey (مع canvasId) أو journey_step (مع canvasId وnodeId) أو journey_tag (مع tagIds) أو any. messageChannel هو any أو أحد email وsms وpush وwhatsapp وin_app وwebhook وviber - فقط قناة تُبلغ عن الإجراء (لا opened لـ sms أو push أو webhook؛ وbounced لـ email فقط). messageWindow هو ever أو in_last_days أو not_in_last_days (value = أيام، من 1 إلى 3650) أو between_dates (startDate وendDate) أو at_least (value = مرات، 1 على الأقل) أو at_most (value = مرات، 0 أو أكثر). tagIds قائمة بمعرّفات الوسوم (من GET /tags)، وتعني عدة معرّفات أيًّا من تلك الوسوم؛ ويطابق الحملات أو الرحلات التي تحمل الوسم عند حساب الجمهور، ولا تغيّره إعادة تسمية الوسم. الفلتر المحفوظ باسم وسم في tag لا يزال يعمل ويُحفظ بالمعرّف عند الحفظ التالي؛ ويُرفض الاسم الذي لا يحمله أي وسم بالرمز 400. يُرفض أي شيء آخر بالرمز 400. مثال: { "type": "message_activity", "operator": "opened", "messageSource": "any_campaign", "messageChannel": "email", "messageWindow": "in_last_days", "value": 30 }. راجع نشاط الرسائل.

يتبع opened على email أو any قاعدة الفتح: فهو يطابق أيضًا نقرة الشخص في البريد، لأن النقرة تثبت أن البريد فُتح، ومع at_least / at_most يقارن الأكبر بين عدد الفتحات وعدد النقرات في البريد. لا تُحتسب أبدًا فتحات الروبوتات ونقرات فاحصات الروابط.

يقبل فلتر canvas_execution أيضًا nodeId مع canvasId واحد - وصل تشغيل الشخص إلى تلك الخطوة من الرحلة (أي نوع عقدة) - والمعاملين in_tagged_canvas / not_in_tagged_canvas مع tagIds بدلًا من canvasId: في (أو ليس في) أي رحلة تحمل الوسم. مع nodeId، يحصر stepWindow الشرط في آخر وقت دخل فيه التشغيل الخطوة: ever (الافتراضي) أو in_last_days (withinDays، من 1 إلى 3650) أو between_dates (startDate وendDate). المعامل الخاص برحلة واحدة (in_canvas وnot_in_canvas وcompleted_canvas وexited_canvas) المحفوظ دون canvasId لا يطابق أحدًا. راجع تنفيذ Canvas.

استخدم 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`

جهات الاتصال التي ليس لها قيمة

جهة الاتصال التي ليس لها قيمة في الحقل تطابق المعاملات السلبية (not_equals وnot_contains وnot_in وnot_exists) ولا تطابق أيًّا من الإيجابية (equals وcontains وin وexists وgt وgte وlt وlte). راجع جهات الاتصال التي ليس لها قيمة.

تُطابَق المعرّفات بتساهل

يُقارَن email دون تمييز بين الأحرف الكبيرة والصغيرة عبر equals و not_equals و in و not_in - فـ [email protected] و [email protected] هما العنوان نفسه. ويُقارَن phone بأرقامه عبر المشغّلات الأربعة نفسها، لذا يطابق كل من +972501234567 و 972501234567 و +972 50-123-4567 جهة الاتصال نفسها. أما بقية الحقول فتُطابَق تماماً كما تكتبها، بما فيها externalId - فمعرّفاتك تبقى حساسة لحالة الأحرف.

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

العامل	الوصف	المثال
`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/api/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 العامة: حدود المعدل.

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

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

إبقاء الشريحة جاهزة للتقارير

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

تجسيد الشريحة (materialization) يخزّن أعضاءها داخل قاعدة بيانات التحليلات، فيقوم التقرير بعملية JOIN ولا تنتقل أي قائمة. يختفي القيد عند أي حجم.

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

المقابل هو حداثة البيانات. تُعاد بناء الشريحة المجسّدة كل ليلة وعند طلبك، لذا يقرأ التقرير الأعضاء كما كانوا عند آخر إعادة بناء لا كما هم الآن. وتذكر التقارير الطابع الزمني الذي استخدمته.

عرض حالة التجسيد

GET /segments/:id/materialization

curl -X GET https://api-eu1.joryio.com/api/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/materialization \
  -H "Authorization: Bearer jry_live_your_api_key"

{
  "materialized": true,
  "refreshedAt": "2026-09-03T03:00:00.000Z",
  "memberCount": 482103,
  "error": null,
  "used": 4,
  "quota": 20
}

تكون refreshedAt بقيمة null إلى أن تكتمل أول إعادة بناء. وتحمل error سبب فشل آخر إعادة بناء، حتى تستطيع اللقطة القديمة أن تقول لماذا هي قديمة؛ وتستمر قائمة الأعضاء السابقة في الخدمة بدل أن تفرغ الشريحة. وقيمة quota تساوي -1 تعني بلا حد.

كل الشرائح المجسّدة في المؤسسة

GET /segments/materialization/usage

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

{
  "quota": 20,
  "used": 2,
  "segments": [
    {
      "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
      "name": "Champions",
      "workspaceId": "8c1f0b2a-91d4-4a77-9a3e-2d6f7b5c1e40",
      "refreshedAt": "2026-09-03T03:00:00.000Z",
      "memberCount": 1200,
      "error": null
    }
  ]
}

التفعيل

POST /segments/:id/materialization

تجري أول عملية بناء فورًا دون انتظار الليل. تُعيد نفس كائن الحالة.

تُعيد 400 عندما لا تتوفر لدى المؤسسة مقاعد شاغرة، مع ذكر أسماء الشرائح التي تشغلها لتختار ما تُوقفه.

التعطيل

DELETE /segments/:id/materialization

يحذف الأعضاء المخزّنين ويحرّر المقعد.

إعادة البناء الآن

POST /segments/:id/materialization/refresh

يعيد حساب الأعضاء فورًا. تُبنى قائمة الأعضاء كاملة من جديد ولا يُضاف إليها فحسب، فيُزال من لم يعد مستوفيًا للشروط تمامًا كما يُضاف الجدد - وهذا مهم لأن الناس يخرجون من الشريحة دون أن يفعلوا شيئًا: فالمشتري يخرج من "لا عمليات شراء خلال 30 يومًا" لمجرد تقدّم التاريخ.

اختبار المرشحات قبل استخدامها

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

معاينة الجمهور

POST /segments/preview

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

{ "count": 4820 }

عيّنة من المستخدمين المطابقين

POST /segments/preview-users

الاستعلام نفسه، مع إعادة عيّنة من جهات الاتصال الفعلية لترى إن كانوا الأشخاص الذين قصدتهم.

فحص مستخدم واحد

POST /segments/check-user

هل تطابق هذه الجهة مجموعة المرشحات؟ إنها البوابة الفردية التي يحتاجها التكامل حين يقرّر بشأن شخص واحد لا حين يبني جمهورًا.

الاستجابة:

{ "userId": "user_123", "matches": true }

التوزيع حسب القناة

POST /segments/channel-breakdown

كم من جهات الاتصال المطابقة يمكن الوصول إليها فعلًا في كل قناة. شريحة من 10,000 فيها 400 رقم هاتف ليست جمهور SMS من 10,000، وهنا يتضح ذلك قبل جدولة الإرسال.

الاستجابة:

{
  "email": 9210,
  "sms": 400,
  "push": 3110,
  "whatsapp": 280,
  "viber": 95,
  "matched": 10000,
  "capped": false
}

matched هو المجتمع الذي تُعد أعداد القنوات مجموعة جزئية منه، وcapped تكون true عندما يكون التقسيم أكبر من أن يُحل بدقة (عندها تخص الأعداد العينة التي جرى حلها). عدد القناة هو ما يمكن لمسار الإرسال الوصول إليه فعليًا: جهة اتصال مشتركة بلا عنوان أو بلا هاتف أو بلا جهاز مسجل لا تُحتسب. يُعاد فحص سجل STOP الهاتفي وقوائم حظر العناوين وقت الإرسال، لذا لا يمكن للإرسال الفعلي إلا أن يكون أصغر.

الإنشاء الجماعي والتصدير

POST /segments/bulk
GET /segments/exports

ينشئ POST /segments/bulk عدة شرائح بنداء واحد - لتهيئة مساحة عمل من إعداداتك بدل النقر في الواجهة. ويعرض GET /segments/exports مهام التصدير مع حالتها ورابط التنزيل الموقّع مسبقًا عند اكتمالها.

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

الحذف مقابل الأرشفة

POST   /segments/{segmentId}/archive
DELETE /segments/{segmentId}

الأرشفة هي الوضع الافتراضي. الشريحة المؤرشفة تتوقف عن الظهور في المنتقيات وفي عمليات فحص العضوية، بينما تستمر كل حملة أو رحلة تشير إليها بالفعل في العمل. وللتراجع: POST /segments/{segmentId}/unarchive.

أما الحذف فيزيلها نهائيًا، وفقط حين لا يشير إليها شيء. فإن كانت حملة أو رحلة أو حملة داخل التطبيق أو شريحة أخرى ما زالت تستخدمها، يعيد الطلب 409 ويسمّيها.

يقيّم GET /users/{userId}/segments كل شريحة نشطة مقابل جهة الاتصال، لذا فمساحة العمل التي تراكم الشرائح تدفع ثمنها في كل فحص عضوية. والحل هو أرشفة أو حذف ما لم تعد تستخدمه.

المصادقة​

إنشاء شريحة​

بنية الفلتر​

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

الاستجابة​

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

عرض الشرائح​

تحديث شريحة​

أرشفة شريحة​

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

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

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

عوامل السمات​

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

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

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

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

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

حدود المعدل​

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

إبقاء الشريحة جاهزة للتقارير​

عرض حالة التجسيد​

كل الشرائح المجسّدة في المؤسسة​

التفعيل​

التعطيل​

إعادة البناء الآن​

اختبار المرشحات قبل استخدامها​

معاينة الجمهور​

عيّنة من المستخدمين المطابقين​

فحص مستخدم واحد​

التوزيع حسب القناة​

الإنشاء الجماعي والتصدير​

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

الحذف مقابل الأرشفة​