Users API

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

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

المصادقة

Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

إنشاء مستخدم أو تحديثه

أنشئ مستخدماً جديداً أو حدّث سمات مستخدم قائم.

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

POST /users

الحقل	النوع	مطلوب	الوصف
externalId	string	واحد من externalId / email	معرّف المستخدم الفريد لديك، حتى 255 حرفاً، وهو مفتاح الإنشاء أو التحديث.
email	string	واحد من externalId / email	Email المستخدم.
userId	string	لا	معرّف المستخدم الداخلي في Joryio، سداسي من 24 حرفاً ومن استجابات API، للتحديث فقط ولا ينشئ أبداً. لا يجتمع مع externalId.
phone	string	لا	هاتف المستخدم، حتى 20 حرفاً.
attributes	object	لا	سمات مخصصة، حتى 200 مفتاح و50KB وعمق 5.
subscriptions	array	لا	عضويات قوائم اشتراك تطبق في الطلب نفسه، حتى 100.
events	array	لا	أحداث تستقبل في الطلب نفسه، حتى 25.

userId هو معرّف Joryio الداخلي وللتحديث فقط

userId وexternalId ليسا اسمين بديلين. userId هو id الداخلي ذو 24 حرفاً الذي يصدره Joryio فقط؛ إرسالُه يحدّث المستخدم المحدد أو يعيد 404 إذا لم يوجد. لا ينشئ مستخدماً ولا يطابق externalId. يُرفض userId غير ذي 24 حرفاً بـ 400، كما يُرفض إرسال userId وexternalId معاً. لإنشاء مستخدم أو تحديثه بمعرّفك أنت، مهما كان شكله، استخدم externalId.

اشتراكات مضمّنة

لـ onboarding في طلب واحد، مرر عضويات القوائم بدلاً من POST /subscriptions/contacts/:userId/lists/:listId منفصلاً لكل قائمة:

الحقل	النوع	مطلوب	الوصف
listId	string	نعم	معرّف قائمة الاشتراك.
channel	string	لا	email أو sms أو whatsapp أو push أو viber، والافتراضي email.
status	string	لا	subscribed الافتراضي أو unsubscribed.

تكتب صفوف الموافقة عبر المسار المدقق نفسه لنقطة الاشتراك المستقلة، مع source: api. لا يُحيي عنصر اشتراك صراحةً إلغاءً قائماً لقائمة أو قناة؛ يُتخطى ويُبلغ عنه. تتطلب إعادة الموافقة الصريحة نقطة اشتراك مخصصة. كذلك يُبلغ عن فشل كل عنصر، كـ listId غير معروف، ولا يتراجع upsert للملف الشخصي.

أحداث مضمّنة

تدخل كل الأحداث خط أحداث القياسي؛ فتعمل محفزات الرحلات والشرائح والتحليلات كما في POST /events/track:

الحقل	النوع	مطلوب	الوصف
name	string	نعم	اسم الحدث حتى 255 حرفاً، ويفضل اسم قياسي مثل Order Completed.
properties	object	لا	خصائص الحدث بالحدود نفسها لنقطة track.
timestamp	string أو number	لا	ISO 8601 أو ميلي ثانية epoch، والافتراضي الآن.

مثال

curl -X POST https://api-eu1.joryio.com/users \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_123",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "attributes": { "firstName": "John", "lastName": "Doe", "plan": "premium", "signupDate": "2024-01-15T10:30:00Z" },
    "subscriptions": [{ "listId": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d", "channel": "email" }],
    "events": [{ "name": "Order Completed", "properties": { "orderId": "ord_789", "total": 129.90, "currency": "USD" } }]
  }'

يعاد كائن المستخدم مباشرة. يكون id وuserId معرّف Joryio الداخلي، ويُعاد externalId الذي أرسلته. تظهر حقول الملخص subscriptions وevents فقط عند تقديم المدخلين؛ العناصر المتخطاة هي { listId, channel, reason } والأحداث المرفوضة { name, reason }.

• عند وجود المستخدم، تندمج السمات وتحفظ المفاتيح غير الموجودة في الطلب.
• تخزن السمة null بالقيمة null ولا تحذف المفتاح.
• تُفهرس Email والهاتف تلقائياً للتقسيم.
• تطبق الاشتراكات والأحداث المضمنة بعد upsert؛ لا يفشل الطلب ولا يتراجع المستخدم عند فشل عنصر.

الحصول على مستخدم بالمعرّف

يوجد مساران:

• GET /users/by-user-id/:userId للبحث بمعرّفك، أي externalId، وهو الموصى به للتكاملات.
• GET /users/:userId للبحث بمعرّف Joryio الداخلي ذي 24 حرفاً.

GET /users/by-user-id/:userId

يعيد كائن المستخدم مباشرة، شاملاً id وuserId الداخليين وexternalId وEmail والهاتف والسمات والشرائح والطوابع الزمنية.

عرض المستخدمين

GET /users

النتائج مرتبة بالأحدث تحديثاً أولاً. لا يدعم المسار فلاتر سمات أو ترتيباً؛ استخدم Segments للتقسيم بالسمات أو GET /users/search?query=... للبحث بالاسم أو Email أو الهاتف أو المعرّف.

المعامل	النوع	الافتراضي	الوصف
limit	number	50	نتائج الصفحة، بحد أقصى 200.
offset	number	0	عدد المستخدمين المتجاوز.

تعيد الاستجابة data للمستخدمين وpagination بـ total وlimit وoffset وhasMore.

تحديث مستخدم

حدّث Email أو الهاتف أو السمات من دون استبدال الملف كله. تندمج السمات لكل مفتاح. يستخدم التحديث PUT ولا توجد نقطة PATCH:

PUT /users/by-user-id/:userId
PUT /users/:userId

المسار الأول بمعرّفك، والثاني بمعرّف Joryio الداخلي.

الحقل	النوع	الوصف
email	string	Email جديد.
phone	string	هاتف جديد.
attributes	object	سمات تُدمج كتحديث لكل مفتاح.

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

حذف مستخدم

احذف مستخدماً وكل بياناته المرتبطة نهائياً.

DELETE /users/:userId

معامل المسار هو معرّف Joryio الداخلي. إن كان لديك معرّفك فقط فابحث أولاً بـ GET /users/by-user-id/:userId. يتطلب الحذف نطاق users:delete ويعيد 204 No Content بلا نص.

• الإجراء دائم ولا يمكن التراجع عنه.
• يحذف الملف والأحداث وسجل الحملات.
• يزيل المستخدم من جميع الشرائح.
• لا تستهدفه الحملات النشطة بعد ذلك.

العمليات الجماعية، نص المصفوفة

لا توجد نقطة جماعية مستقلة: يقبل POST /users كائن مستخدم أو مصفوفة JSON مجردة من المستخدمين. ينشئ شكل المصفوفة أو يحدّث حتى 1000 مستخدم في طلب واحد.

POST /users
Content-Type: application/json

[ { ...user }, { ...user } ]

يتبع كل عنصر شكل المستخدم المفرد، بما فيه subscriptions وevents. تنطبق الحدود لكل عنصر: 100 اشتراك و25 حدثاً. يتحقق من كل عنصر، ويُبلغ عن غير الصالح في failed بفهرسه، وتُعالج العناصر الصالحة الأخرى.

{
  "processed": 2,
  "created": 1,
  "updated": 1,
  "failed": [],
  "subscriptions": { "applied": 1, "skipped": 0 },
  "events": { "accepted": 1, "rejected": 0 }
}

• الحد الأقصى 1000 مستخدم لكل طلب.
• إجماليات مستوى الطلب: 500 حدث مضمن و1000 اشتراك مضمن عبر المصفوفة. عند تجاوزها أرسل الأحداث إلى POST /events/track والعضويات إلى نقطة الأعضاء الجماعية للقوائم.
• المعالجة على دفعات متوازية من 10، ويسمح بالفشل الجزئي.
• ملخصا subscriptions وevents أعداد مجمعة؛ استخدم كائن المستخدم الواحد عندما تحتاج أسباب التخطي أو الرفض المفصلة.
• لاستيراد الملفات أو الهجرات الكاملة، استخدم Bulk Import في اللوحة أو Warehouse sync، لا حلقات batching يدوية.

أحداث المستخدم

الحصول على أحداث مستخدم

GET /users/:userId/events

معامل المسار هو معرّف Joryio الداخلي.

المعامل	النوع	الافتراضي	الوصف
limit	number	50	الأحداث المعادة، بحد أقصى 1000.
offset	number	0	إزاحة الترقيم.
startDate	string	-	الأحداث بعد هذا التاريخ، ISO 8601.
endDate	string	-	الأحداث قبل هذا التاريخ، ISO 8601.
eventName	string	-	تصفية باسم الحدث.
groupBySession	boolean	false	إعادة الأحداث مجمعة بحسب الجلسة أيضاً.

تستخدم حقول الحدث snake_case لأنها من مخزن التحليلات، مثل event_id وevent_name وproperties وtimestamp. تعيد الاستجابة data وtotal وlimit وoffset.

السمات الشائعة

email وphone حقول ملف في المستوى الأعلى وليسا سمات؛ أرسلهما في المستوى الأعلى لنص الطلب.

السمة	النوع	الوصف
firstName	string	الاسم الأول؛ يستخدم في البحث والعرض.
lastName	string	اسم العائلة؛ يستخدم في البحث والعرض.
language	string	اللغة المفضلة؛ تضبطها SDKs تلقائياً عند توفرها.
timezone	string	منطقة المستخدم IANA؛ تقود الوقت الهادئ وتسليم الرحلة بالوقت المحلي.
country	string	رمز الدولة؛ مفهرس للتقسيم.

يمكنك إضافة سمات مخصصة، مثل الخطة وMRR ومصدر التسجيل وقيمة العمر والوسوم والتفضيلات. الأنواع المدعومة: string وnumber وboolean وتاريخ ISO 8601 ومصفوفة وكائن متداخل.

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

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

الحالة	مثال للسبب
400	لا يمكن إنشاء أو تحديث مستخدم من دون externalId أو email صالح؛ userId يحدّث فقط مستخدماً قائماً.
401	مفتاح API غير صالح أو منتهي.
404	المستخدم غير موجود بالمعرّف المطلوب.

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

1. إعادة المحاولة آمنة: POST /users عملية upsert بمفتاح معرّفك، فتحدّث الطلبات المكررة الملف نفسه ولا تنشئ تكراراً. لا يوجد رأس Idempotency-Key؛ أعد الطلب كما هو عند فشل الشبكة.
2. سمِّ السمات بوضوح واتساق: استخدم signupDate وlifetimeValue وplan بدلاً من اختصارات مبهمة.
3. استخدم E.164 للهاتف: مثل +1234567890، لا تنسيقات محلية مثل (123) 456-7890.

حدود المعدل

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

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

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