ابدأ من هنا

تتيح واجهات Giftpack البرمجية لنظامك الخلفي إنشاء وتشغيل مسارات عمل المكافآت والحوافز والمنتجات الترويجية وخيارات المستلمين. تتولى Giftpack إدارة توفر الكتالوج وتجارب المستلمين والتنفيذ وتحديثات التسليم، بينما يظل نظامك مسؤولًا عن محفزات الأعمال وبيانات العملاء.

عنوان URL الأساسي لبيئة الإنتاج هو:

https://developer.giftpack.ai

استخدم مرجع API للاطلاع على مخططات الطلبات والاستجابات كاملة. واستخدم هذا الدليل لاختيار مجموعة الموارد المناسبة وفهم كيفية انتقال الموارد بين مراحلها بعد إنشائها.

اختيار مسار العمل

نموذج الموارد

يستخدم Smart Gifting الحملة بوصفها حاوية البرنامج، ويستخدم giftee لتمثيل دورة الحياة الخاصة بكل مستلم:

Campaign -> Giftee -> Redemption -> Fulfillment -> Delivery

تستخدم طلبات الكتالوج المباشرة Marketplace Order بوصفه حاوية الطلب، وMarketplace Order Receiver لتمثيل دورة الحياة الخاصة بكل مستلم:

Marketplace Order -> Receiver -> Claim or Selection -> Fulfillment -> Delivery

لا تتعامل مع giftee وmarketplace_order_receiver على أنهما مورد واحد قابل للتبادل. فأسماء أحداثهما تحدد مجموعتين مختلفتين من الطلبات، حتى عندما تبدو حالات التنفيذ متشابهة.

دورة حياة الطلب

تعيد طلبات الإنشاء والتحديث الحالة الراهنة للمورد. وتستمر إجراءات المستلم والتنفيذ والشحن والتسليم بصورة غير متزامنة.

لبناء تكامل موثوق:

• احفظ معرّف المورد المُعاد.
• اشترك في مجموعة أحداث Webhook المطابقة.
• تعامل مع id الخاص بحدث Webhook بوصفه مفتاح إزالة التكرار.
• تحقق من اتساق الحالة عبر نقطة نهاية GET عندما يرصد نظامك حدثًا مفقودًا أو متأخرًا.
• لا تعِد تلقائيًا طلبًا يغيّر الحالة إلا إذا وثقت عملية API الخاصة به صراحةً عقدًا للتكرار الآمن.

الطلب الأول

بعد إنشاء مفتاح API في Giftpack، تحقق من إمكانية الوصول باستخدام كتالوج أحداث Webhook:

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

تسرد الاستجابة أنواع أحداث Webhook التي تدعمها API حاليًا. تمثل نقطة النهاية هذه كتالوج الأحداث المرجعي، وليس قائمة ثابتة مضمنة في العميل.

الخطوات التالية

1. اقرأ المصادقة والأمان قبل تخزين مفتاح API أو استخدامه.
2. اختر مسار عمل من وصفات التنفيذ.
3. اضبط Webhooks وتحقق منها قبل إطلاق تكامل في بيئة الإنتاج.
4. استخدم مرجع API لمعرفة الحقول المطلوبة ونماذج الاستجابة الخاصة بكل نقطة نهاية.

التعريفات

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

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

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 الأساسية ضمن /v1 مفتاح API مرتبطًا بمساحة العمل في الترويسة X-API-KEY. يجب ألا تستخدم مفاتيح API إلا تطبيقات موثوقة تعمل على جانب الخادم.

متطلبات الوصول

تتوفر إدارة مفاتيح API من إعدادات المطور. يجب أن تتمتع مساحة العمل والمستخدم الحالي بإمكانية الوصول إلى ميزة Giftpack Open API وبأذونات إعدادات المطور المطلوبة.

إذا لم تكن صفحة Developer متاحة، فاطلب من مسؤول مساحة العمل التحقق من خطة مساحة العمل ودورك قبل البدء ببناء التكامل.

إنشاء مفتاح وتخزينه

1. سجّل الدخول إلى Giftpack.
2. افتح إعدادات المطور.
3. أنشئ مفتاح API للبيئة المقصودة.
4. خزّن المفتاح في مدير أسرار على جانب الخادم.

لا تضع مفتاح API مطلقًا في JavaScript يعمل في المتصفح، أو تطبيق جوال، أو السجلات، أو لقطات الشاشة، أو تذاكر الدعم، أو نظام التحكم في المصدر.

استخدم بيانات اعتماد منفصلة لبيئتي الاختبار المرحلي والإنتاج. ألغِ المفتاح فورًا إذا كان من المحتمل أن يكون قد انكشف.

مصادقة طلب

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

يحدد مفتاح API مساحة العمل. ويُفرض التفويض على الموارد من جانب الخادم، لذلك لا يمنح معرّف مأخوذ من مساحة عمل أخرى حق الوصول إلى ذلك المورد.

البيئة والنقل

• أرسل طلبات الإنتاج إلى https://developer.giftpack.ai.
• استخدم HTTPS لكل طلب.
• احتفظ ببيانات الاعتماد في مخزن أسرار مخصص لكل بيئة.
• لا تعِد استخدام مفتاح الإنتاج في بيئة التطوير المحلية.

تستخدم بعض عمليات الموصلات في مرجع API رموز Bearer أو آليات مصادقة خاصة بمزوّد الخدمة. اتبع مخطط الأمان الموضح لكل عملية؛ ولا تفترض أن مفتاح Giftpack API يمكنه استدعاء نقطة نهاية خاصة بموصل.

الممارسات التشغيلية

• دوّر بيانات الاعتماد وفق سياسة الأمان في مؤسستك.
• اقصر الوصول إلى المفتاح على الخدمة التي تحتاج إليه.
• احجب X-API-KEY من سجلات الطلبات والأخطاء.
• سجّل العملية ومعرّف المورد وحالة HTTP والطابع الزمني لأغراض تشخيص الدعم.
• تحقق من توقيعات Webhook بصورة مستقلة عن مصادقة طلبات API.

لا يضمن العقد العام حدًا موحدًا لمعدل الطلبات أو سياسة واحدة لإعادة المحاولة لجميع العمليات. استخدم الترويسات الخاصة بكل نقطة نهاية ومرجع API عندما تكون متاحة، وتواصل مع Giftpack قبل التخطيط لدفعات طلبات كبيرة الحجم.

الأخطاء والاسترداد

تستخدم عمليات Giftpack رموز حالة HTTP القياسية. وتستخدم استجابات الأخطاء الموثقة في مرجع API نوع المحتوى application/problem+json.

استجابة المشكلة

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Property email is required but is missing.",
  "instance": "https://developer.giftpack.ai/errors/example",
  "errors": [
    {
      "location": "body.email",
      "message": "The email field is required.",
      "value": null
    }
  ]
}

الحقول

• type: عنوان URI يحدد نوع المشكلة. وقد تكون قيمته about:blank.
• title: ملخص ثابت للمشكلة ومقروء للبشر.
• status: حالة HTTP المرتبطة بهذه الاستجابة.
• detail: شرح لهذا الإخفاق تحديدًا.
• instance: عنوان URI يحدد واقعة المشكلة، عند توفيره.
• errors: تفاصيل اختيارية على مستوى الحقول، وتتضمن location وmessage وvalue.

ليس مضمونًا وجود كل حقل في كل خطأ. اكتب محللات تتحمل غياب الحقول الاختيارية وظهور حقول غير معروفة مستقبلًا.

الاسترداد حسب الحالة

مرجع API هو المصدر المعتمد للاستجابات الموثقة لكل عملية.

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

يمكن عادةً إعادة طلبات GET باستخدام تراجع أُسّي محدود. أما الطلبات التي تغيّر الحالة فتتطلب عناية أكبر:

• لا تعِد طلبات POST أو PATCH بصورة عمياء بعد انتهاء المهلة.
• تحقق أولًا مما إذا كانت العملية توثق التكرار الآمن أو تعيد موردًا يمكن التحقق من حالته.
• احفظ المعرّفات المُعادة في تخزين دائم قبل بدء الخطوة التالية.
• استخدم حقول المراجع التجارية الخاصة بك عندما تدعمها نقطة النهاية.
• امنع عمليات المعالجة المتزامنة من إرسال العملية المنطقية نفسها.

يعني انتهاء مهلة النقل أن العميل لم يتلق استجابة؛ ولا يثبت أن الخادم لم يكمل الطلب.

بيانات تشخيص الدعم

عند تصعيد مشكلة، قدّم نقطة النهاية والطريقة والطابع الزمني بتوقيت UTC وحالة HTTP ومعرّفات الموارد ذات الصلة واستجابة المشكلة بعد حجب البيانات الحساسة. لا تضمّن أبدًا مفتاح API أو بيانات مستلمين لم تُحجب منها المعلومات الحساسة.

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

تبلّغ Webhooks عن انتقالات المستلمين والتنفيذ التي تحدث بعد أن يعيد طلب API استجابته. استخدمها بوصفها الإشارة الأساسية لدورة الحياة، واستخدم عمليات GET لتسوية الحالة.

كتالوج الأحداث

استرجع الكتالوج الحالي بدلًا من تضمين قائمة قديمة وثابتة في الكود:

curl https://developer.giftpack.ai/v1/webhookeventtypes \
  --header 'Accept: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY'

يحتوي الكتالوج الحالي على مجموعتين من الموارد.

giftee

أحداث دورة حياة المستلم لطلبات Smart Gifting، بما فيها الحملات التي تبدأ عبر عمليات التكامل والبرامج المجدولة ومسارات عمل المكافآت المؤتمتة.

• giftee.created
• giftee.launched
• giftee.preparing
• giftee.shipped
• giftee.delivered
• giftee.failed
• giftee.returned
• giftee.reviewed
• giftee.cancel
• giftee.resume
• giftee.delete

marketplace_order_receiver

أحداث دورة حياة المستلم للطلبات المقدمة مباشرةً عبر Gift Mall أو Merchandise Catalog، خارج مسارات عمل حملات Smart Gifting.

• marketplace_order_receiver.created
• marketplace_order_receiver.launched
• marketplace_order_receiver.shipped
• marketplace_order_receiver.delivered
• marketplace_order_receiver.failed
• marketplace_order_receiver.returned
• marketplace_order_receiver.reviewed
• marketplace_order_receiver.delete

عقد الحمولة

كل عملية تسليم هي كائن JSON. تمثل data لقطة منظّمة للمورد، وليست سلسلة JSON مُفلتة.

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "type": "giftee.shipped",
  "data": {
    "id": "23e4567-e89b-12d3-a456-426655440000",
    "type": "giftee",
    "email": "recipient@example.com",
    "status": 12,
    "delivery_status": 2,
    "budget": 100,
    "campaign": {
      "id": "323e4567-e89b-12d3-a456-426655440000"
    },
    "recipient": {
      "id": "423e4567-e89b-12d3-a456-426655440000"
    },
    "delivery_tracking_code": "TRACKING-CODE"
  },
  "created_at": "2026-09-01 15:23:33"
}

• id هو المعرّف الدائم لواقعة الحدث، وينبغي استخدامه مفتاحًا لإزالة التكرار.
• يحدد type مجموعة الموارد والانتقال.
• تلتقط data حالة المورد عند وقوع الحدث. وتختلف الحقول باختلاف مجموعة الموارد ومرحلة دورة الحياة.
• يمثل created_at وقت وقوع الحدث. وقد تصل عمليات التسليم بترتيب مختلف، لذا استخدم هذه القيمة عند ترتيب الانتقالات.
• تحتفظ أحداث الحذف بآخر لقطة مخزنة بعد إزالة المورد النشط.

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

ترسل Giftpack ملخص HMAC-SHA256 السداسي العشري المكتوب بأحرف صغيرة لجسم الطلب الخام في X-Giftpack-Signature.

const crypto = require('crypto');

function verifyGiftpackWebhook(rawBody, signature, secret) {
  if (!signature) return false;

  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const actualBuffer = Buffer.from(signature, 'utf8');
  const expectedBuffer = Buffer.from(expected, 'utf8');

  return (
    actualBuffer.length === expectedBuffer.length &&
    crypto.timingSafeEqual(actualBuffer, expectedBuffer)
  );
}

تحقق من التوقيع قبل تحليل الحمولة أو معالجتها. وخزّن أسرار Webhook في مخزن أسرار على جانب الخادم.

سلوك التسليم وإعادة المحاولة

• ترسل Giftpack طلب HTTP من نوع POST يتضمن جسم JSON.
• تُعد أي استجابة 2xx عملية التسليم ناجحة.
• يمكن أن يظل الطلب مفتوحًا لمدة تصل إلى 60 ثانية.
• تُعاد محاولات التسليم الفاشلة بعد نحو 1 و5 و15 دقيقة، بحد أقصى أربع محاولات تسليم تشمل الطلب الأول.
• قد يتكرر التسليم. عالج id بطريقة آمنة من التكرار.
• ترتيب التسليم غير مضمون.

أعِد استجابة 2xx بسرعة بعد التحقق من الحدث وقبوله في تخزين دائم. وانقل العمل المكلف إلى قائمة انتظار.

حالة سجل الأحداث

تستخدم سجلات أحداث وطلبات Webhook الحالات الرقمية التالية:

• -1: فشل
• 0: قيد المعالجة
• 1: نجاح

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

قائمة تحقق لبيئة الإنتاج

• اشترك فقط في مجموعات الأحداث التي ينشئها مسار عملك.
• تحقق من X-Giftpack-Signature مقابل الجسم الخام غير المعدّل.
• أزل التكرار باستخدام id الخاص بالحدث.
• خزّن created_at واسمح بوصول الأحداث بترتيب مختلف.
• لا تعِد 2xx إلا بعد قبول الحدث بأمان.
• راقب الأحداث التي تصل إلى حالة الفشل.
• استخدم إجراء الاختبار في لوحة المعلومات قبل تفعيل نقطة نهاية للإنتاج.

وصفات التنفيذ

اختر مجموعة الموارد التي تتوافق مع طريقة تلقي المستلم للمكافأة. يظل مرجع API المصدر المعتمد لكل حقل مطلوب ونموذج استجابة.

curl https://developer.giftpack.ai/v1/marketplaceorders \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "marketplace_order_name": "September employee rewards",
    "marketplace_order_start_date": "2026-09-01",
    "marketplace_order_end_date": "2026-09-30",
    "marketplace_order_type": "Normal",
    "submit": false,
    "receivers": [
      {
        "member_id": "9a1232aa-238f-421c-82e7-45693d1b25b4",
        "country": "US",
        "gift_message": "Thank you for your contribution.",
        "email_notification": true,
        "sms_notification": false,
        "marketplace_feature": false,
        "donation_feature": false,
        "products": [
          {
            "marketplace_product_id": "961be65a-88d8-4040-8808-843ccf5da624",
            "marketplace_product_variant_id": "961be65a-a96a-412d-b22a-325f07d85647",
            "product_quantity": 1
          }
        ]
      }
    ]
  }'

curl https://developer.giftpack.ai/v1/pointrecipients/MEMBER_ID/points \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "credits": 1,
    "points": 100,
    "expired_at": "2027-09-01",
    "notes": "Annual recognition allocation"
  }'

قبل الانتقال إلى الإنتاج

• تحقق من الحقول المطلوبة بالرجوع إلى مرجع API الحالي.
• اختبر باستخدام مستلمين وبيانات اعتماد غير مخصصة للإنتاج.
• احفظ معرّف كل مورد مُعاد في تخزين دائم.
• اضبط مجموعة Webhook المطابقة.
• تحقق من التوقيعات وأزل الأحداث المكررة.
• حدد كيف يتحقق نظامك من نتيجة العمليات المنتهية مهلتها قبل إعادة طلب يغيّر الحالة.