الأحداث

أرسل ما تفعله جهات الاتصال في أنظمتك: إنشاء طلب أو دفعه، أو ترك سلة، أو عرض منتج. يُحفظ كل حدث مرة واحدة، ويُطابق بجهة الاتصال عبر البريد الإلكتروني أو رقم الهاتف في مساحة العمل الافتراضية لمؤسستك، ثم يظهر في سجلها الزمني. يتطلب هذا المسار مفتاحًا يحمل events:write؛ والمفاتيح المنشأة قبل اعتماد النطاقات لا تحمل هذا النطاق.


POST/external/v1/events

تسجيل الأحداث

يحتوي جسم الطلب على events، وهي مصفوفة من 1 إلى 100 حدث. تُفحص جميع الأحداث قبل حفظ أي منها: إذا رُفض أحدها، يُرفض الطلب كله ولا يُحفظ شيء منه.

  • اسم
    id
    النوع
    string
    وصف

    مطلوب: معرّفك الخاص للحدث، من 1 إلى 128 محرفًا دون مسافات، مثل order-1001-paid. لا يُحفظ الحدث المرسل مجددًا بالمعرّف نفسه إلا مرة واحدة، لذا يمكن إعادة المحاولة دون تكراره.

  • اسم
    type
    النوع
    string
    وصف

    مطلوب: ما حدث، من أحد الأنواع أدناه.

  • اسم
    occurredAt
    النوع
    string
    وصف

    مطلوب: وقت حدوثه بصيغة ISO 8601، مثل 2026-10-20T10:00:00Z. لا يجوز أن يتقدم الوقت الحالي بأكثر من خمس دقائق أو يسبقه بأكثر من 3,650 يومًا.

  • اسم
    email
    النوع
    string
    وصف

    عنوان البريد الإلكتروني للشخص. قدّم هذا العنوان أو رقم الهاتف أو كليهما.

  • اسم
    phone
    النوع
    string
    وصف

    رقم هاتف الشخص مع رمز البلد، مثل +919812345678.

  • اسم
    value
    النوع
    number
    وصف

    قيمة الحدث، بدءًا من 0 وبحد أقصى 14 رقمًا في الجزء الصحيح وأربع منازل عشرية، مثل 1299.50. أرسل معها currency. لا يحمل الحدث customer.created قيمة.

  • اسم
    currency
    النوع
    string
    وصف

    عملة القيمة، برمز ISO 4217 مثل INR.

  • اسم
    properties
    النوع
    object
    وصف

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

نوع الحدثما الذي حدثالخصائص المسموحة
order.placedتم إنشاء طلبorderNumber, itemCount, productIds
order.paidتم دفع قيمة طلبorderNumber, itemCount, productIds
order.fulfilledتم تنفيذ طلبorderNumber, itemCount, productIds
order.cancelledتم إلغاء طلبorderNumber, itemCount, productIds
order.refundedتم رد مبلغ طلبorderNumber, itemCount, productIds
checkout.startedبدأت عملية إتمام الشراءitemCount, productIds
cart.abandonedتُركت سلة تحتوي على عناصرitemCount, productIds
product.viewedتم عرض منتجproductId
customer.createdأصبح الشخص عميلًالا توجد
  • يتكون orderNumber و**productId** وكل معرّف في productIds من 1 إلى 64 محرف ASCII. يجب أن يبدأ بحرف أو رقم أو #؛ ويمكن أن تتضمن بقية المحارف . _ : / - أيضًا، مثل #1001 أو gid://shopify/Product/2.
  • itemCount عدد صحيح من 0 إلى 10,000، و**productIds** يحتوي على 1 إلى 50 معرّفًا.
  • الحد الأقصى للخصائص هو 4 KB، ولا تقبل إلا المعرّفات والأعداد المذكورة أعلاه. لا تضع فيها بيانات بطاقات الدفع أو العناوين أو النص الحر؛ عرّف الشخص باستخدام email وphone.

طلب مدفوع وسلة متروكة

curl -X POST https://api.oblic.app/external/v1/events \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      {
        "id": "order-1001-paid",
        "type": "order.paid",
        "occurredAt": "2026-10-20T10:00:00Z",
        "email": "asha@example.org",
        "value": 1299.50,
        "currency": "INR",
        "properties": { "orderNumber": "#1001", "itemCount": 2, "productIds": ["SKU-1", "SKU-2"] }
      },
      {
        "id": "cart-7781",
        "type": "cart.abandoned",
        "occurredAt": "2026-10-20T11:30:00Z",
        "phone": "+919812345678",
        "properties": { "itemCount": 1, "productIds": ["SKU-3"] }
      }
    ]
  }'

الاستجابة

{
  "status": "success",
  "data": { "received": 2, "stored": 2, "duplicates": 0, "unmatched": 1 },
  "errors": null
}

تكون حالة الاستجابة 202:

  • يعدّ stored الأحداث الجديدة المحفوظة، ويعدّ duplicates الأحداث التي حُفظت سابقًا بحسب id فلم تُحفظ مرة أخرى.
  • يعدّ unmatched الأحداث المحفوظة التي لم تُطابق بجهة اتصال بعد. تُختار أقدم جهة اتصال في مساحة العمل الافتراضية تحمل البريد الإلكتروني، وإلا فرقم الهاتف كهاتف أو رقم WhatsApp. ينتظر الحدث إن لم توجد مطابقة. تعمل خدمة المطابقة عادة كل عشر دقائق عند تفعيلها؛ وقد يؤخرها تراكم العمل أو العطل. وتحذف الخدمة الأحداث التي بقيت دون مطابقة بعد 30 يومًا من استلامها. لا يُنشئ الحدث جهة اتصال أبدًا.
  • تُرسل أحداث الحساب الفرعي مع X-Oblic-On-Behalf-Of الخاص به، مثل رسائله (راجع الحسابات الفرعية).
الرفضcdالسبب
400UNKNOWN_EVENT_TYPEقيمة type للحدث ليست من الأنواع المعروفة
400PERSON_REQUIREDلا يقدم الحدث email ولا phone
400INVALID_VALUEوجود value دون currency أو currency دون قيمة، أو قيمة سالبة، أو أكثر من 14 رقمًا صحيحًا أو أربع منازل عشرية، أو قيمة لحدث customer.created
400INVALID_PROPERTIESخاصية غير مسموحة لهذا النوع أو ذات صيغة غير صحيحة
400INVALID_OCCURRED_ATيتقدم occurredAt الوقت الحالي بأكثر من خمس دقائق أو يسبقه بأكثر من 3,650 يومًا
400الحقل المعني، مثل EVENTS[0].IDغياب events أو فراغها أو تجاوزها 100 عنصر، أو غياب حقل أو عدم صحة صيغته
403INSUFFICIENT_SCOPEلا يحمل المفتاح events:write

تحدد حالات الرفض الحقل أو موضع الحدث في المصفوفة، مثل events[2].type، بدلًا من إعادة عنوان البريد أو الهاتف أو قيم الخصائص. قد ترد أسماء الخصائص غير المعروفة في التوضيح؛ فلا تضع معلومات حساسة في الأسماء أيضًا. يسبق فحص البنية الفحوص الخاصة بالنوع، وتعرض الاستجابة المشكلات التي عُثر عليها في تلك المرحلة.


بدء رحلة

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

  • مرة لكل حدث: جهة الاتصال التي تدفع طلبين تبدأ الرحلة مرتين؛ أما إعادة إرسال حدث بالـ id نفسه فتبدأها مرة واحدة.
  • حدث حديث فقط: يبدأ الحدث الرحلات إذا حُفظ مع جهة اتصاله أو طُوبق بها لاحقًا خلال 24 ساعة من occurredAt. يظهر الحدث الأقدم، كاستيراد طلبات سابقة، في السجل ويُحتسب للشرائح، لكنه لا يبدأ رحلة.
  • المنتجات والقيمة: تُطابق المنتجات مع productIds للطلب أو عملية الشراء أو السلة، أو مع productId المعروض. ويجب أن تبلغ القيمة الحد الأدنى بالعملة المحددة. لا يحمل الحدث customer.created أيًا منهما، فلا يقيّده هذان الشرطان.

من Shopify

عندما تُضبط إضافة Shopify ورابط تثبيتها، اربط متجرًا من إعدادات → التكامل → متجر Shopify: ثبّت تطبيق Oblic في Shopify، ثم اربط المتجر بمؤسستك. إن لم يتوفر التكامل، اطلب من المسؤول إعداده أولًا. تتحول الطلبات إلى الأنواع أعلاه، وتُطابق بجهات الاتصال عبر البريد أو الهاتف كالأحداث التي ترسلها. ويصبح المشتركون في التسويق بالبريد أو SMS جهات اتصال مع تسجيل موافقتهم.

مصدر Shopifyالحدث الناتج
طلب أُنشئ أو دُفع أو نُفّذ أو أُلغيorder.placed, order.paid, order.fulfilled, order.cancelled
رد مبلغorder.refunded للشخص الذي قدّم الطلب وبقيمة المبلغ المردود
عملية شراء تحمل بريدًا إلكترونيًا أو رقم هاتفcheckout.started
عملية شراء خاملة لمدة ساعة دون إنشاء طلبcart.abandoned مرة لكل عملية شراء
عميل اشترك في التسويق ولم يصبح جهة اتصال بعدcustomer.created عندما ينشئ Oblic جهة الاتصال
  • محتوى الحدث: قيمة الطلب بعملة المتجر ورقمه وعدد عناصره ومنتجاته بمعرّفات Shopify. لا يحتفظ الحدث بتفاصيل أخرى من الطلب.
  • العملاء المشتركون: يُبحث عن العميل المشترك في تسويق البريد أو SMS في Shopify بين جهات اتصالك وفق قواعد مطابقة الأحداث. إن لم يُعثر عليه، يُنشأ في مساحة العمل الافتراضية باسم عنوانه أو رقمه وتُسجل الموافقة عليهما. لا يُنشأ العميل غير المشترك كجهة اتصال.
  • إلغاء الاشتراك: من يلغي اشتراكه في Shopify يُلغى اشتراكه في بريدك أو لا يتلقى SMS من الحملات والأتمتة والرحلات إلى أن يشترك هناك مجددًا. لا يعكس Shopify إلغاء اشتراك بريدي أجراه الشخص في Oblic، مثل رابط إلغاء الاشتراك في رسالة.
  • قطع الاتصال: افصل المتجر من الصفحة نفسها ثم أزل تطبيق Oblic من Shopify. تبقى الأحداث عند الفصل. يُحذف المتجر وأحداثه عند معالجة طلب Shopify اللاحق shop/redact، وليس بمجرد قطع الاتصال.
  • خصوصية العملاء: عند طلب Shopify حذف بيانات عميل، تُحذف أحداثه من ذلك المتجر. وإن سُجلت موافقته على جهة اتصال، يُخطَر مالكو المؤسسة في Oblic لحذفها. ويُخطَر المالكون أيضًا عندما يطلب العميل بياناته.
هل كانت هذه الصفحة مفيدة؟