مرجع الأحداث

تسرد هذه الصفحة كل حدث ويب هوك يمكن أن ترسله TakeTheme وشكل الحمولة التي يحملها. وتشترك جميع الأحداث في بنية الغلاف نفسها، ويختلف data.object باختلاف الحدث.

الغلاف

كل تسليم، ولكل نوع حدث، يأتي داخل هذا الغلاف:

{
  "id": "3f1c2b9e-8a4d-4c7e-9b1a-2d6f8e0c1a34",
  "type": "order.paid",
  "created": 1751371200.123,
  "data": {
    "object": { "...": "the order object" }
  }
}

id — معرّف الحدث الفريد (UUID). يُرسَل أيضًا في ترويسة X-TakeTheme-Delivery. استخدمه لإسقاط المكرر.
type — أحد أنواع الأحداث أدناه. يُرسَل أيضًا في ترويسة X-TakeTheme-Event.
created — طابع زمني Unix (بالثواني) للحظة إنشاء الحدث.
data.object — المورد؛ وهو كائن الطلب في جميع الأحداث أدناه.

أحداث الطلبات

تحمل جميع أحداث الطلبات كائن الطلب نفسه في data.object. ويخبرك type بما تغيّر، وتُظهر لك حقول الحالة في الكائن النتيجة النهائية.

الحدث	المُشغِّل
`order.placed`	إنشاء طلب جديد (شراء من المتجر، أو طلب أنشأه المسؤول، أو إكمال طلب مسوّدة).
`order.paid`	تحصيل المبلغ أو تعليم الطلب كمدفوع يدويًا.
`order.fulfilled`	تعليم الطلب — أو ما تبقّى من عناصره — كمُجهَّز.
`order.cancelled`	إلغاء الطلب.
`order.returned`	تعليم الطلب كمرتجع.
`order.refunded`	استرداد مبلغ الطلب (كليًا أو جزئيًا).
`order.updated`	تعديل الطلب (العناصر، العنوان، التتبع، الملاحظات، التعليق أو رفعه، الأرشفة، وغيرها). مُجمَّع في تسليم واحد لكل طلب كل نحو 5 ثوانٍ.

كائن الطلب

قيمة data.object في أحداث الطلبات:

الحقل	النوع	الوصف
`id`	نص	معرّف الطلب الفريد.
`internalId`	نص	رقم الطلب الظاهر للبشر (مثل `1042`). استخدمه في واجهتك بدل `id`.
`trackNumber`	نص	رقم التتبع (قد يكون فارغًا في بعض الطلبات).
`status`	نص	حالة الطلب (مثل `open` و`cancelled`).
`paymentStatus`	نص	حالة الدفع (مثل `unpaid` و`paid` و`partially_refunded` و`refunded`).
`fulfillmentStatus`	نص	حالة التجهيز (مثل `unfulfilled` و`partially_fulfilled` و`fulfilled`).
`totalPrice`	رقم	إجمالي الطلب بعملة المتجر.
`currency`	نص	رمز العملة ISO (مثل `EGP` و`USD`).
`payment`	كائن	تفصيل المبالغ — انظر أدناه.
`discountCode`	نص \| null	رمز الكوبون المطبَّق إن وُجد.
`appliedDiscounts`	مصفوفة	الخصومات التلقائية وخصومات الرموز المطبَّقة على الطلب.
`customer`	كائن	`{ customerId, name, email, phone }` لعميل الطلب.
`contact`	كائن	`{ email, phone }` على مستوى الطلب (يُملأ في طلبات الضيوف والدفع عند الاستلام).
`items`	مصفوفة	بنود الطلب — انظر أدناه.
`deliveryStatus`	مصفوفة	الشحن والتتبع لكل بند — انظر أدناه.
`shippingAddress`	كائن	عنوان الشحن (قد يكون فارغًا في الطلبات الرقمية بالكامل).
`billingAddressSameAsShipping`	منطقي	هل عنوان الفوترة مطابق لعنوان الشحن.
`note`	نص	ملاحظة التاجر أو العميل على الطلب.
`tags`	مصفوفة	وسوم الطلب.
`origin`	نص	قناة الطلب (مثل `online_store` أو لوحة الإدارة).
`isDraft`	منطقي	هل الطلب مسوّدة.
`isAllDigital`	منطقي	هل كل بنود الطلب منتجات رقمية.
`previousStatus`	نص \| null	الحالة السابقة — مفيدة لاكتشاف الانتقال في `order.updated`.
`createdAt`	نص (ISO 8601)	وقت إنشاء الطلب.

الحقل payment:

الحقل	النوع	الوصف
`subTotal`	رقم	مجموع العناصر قبل الشحن والضريبة والخصومات.
`shipping`	رقم	قيمة الشحن المحتسبة.
`tax`	رقم	الضريبة المحتسبة.
`discountAmount`	رقم	إجمالي الخصم المطبَّق.
`handlingFee`	رقم	رسوم المناولة أو الدفع عند الاستلام.
`total`	رقم	الإجمالي الكلي (يساوي `totalPrice`).
`method`	نص	طريقة الدفع (مثل `cod` و`card`).
`provider`	نص \| null	مزوّد الدفع أو البوابة.
`refundedAmount`	رقم	المبلغ المسترد حتى الآن (في أحداث الاسترداد والمرتجعات).
`refundedShipping`	رقم	قيمة الشحن المستردة حتى الآن.

كل عنصر في items:

الحقل	النوع	الوصف
`id`	نص	معرّف بند الطلب (يقابل `deliveryStatus.itemId`).
`productId`	نص	معرّف المنتج (`null` للعناصر المخصصة).
`name`	نص	اسم المنتج وقت الطلب.
`quantity`	رقم	الكمية المطلوبة.
`price`	رقم	سعر الوحدة المحتسب.
`discountPrice`	رقم \| null	سعر الوحدة الأصلي (المشطوب) عند وجود خصم.
`image`	نص \| null	رابط صورة البند المصغّرة.
`variantId`	نص \| null	معرّف الخيار المحدد.
`variantLabel`	نص \| null	وصف الخيار للبشر (مثل `Size: L • Color: Blue`).
`variantDetails`	مصفوفة	`[{ optionName, value }]` للخيار المحدد.
`isPhysicalProduct`	منطقي	هل يحتاج البند إلى شحن.
`isCustomItem`	منطقي	هل هو بند مخصص.
`customInputValue`	نص \| null	تخصيص المشتري (مثل نص النقش).
`removed`	منطقي	`true` إذا أُزيل البند بعد التجهيز — استبعد هذه البنود عند مطابقة `totalPrice`.
`fulfillmentStatus`	نص	حالة التجهيز لهذا البند.

كل عنصر في deliveryStatus:

الحقل	النوع	الوصف
`itemId`	نص	بند الطلب الذي تغطيه هذه الشحنة.
`trackingNumber`	نص \| null	رقم التتبع لدى شركة الشحن.
`trackingUrl`	نص \| null	رابط التتبع لدى شركة الشحن.
`trackingCompany`	نص \| null	اسم شركة الشحن.
`deliveryStatus`	نص \| null	حالة التوصيل كما أبلغت عنها شركة الشحن.

ما يُستبعَد عن قصد

لدواعي الخصوصية والأمان، تستبعد الحمولة الحقول الداخلية والحساسة: معرّفات تتبع الإعلانات (fbc/fbp/عنوان IP/وكيل المستخدم)، وإسناد التحويلات، وتقييم الاحتيال والمخاطر، ورموز التحميل للمنتجات الرقمية، والسجل الزمني الداخلي، وإسناد الموظفين. اجلب الطلب بمعرّفه من واجهة الطلبات إذا احتجت إلى المزيد.

مثال: `order.paid`

{
  "id": "3f1c2b9e-8a4d-4c7e-9b1a-2d6f8e0c1a34",
  "type": "order.paid",
  "created": 1751371200.123,
  "data": {
    "object": {
      "id": "665f1b2c9a3e4d0012ab34cd",
      "internalId": "1042",
      "trackNumber": "TT-1042",
      "status": "open",
      "paymentStatus": "paid",
      "fulfillmentStatus": "unfulfilled",
      "totalPrice": 349.99,
      "currency": "EGP",
      "payment": {
        "subTotal": 329.99,
        "shipping": 20,
        "tax": 0,
        "discountAmount": 0,
        "handlingFee": 0,
        "total": 349.99,
        "method": "card",
        "provider": "kashier",
        "refundedAmount": 0,
        "refundedShipping": 0
      },
      "discountCode": null,
      "appliedDiscounts": [],
      "customer": {
        "customerId": "665d9f0a9a3e4d0012a9f0aa",
        "name": "Mona Adel",
        "email": "mona@example.com",
        "phone": "+201000000000"
      },
      "contact": { "email": "mona@example.com", "phone": "+201000000000" },
      "items": [
        {
          "id": "665f1b2c9a3e4d0012ab3500",
          "productId": "665e0a1b9a3e4d0012aa11bb",
          "name": "Linen Shirt — Medium",
          "quantity": 2,
          "price": 174.995,
          "discountPrice": null,
          "image": "https://cdn.example.com/linen-shirt.jpg",
          "variantId": "665e0a1b9a3e4d0012aa11cc",
          "variantLabel": "Size: M",
          "variantDetails": [{ "optionName": "Size", "value": "M" }],
          "isPhysicalProduct": true,
          "isCustomItem": false,
          "customInputValue": null,
          "removed": false,
          "fulfillmentStatus": "unfulfilled"
        }
      ],
      "deliveryStatus": [],
      "shippingAddress": {
        "name": "Mona Adel",
        "street": "12 Nile St.",
        "city": "Cairo",
        "state": "Cairo",
        "country": "EG"
      },
      "billingAddressSameAsShipping": true,
      "note": "",
      "tags": [],
      "origin": "online_store",
      "isDraft": false,
      "isAllDigital": false,
      "previousStatus": "open",
      "createdAt": "2026-07-01T12:00:00.000Z"
    }
  }
}

مثال: `order.fulfilled`

البنية نفسها؛ لاحظ تغيّر fulfillmentStatus:

{
  "id": "a2b9c1d0-7e6f-4a3b-8c2d-1f0e9d8c7b6a",
  "type": "order.fulfilled",
  "created": 1751374800.501,
  "data": {
    "object": {
      "id": "665f1b2c9a3e4d0012ab34cd",
      "internalId": "1042",
      "trackNumber": "TT-1042",
      "status": "open",
      "paymentStatus": "paid",
      "fulfillmentStatus": "fulfilled",
      "totalPrice": 349.99,
      "currency": "EGP",
      "customer": { "customerId": "665d9f0a9a3e4d0012a9f0aa", "name": "Mona Adel", "email": "mona@example.com", "phone": "+201000000000" },
      "items": [
        { "id": "665f1b2c9a3e4d0012ab3500", "productId": "665e0a1b9a3e4d0012aa11bb", "name": "Linen Shirt — Medium", "quantity": 2, "price": 174.995, "fulfillmentStatus": "fulfilled" }
      ],
      "deliveryStatus": [
        { "itemId": "665f1b2c9a3e4d0012ab3500", "trackingNumber": "EG123456789", "trackingUrl": "https://track.bosta.co/EG123456789", "trackingCompany": "Bosta", "deliveryStatus": "in_transit" }
      ],
      "shippingAddress": { "city": "Cairo", "country": "EG" },
      "createdAt": "2026-07-01T12:00:00.000Z"
    }
  }
}

معالجة الأحداث

تفرّع بحسب type واقرأ حقول الحالة التي تهمّك:

switch (event.type) {
  case "order.placed":
    // Reserve inventory, create a record in your system.
    break;
  case "order.paid":
    // Trigger fulfillment / accounting.
    break;
  case "order.fulfilled":
    // Notify the customer, close the fulfillment task.
    break;
  case "order.cancelled":
  case "order.returned":
  case "order.refunded":
    // Reverse inventory / issue store credit / update ledgers.
    break;
  case "order.updated":
    // Re-sync the order snapshot from event.data.object.
    break;
  default:
    // Unknown/future event type — acknowledge and ignore.
    break;
}

التوافق مع المستقبل

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

الغلاف​

أحداث الطلبات​

كائن الطلب​

مثال: order.paid​

مثال: order.fulfilled​

معالجة الأحداث​