API
API Docs

المقدمة

تُمكّنك واجهة Giftpack API من برمجة تدفقات الإهداء المعتمدة على العلاقات (relationship-driven gifting workflows) عبر الهدايا ومنتجات العلامة (swag) والمكافآت على نطاق عالمي.

بدلاً من بناء بوابة مكافآت منفصلة أو تنسيق المورّدين يدوياً، يمكنك orchestrate أحداث الإهداء (gifting events) مباشرةً من أنظمتك الحالية مثل CRM وHRIS ومنصات التشغيل الداخلية. تتيح الواجهة لتطبيقك تشغيل لحظات التفاعل وإدارتها ومراقبتها برمجياً، بينما تتولى Giftpack التنفيذ التشغيلي (fulfillment) والتوافر واللوجستيات والامتثال.

لا تتبع Giftpack بنية واجهات التجارة الإلكترونية التقليدية. فبدلاً من التركيز على كتالوج المنتجات وعمليات checkout، يقوم النظام بنمذجة الإهداء (gifting) كأحداث علاقة. يتم التعامل مع هوية المستلم والتوقيت وسياق العمل كمدخلات أساسية إلى جانب العنصر المُرسَل. وهذا يسمح للتكاملات بالارتباط طبيعياً مع المحفزات الواقعية مثل onboarding والذكرى السنوية وإغلاق الصفقات وحملات الاحتفاظ أو محطات تفاعل العملاء.

توفّر الواجهة رؤية كاملة لدورة الحياة عبر مراحل العملية، بما في ذلك حالة redemption وتقدم fulfillment وتتبع التسليم (delivery tracking). تُمكّن هذه endpoints أنظمتك من قياس النتائج وأتمتة إجراءات المتابعة ودمج الإهداء (gifting) ضمن تقارير التشغيل وسير العمل.

المفهوم الأساسي

على مستوى النظام، تتبع Giftpack نموذج دورة الحياة التالي:

Intent → Campaign → Recipient → Redemption → Fulfillment → Tracking

تمثل كل مرحلة انتقال حالة ضمن دورة حياة التفاعل:

  • يحدد Intent المحفّز التجاري أو الهدف.
  • تعمل Campaign كحاوية للتفاعل.
  • يمثّل Recipient هوية الجهة المشاركة في الحملة.
  • تسجل Redemption إجراء المستلم.
  • يدير Fulfillment عملية التنفيذ التشغيلي.
  • يوفّر Tracking الرؤية اللاحقة والتحليلات.

مخطط دورة الحياة

حدث أعمال
    │
    ▼
[ Intent ]
    │
    │  (API متزامن)
    ▼
[ Campaign Created ]
    │
    │  (API متزامن)
    ▼
[ Recipient Attached ]
    │
    │  (API متزامن)
    ▼
[ Redemption Link Issued ]
    │
    │  ────── إجراء المستخدم (غير متزامن) ──────
    ▼
[ Redemption Claimed ]
    │
    │  (Webhook: giftee.preparing)
    ▼
[ Shipment Processing ]
    │
    │  (Webhook: giftee.shipped)
    ▼
[ Tracking / Delivered ]
    │
    │  (Webhook: giftee.delivered / giftee.failed / giftee.returned)
    ▼
[ Final Tracking State ]
    │
    │  (Webhook: giftee.reviewed)
    ●

يبدأ النصف الأول من دورة الحياة بشكل متزامن عبر استدعاءات API. أما النصف الثاني فيتقدم بشكل غير متزامن عبر إجراءات المستلمين وأحداث التنفيذ التشغيلي (fulfillment events). يجب أن تعتمد التكاملات على حقول الحالة وأحداث webhook بدلاً من افتراض الاكتمال الفوري.

ينطبق هذا النموذج بشكل متسق على حملات الإهداء الذكي (smart gifting) ‏AutoMatch™، وطلبات السوق (marketplace orders)، وتدفقات منتجات العلامة (swag workflows)، وحالات أتمتة المؤسسات. فهم هذا النموذج ضروري لبناء تكاملات موثوقة، خاصةً في البيئات غير المتزامنة والمعتمدة على الأحداث.

التعريفات

تصف هذه التعريفات كائنات المجال الأساسية المستخدمة في تكاملات Giftpack API. فهم العلاقة بين هذه الكائنات ضروري قبل بناء سير العمل. تعمل Giftpack عبر ثلاث طبقات رئيسية:

  1. طبقة التفاعل (Engagement Layer)
  2. طبقة التجارة (Commerce Layer)
  3. طبقة الإمداد والعمليات (Supply & Operations Layer)
1. طبقة التفاعل (Engagement Layer)

تقوم هذه الطبقة بنمذجة دورة العلاقة بين المُرسل والمستلم. وهي قائمة على الأحداث (event-driven) وغالباً ما تكون غير متزامنة.

المستلم (Recipient)

شخص حقيقي (موظف أو عميل أو شريك) قد يتلقى هدية أو مكافأة. في منطق API، يمثل Recipient هوية دائمة داخل مساحة عمل Giftpack. يمكن أن يوجد Recipient بشكل مستقل عن الحملات وقد يشارك في عدة حملات بمرور الوقت.

مجموعة المستلمين (Recipient Group)

مجموعة منطقية من المستلمين تُستخدم للاستهداف والتعيين الجماعي. المجموعات هي بنى تنظيمية ولا تمثل معاملات.

الحملة (Campaign)

تمثل Campaign نية تفاعل واحدة.

وتحدد:

  • الهدف (مثل onboarding أو retention أو milestone)
  • نافذة redemption
  • تخصيص الميزانية
  • المستلمين المؤهلين

الحملة ليست طلباً. الحملة تعمل كحاوية دورة حياة تحدث داخلها أحداث redemption وfulfillment.

حالة المستلم داخل الحملة (Giftee)

يصبح Recipient عبارة عن Giftee عند ربطه بـ Campaign. ويمثل Giftee حالة المشاركة الخاصة بالحملة لذلك المستلم. وهذا الفرق مهم:

  • Recipient = هوية
  • Giftee = حالة مرتبطة بالحملة

قالب الحملة (Campaign Template)

يحدد طبقة العرض للحملة، بما في ذلك:

  • الرسائل
  • الهوية البصرية
  • محتوى البريد الإلكتروني

القوالب تؤثر على التواصل، لا على منطق fulfillment.

الاسترداد (Redemption)

يمثل Redemption إجراء المستلم للمطالبة بالهدية. وقد يحدث عبر:

  • رابط redemption
  • بريد redemption
  • تدفق gift card (اختياري)

ينقل Redemption الحالة من “invited” إلى “claimed”.

رابط URL فريد يسمح لـ Giftee بالمطالبة بهديته.

بريد الاسترداد (Redemption Email)

بريد إلكتروني يرسل رابط redemption باستخدام campaign template.

2. طبقة التجارة (Commerce Layer)

تتعامل هذه الطبقة مع العمليات المعاملاتية وما يتعلق بـ fulfillment. وقد تعمل بشكل مستقل عن سير عمل الحملات.

منتج المتجر (Marketplace Product)

عنصر ثابت ومُنتقى يختاره المُرسل مباشرة. غالباً ما يتم fulfilled مباشرة بعد إنشاء الطلب.

طلب المتجر (Marketplace Order)

معاملة شراء مباشرة لمستلم واحد أو أكثر. قد تتجاوز Marketplace Orders نمط redemption الخاص بالحملات وتنتقل مباشرة إلى fulfillment. Marketplace Order ≠ Campaign.

مستلم طلب المتجر (Marketplace Order Receiver)

مستلم مُعيّن كهدف fulfillment لطلب Marketplace.

منتج Swag

منتج قابل للتخصيص يُدار عبر نظام المخزون والمستودعات في Giftpack. وقد يتطلب:

  • procurement
  • تخصيص المخزون
  • fulfillment على دفعات

المنتج (Product)

كائن حاوية قابل للبيع داخل كتالوجات marketplace أو swag.

متغير المنتج (Product Variant)

تهيئة محددة قابلة للشراء من المنتج، مثل:

  • الحجم
  • اللون
  • الإعداد

تحدث المعاملات دائماً على مستوى Product Variant.

3. طبقة الإمداد والعمليات (Supply & Operations Layer)

تشغّل هذه الطبقة عمليات fulfillment وإدارة vendors. وغالباً ما تكون مجردة في معظم التكاملات، لكنها تظل مهمة لفهم انتقالات الحالة.

مكتب المشتريات (Procurement Office)

طبقة تشغيلية مسؤولة عن:

  • onboarding للموردين
  • sourcing للمخزون
  • مراقبة الجودة
  • حوكمة fulfillment

المزوّد (Provider)

Vendor يزوّد منتجات إلى منظومة Giftpack.

مزوّد مُدار (Managed Provider)

Provider يخضع لإشراف Procurement Office لضمان جودة الكتالوج وonboarding والتحكم التشغيلي.

رمز المزوّد (Provider Code)

معرّف فريد يُستخدم للإشارة إلى Provider في عمليات API.

نظرة العلاقات (Relationship Overview)

يبين الهيكل التالي كيفية ارتباط هذه الكيانات ببعضها:

Recipient
  └─ may belong to Recipient Group
  └─ becomes Giftee when attached to Campaign

Campaign (Engagement Container)
  ├─ defines Redemption rules
  ├─ manages Giftee states
  └─ may generate Fulfillment Orders

Commerce Layer
  ├─ Marketplace Order (direct transaction)
  └─ Swag Order (inventory-based transaction)

Redemption
  ├─ Link-based
  ├─ Email-based
  └─ Transitions state before fulfillment

المصادقة والأمان

يجب أن تكون جميع الطلبات إلى Giftpack Integration API مُصادَقًا عليها باستخدام API Key صالح.

المصادقة إلزامية لكل endpoint ويتم فرضها على حدود الـ workspace. أي طلب غير مصرح به أو مصادقة غير صحيحة يتم رفضه قبل تنفيذ منطق الأعمال.

مفاتيح API

يمكن لكل workspace في Giftpack إنشاء مفتاح API واحد أو أكثر من خلال لوحة Giftpack.

تُستخدم API Keys من أجل:

  • مصادقة طلبات API
  • تحديد الـ workspace المصدر
  • فرض التفويض على مستوى الموارد
  • تطبيق ضوابط الاستخدام وحدود المعدل

مفاتيح API هي workspace-scoped. ولا يمكنها الوصول إلى موارد خارج الـ workspace الأصلي.

لا يقوم Giftpack بمشاركة API Keys بين الـ workspaces.

إشعار أمني: مفاتيح API تمنح وصولًا إلى موارد على مستوى الـ workspace. تعامل معها كبيانات اعتماد سرية.

الحصول على API Key

لإنشاء API Key:

  1. سجّل الدخول إلى لوحة Giftpack
  2. انتقل إلى Integration Hub → API Keys
  3. أنشئ API Key جديدًا ضمن Giftpack Integration

يصبح مفتاح API فعالًا فور إنشائه. ويتم تسجيل أحداث إنشاء المفاتيح داخليًا لأغراض التدقيق والتتبع.

مهم: احتفظ بمفتاح API بأمان، ولا تعرضه في كود client-side أو في المستودعات العامة.

استخدام API Key

ضمّن API Key في header باسم X-API-KEY في كل طلب.

GET /v1/recipients HTTP/1.1
Host: developer.giftpack.ai
X-API-KEY: YOUR_API_KEY

الطلبات بدون API Key صالح ستُرجِع خطأ مصادقة. تتم المصادقة قبل معالجة الطلب وتقييم الموارد.

نموذج التفويض

يتم فرض التفويض على مستوى الـ workspace. يمكن لـ API Key الوصول فقط إلى:

  • Recipients
  • Campaigns
  • Marketplace Orders
  • Swag Orders
  • Credits
  • Providers
  • أي موارد أخرى ضمن نفس الـ workspace

الوصول بين workspaces محظور تمامًا. قرارات التفويض تُنفّذ على الخادم ولا يمكن تجاوزها عبر معاملات العميل.

إدارة دورة حياة المفاتيح

ينبغي للتكاملات المؤسسية تطبيق ضوابط مناسبة لدورة حياة المفاتيح.

ممارسات موصى بها:

  • استخدام API Keys منفصلة لبيئتي staging و production
  • تدوير API Keys بشكل دوري
  • إلغاء API Key فورًا عند الاشتباه بالاختراق
  • تجنب مشاركة API Keys بين الفرق أو الأنظمة

عند إلغاء API Key، سيتم رفض جميع الطلبات اللاحقة التي تستخدمه.

لا يقوم Giftpack بتدوير API Keys تلقائيًا. إدارة المفاتيح مسؤولية الجهة المتكاملة.

أمان النقل

يجب إرسال جميع طلبات API عبر HTTPS.

  • الحد الأدنى لإصدار TLS: TLS 1.2
  • طلبات HTTP غير المشفرة مرفوضة

يتم تشفير جميع البيانات أثناء النقل باستخدام TLS وفق معايير الصناعة.

يشمل ذلك:

  • بيانات Recipient
  • معلومات الشحن
  • بيانات تعريف الطلب
  • headers المصادقة

لا يدعم Giftpack اتصالات النقل غير الآمنة.

تحديد معدل الطلبات

تخضع طلبات API إلى rate limiting لضمان استقرار المنصة وعدالة الاستخدام. عند تجاوز الحد، تُرجع API:

  • حالة HTTP 429
  • رمز الخطأ RATE_LIMIT_EXCEEDED

يجب على التكاملات:

  • تنفيذ منطق إعادة المحاولة
  • استخدام استراتيجيات exponential backoff
  • تجنب polling العدواني

لأحمال العمل المؤسسية عالية الحجم أو الاندفاعية، تواصل مع Giftpack لمناقشة إعدادات المعدل.

خصوصية البيانات والتعامل مع PII

قد تعالج APIs الخاصة بـ Giftpack بيانات شخصية مُعرِّفة (PII)، بما في ذلك:

  • أسماء recipients
  • عناوين البريد الإلكتروني
  • عناوين الشحن

مسؤوليات المطور:

  • ضمان وجود أساس قانوني لمعالجة البيانات
  • الحصول على موافقة المستلم عند الحاجة
  • الامتثال للتشريعات ذات الصلة (مثل GDPR وCCPA)
  • تقليل تخزين البيانات غير الضرورية

يعالج Giftpack البيانات فقط لغرض تنفيذ workflows الخاصة بالهدايا والمكافآت. لا يستخدم Giftpack بيانات recipients للإعلانات أو أي profiling غير مرتبط.

اعتبارات السجلات والتدقيق

في البيئات المؤسسية، يجب أن تقوم التكاملات بـ:

  • تسجيل outbound API requests
  • تسجيل رموز الاستجابة وحالات الخطأ
  • مراقبة فشل المصادقة غير الطبيعي
  • مراقبة أحداث rate-limit غير المتوقعة

يحافظ Giftpack على سجلات داخلية لـ:

  • محاولات المصادقة
  • استخدام المفاتيح
  • الأحداث الأمنية ذات الصلة

استجابات أخطاء المصادقة

تتبع أخطاء المصادقة والتفويض بنية موحدة.

{
  "error_code": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "action": "Verify your API key and include it in the X-API-KEY header"
}

أشهر رموز أخطاء المصادقة:

  • UNAUTHORIZED
  • FORBIDDEN
  • RATE_LIMIT_EXCEEDED

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

في بيئات الإنتاج:

  • خزّن API Keys في متغيرات بيئة آمنة
  • لا تُظهر API Keys في تطبيقات frontend أو client-side
  • لا تقم بعمل commit لمفاتيح API في أنظمة التحكم بالإصدارات
  • قيّد الوصول الداخلي إلى مفاتيح الإنتاج
  • استخدم تكاملات server-to-server كلما أمكن

إذا اشتبهت في تعرّض API Key للاختراق:

  1. ألغِ المفتاح فورًا
  2. أنشئ مفتاحًا بديلًا
  3. راجع سجلات API الحديثة لاكتشاف أي استخدام غير طبيعي

معالجة الأخطاء وخريطة الحالات

تستخدم Giftpack API أكواد HTTP القياسية وتعيد payloads خطأ منظّمة.

تتضمن جميع استجابات الخطأ رمز خطأ قابلًا للقراءة آليًا بالإضافة إلى request_id. احرص دائمًا على تسجيل request_id عند التواصل مع فريق الدعم.

صيغة استجابة الخطأ

تتبع جميع الأخطاء البنية التالية:

{
  "error": {
    "code": "invalid_request",
    "message": "Recipient email is required.",
    "request_id": "req_123"
  }
}

الحقول

  • code – معرّف خطأ قابل للقراءة آليًا
  • message – شرح قابل للقراءة بشريًا
  • request_id – معرّف تتبع فريد لطلب التشخيص

يجب الاحتفاظ بـ request_id في السجلات لاستخدامه في التشخيص التشغيلي.

أكواد حالة HTTP

تستخدم Giftpack دلالات HTTP القياسية:

  • 200 / 201 – نجح الطلب
  • 400 – خطأ تحقق أو طلب غير صحيح
  • 401 – API Key مفقود أو غير صالح
  • 403 – صلاحيات غير كافية
  • 404 – المورد غير موجود
  • 409 – تعارض (مثل مورد مكرر أو انتهاك حالة)
  • 429 – تم تجاوز حد المعدل
  • 5xx – خطأ داخلي في الخادم

إرشادات إعادة المحاولة

ليست كل الأخطاء قابلة لإعادة المحاولة.

آمن لإعادة المحاولة

  • 429 (تجاوز حد المعدل)
  • 5xx (أخطاء الخادم)

استخدم exponential backoff عند إعادة المحاولة. تجنب إعادة المحاولة العنيفة والفورية.

لا تُعد المحاولة

  • 400 (أخطاء التحقق)
  • 401 / 403 (فشل المصادقة أو الصلاحيات)
  • 404 (مرجع مورد غير صالح)
  • 409 (تعارضات منطق الأعمال)

تشير هذه الحالات إلى مشاكل من جانب العميل يجب تصحيحها قبل إعادة الإرسال.

الحالة غير المتزامنة مقابل حالة HTTP

نجاح استجابة HTTP لا يعني اكتمال fulfillment.

على سبيل المثال:

  • 201 Created يؤكد إنشاء campaign
  • لا يؤكد اكتمال redemption
  • لا يؤكد اكتمال shipment
  • لا يؤكد اكتمال delivery

غالبًا ما تتقدم عمليات Giftpack بشكل غير متزامن.

لتحديد حالة lifecycle:

  • استعلم عن حالة المورد عبر endpoints GET
  • أو استمع إلى أحداث webhook

تعامل دائمًا مع نجاح HTTP على أنه قبول للطلب، وليس اكتمالًا للأعمال.

اعتبارات Idempotency

إذا كان التكامل لديك يعيد المحاولة، فتأكد من أن الطلبات المكررة لا تُحدث آثارًا جانبية غير مقصودة.

عند الحاجة:

  • استخدم external identifiers فريدة
  • خزّن request tracking IDs الخاصة بك
  • تجنب إعادة المحاولة العمياء لأخطاء 4xx

قد يرفض Giftpack إنشاء موارد مكررة حسب منطق الـ endpoint.

سلوك Rate Limiting

عند تجاوز حدود المعدل:

  • يتم إرجاع حالة HTTP 429
  • أعد المحاولة بعد تأخير

يجب على التكاملات:

  • تنفيذ exponential backoff
  • تجنب حلقات polling الضيقة
  • تفضيل تحديثات webhook على polling GET المتكرر

الدعم والتشخيص

إذا واجهت أخطاء غير متوقعة:

  • سجّل payload الخطأ كاملًا
  • سجّل request_id
  • قدّم request_id عند التواصل مع دعم Giftpack

يساعد ذلك على تتبع المشكلة بسرعة داخل سجلات الخادم.

Webhooks والأحداث غير المتزامنة

تدفقات Giftpack تعمل بشكل غير متزامن.

الاستجابة الناجحة من API تعني أن الطلب تم قبوله. تحديثات lifecycle مثل redemption وfulfillment وshipping وdelivery يتم إرسالها عبر أحداث webhook.

تكاملات الإنتاج يجب أن تعتبر webhooks آلية تحديث الحالة الأساسية. استخدم polling لنقاط الحالة فقط للمطابقة أو الاستعادة.

أنواع الأحداث المدعومة

تتم إدارة وعرض أنواع أحداث webhook مباشرة من لوحة Giftpack. لعرض أو إعداد المشغلات المتاحة:

https://giftpack.ai/app/developer/webhooks

واجهة اللوحة هي مصدر الحقيقة للأحداث المتاحة في الإنتاج.

أمثلة مدعومة حاليًا:

  • giftee.created
  • giftee.launched
  • giftee.preparing
  • giftee.shipped
  • giftee.delivered
  • giftee.failed
  • giftee.returned
  • giftee.reviewed

قد تتغير التغطية بمرور الوقت. ارجع دائمًا إلى اللوحة عند إعداد الإنتاج.

إعداد Webhook

يتم إعداد webhooks لكل workspace عبر اللوحة. كل إعداد يتضمن:

  • name
  • endpoint
  • event_types
  • مفتاح تفعيل active
  • secret key ضمن نطاق workspace

مثال إعداد:

{
  "name": "Giftpack Delivery Updates",
  "endpoint": "https://example.com/webhooks/giftpack",
  "event_types": [
    "giftee.created",
    "giftee.shipped",
    "giftee.delivered"
  ]
}

يمكن وجود عدة إعدادات webhook داخل نفس workspace.

نموذج التسليم

تسليم webhook يتبع نموذج at-least-once delivery.

وهذا يعني:

  • قد يتم تسليم نفس الحدث أكثر من مرة
  • ترتيب التسليم غير مضمون بشكل صارم
  • يجب أن تكون handlers لديك idempotent

يُعتبر التسليم ناجحًا عندما يُرجع endpoint لديك أي حالة HTTP من نوع 2xx.

الاستجابات غير 2xx تؤدي إلى محاولات إضافية.

عقد endpoint المستقبِل

يجب أن يقوم endpoint webhook لديك بـ:

  • قبول طلبات POST مع payload من نوع JSON
  • إرجاع حالة 2xx لتأكيد النجاح
  • الاستجابة ضمن timeout مناسب
  • التعامل الآمن مع الأحداث المكررة

مثال إقرار الاستلام:

HTTP/1.1 200 OK
Content-Type: application/json

{"ok": true}

استخدم webhook event ID كمفتاح deduplication.

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

يوفر Giftpack سجلًا كاملًا لأحداث webhook في اللوحة. كل حدث يحتوي على:

  • بيانات تعريف الحدث
  • payload الخام
  • حالة التسليم
  • عدد المحاولات
  • تشخيص request/response لكل محاولة

حالات السجل:

  • 0 – failed
  • 1 – processing
  • 2 – success

واجهة تفاصيل الحدث تعرض:

  • Webhook event (حدث منطقي)
  • Webhook event requests (محاولات تسليم فردية)

مثال كائن التفاصيل:

{
  "webhook_event_id": "wev_01H...",
  "webhook_setting_id": "whs_01H...",
  "webhook_event_type": "giftee.shipped",
  "webhook_event_resource_type": "giftee",
  "webhook_event_resource_id": "gft_01H...",
  "webhook_event_status": 2,
  "webhook_event_attempts": 1,
  "webhook_event_data": "{...raw payload...}",
  "webhook_event_created_at": "2026-02-20T02:00:00.000Z",
  "webhook_event_updated_at": "2026-02-20T02:00:01.000Z"
}

كل سجل محاولة يتضمن:

  • endpoint الهدف
  • حالة استجابة HTTP
  • response headers
  • response body
  • الطابع الزمني

هذا السجل يوفّر تتبعًا كاملًا ويسهّل تصحيح التكامل.

وحدة اختبار Webhook

يوفر Giftpack وحدة اختبار Webhook مدمجة داخل اللوحة. يمكنك:

  • اختيار endpoint
  • اختيار نوع الحدث
  • إرسال payload تجريبي
  • عرض الاستجابة الفعلية من endpoint

هذا يتيح:

  • تحقق end-to-end
  • فحص payload
  • تشخيص فوري للاستجابة

مثال استجابة اختبار:

{
  "event_data": {
    "type": "giftee.created",
    "resource_type": "giftee",
    "resource_id": "gft_01H..."
  },
  "response_http_status": "200",
  "response_http_headers": {"content-type": "application/json"},
  "response_http_body": "{\"ok\":true}"
}

وحدة الاختبار مخصصة للتطوير والتحقق قبل تفعيل الإنتاج.

متطلبات النقل

حتى لو كانت الواجهة الحالية تسمح بـ http و https، يجب على تكاملات الإنتاج استخدام HTTPS دائمًا.

استخدام HTTPS يضمن:

  • تشفير النقل
  • الحماية من الاعتراض
  • الامتثال لمتطلبات الأمان المؤسسية

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

لمعالجة webhook بشكل موثوق:

  • استخدم معالجة idempotent
  • سجّل جميع الأحداث الواردة
  • خزّن event IDs لإزالة التكرار
  • تجنب المعالجة المتزامنة الطويلة داخل handler
  • انقل الأعمال الثقيلة إلى background jobs
  • راقب محاولات التسليم الفاشلة

التكامل المعتمد على webhook هو المصدر المعتمد لتحديثات lifecycle. لا تفترض أن استجابات API المتزامنة تمثل الحالة النهائية.

التحقق من توقيع Webhook

لضمان أن أحداث webhook صادرة من Giftpack ولم يتم العبث بها، يتم توقيع كل طلب باستخدام secret خاص بكل workspace.

تكاملات الإنتاج يجب أن تتحقق من التوقيع.

صيغة ترويسة التوقيع

كل طلب webhook يتضمن الترويسة التالية:

X-GIFTPACK-SIGNATURE: t=1708459200,v1=abcdef1234567890...

المكوّنات

  • t — طابع زمني Unix (بالثواني)
  • v1 — توقيع HMAC SHA-256

يتم توليد التوقيع عبر:

HMAC_SHA256(secret, `${timestamp}.${raw_body}`)

يجب استخدام raw body كما تم استلامه تمامًا.

عملية التحقق

للتحقق من طلب webhook:

  1. استخرج ترويسة X-GIFTPACK-SIGNATURE
  2. حلّل t و v1
  3. احصل على raw body قبل JSON parsing
  4. احسب:
expected_signature = HMAC_SHA256(secret, `${timestamp}.${raw_body}`)
  1. قارن باستخدام timing-safe comparison
  2. ارفض الطلب إذا:
  • التوقيع غير متطابق
  • الطابع الزمني قديم جدًا (موصى به: أكثر من 5 دقائق)

الحماية من Replay Attacks

لمنع replay attacks:

  • تحقق من حداثة الطابع الزمني (±300 ثانية)
  • خزّن event IDs المعالجة وارفض التكرارات
  • لا تقبل payloads غير موقعة

مثال نافذة زمنية:

current_time - timestamp <= 300 seconds

مثال (Node.js)

const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, secret) {
  if (!signatureHeader) return false;

  const elements = signatureHeader.split(',');
  const timestamp = elements.find(e => e.startsWith('t='))?.split('=')[1];
  const signature = elements.find(e => e.startsWith('v1='))?.split('=')[1];

  if (!timestamp || !signature) return false;

  const payload = `${timestamp}.${rawBody}`;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  const isValid = crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );

  const currentTime = Math.floor(Date.now() / 1000);
  const tolerance = 300;

  if (Math.abs(currentTime - Number(timestamp)) > tolerance) {
    return false;
  }

  return isValid;
}

مثال Express:

app.post('/webhooks/giftpack',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-giftpack-signature'];
    const isValid = verifySignature(
      req.body.toString(),
      signature,
      process.env.GIFTPACK_WEBHOOK_SECRET
    );

    if (!isValid) {
      return res.status(400).send('Invalid signature');
    }

    const event = JSON.parse(req.body.toString());

    // Process event safely

    res.status(200).json({ ok: true });
});

إدارة الأسرار

Webhook secrets:

  • فريدة لكل إعداد webhook
  • يجب تخزينها بشكل آمن (متغيرات البيئة)
  • يجب عدم كشفها في كود client-side
  • يجب تدويرها عند الاشتباه بالاختراق

إذا تم تدوير secret، حدّث التكامل فورًا.

التعامل مع الفشل

إذا فشل التحقق:

  • أرجع حالة HTTP غير 2xx
  • لا تعالج payload
  • سجّل الفشل لمراقبة الأمان

تكرار فشل التوقيع قد يشير إلى:

  • عدم تطابق secret
  • endpoint مُعد بشكل خاطئ
  • حركة مرور خبيثة

تذكير بنموذج التسليم

تسليم webhook يتبع نموذج at-least-once. الأحداث المكررة واردة.

البناء حسب حالات الاستخدام

تم تصميم Giftpack API حول workflows أعمال حقيقية.

بدلاً من التنقل بين endpoints مباشرةً، اختر أولاً حالة العمل التي تريد تنفيذها. كل حالة أدناه توضح:

  • هدف العمل
  • تسلسل API
  • lifecycle المتوقع
  • أحداث webhook ذات الصلة

تفاصيل التحقق من توقيع webhook موثقة في قسم Webhooks والأحداث غير المتزامنة.

الحالة 1: حملة تقدير الموظفين (Smart Gifting)

سيناريو العمل

تريد أن:

  • تكرّم الموظفين
  • تعيّن ميزانيات
  • تتيح للمستلم اختيار هديته
  • تتبع redemption وfulfillment
  • تزامن الحالة النهائية مع HRIS أو CRM

هذا تدفق Giftee قائم على Campaign.

نظرة lifecycle

Create Campaign
      ↓
Add Giftee
      ↓
Generate Redemption Link
      ↓
Recipient Claims
      ↓
Order Processing
      ↓
Shipped
      ↓
Delivered / Failed / Returned

1. إنشاء Campaign

POST /v1/campaigns

يحدد:

  • الميزانية
  • المدة
  • منطق الاستهداف
  • نافذة redemption

2. إضافة Giftees

POST /v1/giftees

كل giftee يمثل مستلمًا واحدًا داخل الحملة.

3. إنشاء Redemption Link

POST /v1/campaigns/{campaignId}/giftees/{gifteeId}/redeemlink

يرجع:

  • share_claim_link

يمكنك:

  • الإرسال عبر Giftpack
  • الإرسال عبر نظام البريد الداخلي

أحداث Webhook ذات الصلة

لهذه الحالة، اشترك في lifecycle الخاص بـ giftee:

giftee.created
giftee.launched
giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned
giftee.reviewed

تمثل هذه الأحداث الحالة التشغيلية لكل giftee. راجع قسم Webhooks والأحداث غير المتزامنة لمعرفة:

  • بنية payload
  • التحقق من التوقيع
  • سلوك إعادة المحاولة
  • سجلات التسليم
  • وحدة الاختبار
الحالة 2: شراء Marketplace مباشر (بدون Redemption)

سيناريو العمل

تريد أن:

  • ترسل منتجًا ثابتًا
  • تتجاوز تدفق اختيار المستلم
  • تبدأ الشحن فور إنشاء الطلب
  • تتبع حالة fulfillment
  • تزامن تأكيد التسليم مع CRM أو نظام العمليات

هذا تدفق Direct Marketplace Order.

نظرة lifecycle

Select Product
      ↓
Create Marketplace Order
      ↓
Preparing
      ↓
Shipped
      ↓
Delivered / Failed / Returned

1. جلب المنتج

GET /v1/providers/{providerCode}/products

استخدم هذا endpoint لتصفح المنتجات المتاحة. ثم جلب التفاصيل عند الحاجة:

GET /v1/providers/{providerCode}/products/{productId}

اختر:

  • product_id
  • product_variant_id

2. إنشاء Marketplace Order

POST /v1/marketplaceorders

قدّم:

  • product_id
  • product_variant_id
  • member_id
  • quantity
  • shipping information عند الحاجة

يُقبل الطلب بشكل غير متزامن وتبدأ عملية fulfillment.

أحداث Webhook ذات الصلة

fulfillment في marketplace ينتهي إلى أحداث lifecycle الخاصة بـ giftee:

giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned

راجع قسم Webhooks والأحداث غير المتزامنة لمعرفة:

  • بنية payload
  • التحقق من التوقيع
  • سلوك إعادة المحاولة
  • سجلات التسليم
  • وحدة الاختبار
الحالة 3: تدفق تخصيص النقاط والاسترداد

سيناريو العمل

تريد أن:

  • تخصص نقاط مكافآت للمستلمين
  • تتيح لهم الاسترداد لاحقًا
  • تتبع الرصيد والاستخدام
  • تحول التفاعل إلى أحداث fulfillment

هذا تدفق gifting قائم على النقاط.

نظرة lifecycle

Enable Points
      ↓
Allocate Points
      ↓
Recipient Redeems
      ↓
Giftee Created
      ↓
Fulfillment Lifecycle

1. تفعيل ميزة النقاط للمستلم

POST /v1/pointrecipients/{memberId}/enablepointfeature

يتيح هذا للمستلم الاحتفاظ بالنقاط واستردادها.

2. تخصيص النقاط

PATCH /v1/pointrecipients/{memberId}/points

قدّم:

  • points
  • allocation metadata عند الحاجة

يتم تحديث الرصيد فورًا.

3. الاسترداد يطلق lifecycle لـ Giftee

عند استرداد المستلم للنقاط:

  • يتم إنشاء سجل giftee
  • يبدأ fulfillment
  • يتقدم lifecycle بشكل طبيعي

أحداث Webhook ذات الصلة

استرداد النقاط ينتهي إلى أحداث lifecycle الخاصة بـ giftee:

giftee.created
giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned

راجع قسم Webhooks والأحداث غير المتزامنة لمعرفة:

  • بنية payload
  • التحقق من التوقيع
  • سلوك إعادة المحاولة
  • سجلات التسليم
  • وحدة الاختبار