تخطّ إلى المحتوى الرئيسي

مفاتيح API

تُصادَق كل طلبات Joryio REST API باستخدام مفتاح API. يرتبط كل مفتاح بمساحة عمل واحدة، ويحمل قائمة صريحة من الصلاحيات، ويمكن تقييده بمجموعة عناوين IP.

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

إنشاء مفتاح​

  1. افتح لوحة Joryio وانتقل إلى Settings ← API Keys.
  2. انقر Create API Key.
  3. امنح المفتاح اسمًا ووصفًا اختياريًا يراه زملاؤك.
  4. أضف اختياريًا قائمة سماح IP: قائمة CIDR أو عناوين IP مفردة مفصولة بفواصل أو مسافات. اتركها فارغة للسماح بأي IP.
  5. حدّد الصلاحيات التي يحتاجها المفتاح. اختر أصغر مجموعة تحقق الغرض؛ راجع كتالوج النطاقات أدناه.
  6. انقر Create key.
عرض لمرة واحدة

تظهر قيمة المفتاح الكاملة مرة واحدة فقط، مباشرة بعد الإنشاء، ولا تظهر مجددًا. انسخها إلى مدير الأسرار لديك، مثل 1Password أو Vault أو AWS Secrets Manager، قبل إغلاق النافذة. إن فقدتها، احذف المفتاح وأنشئ آخر؛ لا يستطيع Joryio استعادة القيمة الأصلية.

صيغة المفتاح هي jry_live_<random> لمفاتيح الإنتاج وjry_test_<random> لمفاتيح الاختبار. تظهر بادئة المفتاح المرئية، مثل jry_live_abc123، في قائمة المفاتيح في لوحة التحكم وسجلات الخادم، لتعرف أي مفتاح نفذ أي إجراء من دون كشف قيمته الكاملة.

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

أرسل المفتاح كـ bearer token في رأس Authorization مع كل طلب:

GET /users/by-user-id/user_123
Host: api-eu1.joryio.com
Authorization: Bearer jry_live_98f31a72…
Content-Type: application/json

كتالوج النطاقات​

تأخذ الصلاحيات شكل <resource>:<verb>. الأفعال المستخدمة:

الفعلالمعنىمثال
readسرد السجلات الحالية أو جلبهاusers:read, campaigns:read
writeإنشاء السجلات أو تحديثهاusers:write, segments:write
sendتشغيل إجراء تسليم/إرسالcampaigns:send
deleteإزالة السجلات نهائيًاusers:delete, campaigns:delete
trackإرسال أحداث التحليلاتevents:track
activateبدء سير عمل حي أو إيقافه مؤقتًا أو استئنافهcanvas:activate
aliasإرفاق معرّفات بديلة أو فصلهاusers:alias
mergeدمج ملفَّي مستخدمusers:merge
exportتصدير السجلات بالجملةusers:export

فيما يلي الكتالوج العام الكامل، ويُعاد أيضًا من GET /api-keys/permissions:

Events​

النطاقما يسمح به
events:trackإرسال أحداث مخصصة من خوادمك أو SDK.
events:readالاستعلام عن الأحداث التي تم تتبعها.

Users​

النطاقما يسمح به
users:readالبحث عن ملفات المستخدمين وسماتهم بالمعرّف.
users:writeإنشاء سمات وخصائص المستخدم أو تحديثها.
users:deleteإزالة ملفات المستخدمين نهائيًا (GDPR / حق المحو).
users:aliasإرفاق أو فصل المعرّفات الخارجية وأسماء البريد البديلة لمستخدم.
users:mergeدمج ملفَّي مستخدم في ملف واحد.
users:exportتصدير ملفات المستخدمين بالجملة للتحليل دون اتصال.

Campaigns​

النطاقما يسمح به
campaigns:readسرد الحملات وعرض إعداداتها.
campaigns:writeإنشاء مسودات الحملات أو تعديلها عبر API.
campaigns:sendتشغيل إرسال حملة إلى مستخدم أو شريحة محددة.
campaigns:deleteإزالة الحملات نهائيًا من مساحة العمل.

Segments​

النطاقما يسمح به
segments:readسرد الشرائح وعرض أعداد العضوية.
segments:writeإنشاء تعريفات الشرائح أو تحديثها.
segments:deleteحذف الشرائح وسجلها نهائيًا.

رحلات المستخدمين​

النطاقما يسمح به
canvas:readسرد رحلات المستخدمين وفحص مخطط خطواتها.
canvas:writeإنشاء مسودات رحلات المستخدمين أو تعديلها.
canvas:activateبدء رحلة مستخدم حية أو إيقافها مؤقتًا أو استئنافها.
canvas:deleteإزالة رحلات المستخدمين وسجلها.

القوالب​

النطاقما يسمح به
templates:readجلب محتوى قوالب Email وSMS وPush.
templates:writeإنشاء قوالب الرسائل القابلة لإعادة الاستخدام أو تعديلها.
templates:deleteحذف القوالب نهائيًا من Brand Studio.

الاشتراكات​

النطاقما يسمح به
subscriptions:readعرض حالة قبول المستخدم للاشتراك عبر القنوات.
subscriptions:writeاشتراك المستخدمين أو إلغاء اشتراكهم في المجموعات والقنوات.

Apps ومفاتيح SDK​

النطاقما يسمح به
apps:readسرد التطبيقات ومفاتيح SDK المسجلة لمساحة العمل.
apps:writeإضافة مفاتيح SDK لتطبيقات الجوال والويب أو تدويرها أو إزالتها.

مكتبة الأصول​

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

الكيانات​

النطاقما يسمح به
entities:readالاستعلام عن سجلات الكيانات، كالمنتجات والمقالات والأماكن.
entities:writeإنشاء سجلات الكيانات وخصائصها أو تحديثها.

التحليلات​

النطاقما يسمح به
analytics:readجلب المقاييس المجمعة والمسارات وبيانات التقارير.

قابلية التسليم​

النطاقما يسمح به
email_suppression:readفحص قائمة حظر Email، مثل الارتدادات والشكاوى والإدخالات اليدوية.
email_suppression:writeإضافة إدخالات إلى قائمة حظر Email أو إزالتها.
sms_suppression:readفحص قائمة حظر SMS، مثل ردود STOP والإخفاقات.
sms_suppression:writeإضافة أرقام الهاتف إلى قائمة حظر SMS أو إزالتها.

حدود التكرار​

النطاقما يسمح به
touching_rules:readفحص قواعد حدود التكرار وعداداتها الحالية.
touching_rules:writeإنشاء قواعد حدود التكرار أو تعديلها أو إزالتها.

WhatsApp​

النطاقما يسمح به
whatsapp:readقراءة إعدادات WhatsApp Business.
whatsapp:writeتحديث إعدادات حساب WhatsApp Business.

وكلاء AI​

النطاقما يسمح به
ai_agents:readسرد وكلاء AI وإعداداتهم.
ai_agents:writeإنشاء وكلاء AI أو تعديلهم وإعدادات موفريهم.

قائمة سماح IP​

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

الصيغة المقبولة​

  • عنوان IPv4 عادي: 203.0.113.42
  • نطاق IPv4 CIDR: 10.0.0.0/24 أو 192.168.1.0/16
  • عنوان IPv6: مطابقة تامة فقط؛ لا يوجد CIDR لـ IPv6 بعد.

اجمع إدخالات متعددة بفواصل في لوحة التحكم:

10.0.0.0/24, 203.0.113.42, 2001:db8::1

حل عنوان IP المصدر​

يُستخرج IP العميل من رأس موثوق لشبكة الحافة، يُضبط من جديد مع كل طلب عند الحافة ولا يمكن أن تبقى قيمة يرسلها العميل، ثم يُستخدم عنوان اتصال الوكيل الموثوق كبديل. لا يُستخدم عمدًا إدخال X-Forwarded-For الذي يتحكم به العميل في أقصى اليسار، فلا يمكن تزوير قائمة السماح. تُطبّع عناوين IPv6 المعيّنة بـ IPv4، مثل ::ffff:203.0.113.42، إلى صيغة IPv4 قبل المطابقة.

شكل الطلب المرفوض​

عندما يأتي طلب من IP غير موجود في قائمة السماح، يعيد API الخطأ 401 Unauthorized:

{
  "statusCode": 401,
  "message": "Request IP is not allowed for this API key",
  "timestamp": "2026-05-12T08:14:00.000Z",
  "path": "/users"
}

يُسجل الرفض على الخادم مع بادئة المفتاح وIP المخالف لتتمكن من مراجعته.

نقاط نهاية إدارة المفاتيح​

تُدار المفاتيح من لوحة التحكم (Settings ← API Keys) أو عبر API:

الطريقةنقطة النهايةالوصف
GET/api-keys/permissionsسرد جميع النطاقات القابلة للمنح
POST/api-keysإنشاء مفتاح (?environment=live أو test؛ النص: name وdescription? وpermissions[] وipAllowlist? وexpiresAt?)؛ تُعاد قيمة المفتاح الكاملة مرة واحدة
GET/api-keysسرد مفاتيح مساحة العمل
GET/api-keys/:apiKeyIdجلب بيانات مفتاح واحد
PUT/api-keys/:apiKeyIdتحديث الاسم أو الوصف أو الصلاحيات أو قائمة سماح IP أو انتهاء الصلاحية
POST/api-keys/:apiKeyId/revokeتعطيل مفتاح، فيتوقف عن المصادقة فورًا
POST/api-keys/:apiKeyId/rotateإنشاء قيمة مفتاح جديدة مع الصلاحيات نفسها؛ تُعاد القيمة الجديدة مرة واحدة
DELETE/api-keys/:apiKeyIdحذف مفتاح نهائيًا (يعيد 204)

لا يمكن لأي مستدعٍ أن يمنح مفتاحًا نطاقات لا يحملها هو بنفسه.

حقول استجابة القائمة​

يعيد GET /api-keys كائن { "apiKeys": [...] }، ويكون لكل مفتاح الشكل التالي؛ لا تظهر قيمة المفتاح الكاملة أو تجزئته مطلقًا:

{
  "apiKeys": [
    {
      "id": "7c2e4f6a-1b3d-4e5f-8a9b-0c1d2e3f4a5b",
      "name": "ServerSide Updates",
      "description": "Used by our backend to send events.",
      "keyPrefix": "jry_live_98f31a72",
      "permissions": ["events:track", "users:write"],
      "lastUsedAt": "2026-05-12T08:14:00.000Z",
      "expiresAt": null,
      "isActive": true,
      "createdAt": "2026-02-19T12:00:00.000Z",
      "updatedAt": "2026-02-19T12:00:00.000Z"
    }
  ]
}

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

الأخطاء الشائعة​

الحالةالرسالةما يجب التحقق منه
401Invalid API key formatالرأس مفقود أو غير صالح أو لا يبدأ بـ jry_.
401Invalid or expired API keyأُلغي المفتاح أو حُذف أو مرّ expiresAt الخاص به.
401Request IP is not allowed for this API keyلم يطابق IP المصدر أي إدخال في قائمة السماح. راجع قائمة سماح IP.
403This API key does not have the required permissions: ...المفتاح صالح لكنه لا يحمل النطاق المطلوب لنقطة النهاية.
403ORG_HARD_SUSPENDED: organization is suspended. Read-only access only.أُوقفت المؤسسة المالكة؛ تواصل مع الدعم.

تدوير مفتاح​

استدعِ POST /api-keys/:apiKeyId/rotate أو استخدم لوحة التحكم: يحصل المفتاح على قيمة سرية جديدة وبادئة keyPrefix جديدة، وتُعاد القيمة مرة واحدة في الاستجابة، مع الاحتفاظ بالاسم والنطاقات والمعرّف. تفشل فورًا كل الأنظمة التي ما زالت تستخدم القيمة القديمة؛ لذلك انشر القيمة الجديدة أولًا حيثما أمكن، واستخدم keyPrefix في سجلات الوصول للعثور على التكاملات التي ما زالت تستخدم المفتاح القديم. ولتدوير بلا توقف، أنشئ مفتاحًا ثانيًا بالنطاقات نفسها، وانقل المستدعين إليه ثم احذف المفتاح القديم.