العثور على شخص
استخدم GET /users. فهو يجيب عن كل عمليات البحث، مع ترقيم الصفحات والمجموع.
# بمعرّفك أنت
curl "https://api-eu1.joryio.com/api/users?externalId=user_123" \
-H "Authorization: Bearer jry_live_your_api_key"
# بالبريد الإلكتروني
-H "Authorization: Bearer jry_live_your_api_key"
# بحث جزئي - كل ما يبدأ بـ "jane"، مع مطابقة الهاتف والمعرّف
curl "https://api-eu1.joryio.com/api/users?q=jane" \
-H "Authorization: Bearer jry_live_your_api_key"
أي معامل تستخدم
| ما لديك | استخدم | نوع المطابقة |
|---|---|---|
| معرّفك أنت | ?externalId= | تامة |
| عنوان بريد إلكتروني | ?email= | تامة، دون حساسية لحالة الأحرف |
| معرّف Joryio الداخلي (24 خانة hex) | ?userId= | تامة |
| جزء من شيء - اسم، بداية بريد، رقم هاتف | ?q= | بداية النص في البريد وفي externalId وفي الاسم الأول واسم العائلة؛ والأرقام في أي موضع من الهاتف؛ والقيمة كاملة لمعرّف من 24 خانة أو anonymousId بصيغة UUID |
المعاملات التامة تتجمّع معاً (?email=…&externalId=… يتطلب كليهما). أما q فيُتجاهَل عند وجود معامل تام - فـ«البريد يساوي X» و«حقل ما يبدأ بـ Y» لا يمكنهما تضييق الطلب نفسه معاً، ودمجهما بصمت كان سيجيب عن سؤال لم تطرحه.
عندما لا يُعثر على شيء
صفحة فارغة، لا خطأ 404:
{ "data": [], "pagination": { "total": 0, "limit": 50, "offset": 0, "hasMore": false } }
ترتيب القائمة كلها: sortBy (createdAt أو updatedAt أو email أو name؛ الافتراضي updatedAt) وsortOrder (asc أو desc؛ الافتراضي desc). الترتيب ثابت بين الصفحات - لا ينتقل أي صف بينها.
والـ userId الذي ليس من 24 خانة hex يعيد الصفحة الفارغة نفسها بدل خطأ - فالمعرّف المشوّه بحث لا يطابق أحداً، لا طلب معطوب.
معامل لا نتعرّف عليه
إن بدا المعامل خطأً إملائياً لمعامل حقيقي، أو إن لم يكن أي من معاملاتك معروفاً، يُرفض الطلب:
{ "statusCode": 400,
"message": "Unknown query parameter 'externalid'. Did you mean 'externalId'? Valid parameters: limit, offset, email, externalId, userId, q, bots, sortBy, sortOrder" }
وكان هذا سابقاً استجابة 200 صامتة مع الصفحة الكاملة بلا تصفية، وهكذا كلّف خطأ إملائي أحد المطوّرين يوماً كاملاً - فالمرشّح الذي لا يفعل شيئاً يبدو تماماً كالمرشّح الذي وجد كل شيء.
أما المعاملات التي تصل دون أن تختار إرسالها فما زالت تُقبل ويُتجاهَل مضمونها: _ و_* (مبطِّل التخزين المؤقت في jQuery)، وutm_*، وgclid، وfbclid، وmsclkid، وt / v / cb. فـ[email protected]&_=1724500000 يعمل، وكذلك ?_=1724500000 وحده.
والمعامل غير المألوف الذي لا يشبه شيئاً من معاملاتنا - كمعرّف ترابط من بوابة API مثلاً - يُقبل أيضاً، ما دام هناك معامل واحد على الأقل نفهمه. فالقاعدة ليست «ارفض كل ما هو غير معروف»، بل «ارفض طلباً ما كان ليفعل ما قصدته».
المساران الآخران
كلاهما ما زال يعمل، ولا يفعل أي منهما شيئاً لا يستطيعه GET /users.
| المسار | يبقى مفيداً حين |
|---|---|
GET /users/by-user-id/:externalId | تريد السجل نفسه لا صفحة تحتويه - فهو يعيد كائن المستخدم مباشرة |
GET /users/search?query= | تريد الشكل القديم: مصفوفة مجردة، محدودة، بلا total |
أما GET /users/:userId (معرّف Joryio الداخلي) فهو المسار المعتمد للسجل المفرد وهو باقٍ - وإليه يشير id في كل استجابة.
جهات الاتصال المجهولة
من جرى تتبّعه قبل تحديد هويته ليس له بريد ولا هاتف ولا اسم. والمقبض الوحيد لديك هو anonymousId الذي أنشأه SDK، و?q= يطابقه حين يكون المصطلح بصيغة UUID:
curl "https://api-eu1.joryio.com/api/users?q=3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d" \
-H "Authorization: Bearer jry_live_your_api_key"
ولربط تاريخ تلك الجلسة بشخص معروف، راجع POST /users/identify.