تُمكّنك واجهة 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 عبر ثلاث طبقات رئيسية:
طبقة التفاعل (Engagement Layer)طبقة التجارة (Commerce Layer)طبقة الإمداد والعمليات (Supply & Operations Layer)تقوم هذه الطبقة بنمذجة دورة العلاقة بين المُرسل والمستلم. وهي قائمة على الأحداث (event-driven) وغالباً ما تكون غير متزامنة.
شخص حقيقي (موظف أو عميل أو شريك) قد يتلقى هدية أو مكافأة. في منطق API، يمثل Recipient هوية دائمة داخل مساحة عمل Giftpack. يمكن أن يوجد Recipient بشكل مستقل عن الحملات وقد يشارك في عدة حملات بمرور الوقت.
مجموعة منطقية من المستلمين تُستخدم للاستهداف والتعيين الجماعي. المجموعات هي بنى تنظيمية ولا تمثل معاملات.
تمثل Campaign نية تفاعل واحدة.
وتحدد:
الحملة ليست طلباً. الحملة تعمل كحاوية دورة حياة تحدث داخلها أحداث redemption وfulfillment.
يصبح Recipient عبارة عن Giftee عند ربطه بـ Campaign. ويمثل Giftee حالة المشاركة الخاصة بالحملة لذلك المستلم. وهذا الفرق مهم:
Recipient = هويةGiftee = حالة مرتبطة بالحملةيحدد طبقة العرض للحملة، بما في ذلك:
القوالب تؤثر على التواصل، لا على منطق fulfillment.
يمثل Redemption إجراء المستلم للمطالبة بالهدية. وقد يحدث عبر:
ينقل Redemption الحالة من “invited” إلى “claimed”.
رابط URL فريد يسمح لـ Giftee بالمطالبة بهديته.
بريد إلكتروني يرسل رابط redemption باستخدام campaign template.
تتعامل هذه الطبقة مع العمليات المعاملاتية وما يتعلق بـ fulfillment. وقد تعمل بشكل مستقل عن سير عمل الحملات.
عنصر ثابت ومُنتقى يختاره المُرسل مباشرة. غالباً ما يتم fulfilled مباشرة بعد إنشاء الطلب.
معاملة شراء مباشرة لمستلم واحد أو أكثر. قد تتجاوز Marketplace Orders نمط redemption الخاص بالحملات وتنتقل مباشرة إلى fulfillment. Marketplace Order ≠ Campaign.
مستلم مُعيّن كهدف fulfillment لطلب Marketplace.
منتج قابل للتخصيص يُدار عبر نظام المخزون والمستودعات في Giftpack. وقد يتطلب:
كائن حاوية قابل للبيع داخل كتالوجات marketplace أو swag.
تهيئة محددة قابلة للشراء من المنتج، مثل:
تحدث المعاملات دائماً على مستوى Product Variant.
تشغّل هذه الطبقة عمليات fulfillment وإدارة vendors. وغالباً ما تكون مجردة في معظم التكاملات، لكنها تظل مهمة لفهم انتقالات الحالة.
طبقة تشغيلية مسؤولة عن:
Vendor يزوّد منتجات إلى منظومة Giftpack.
Provider يخضع لإشراف Procurement Office لضمان جودة الكتالوج وonboarding والتحكم التشغيلي.
معرّف فريد يُستخدم للإشارة إلى Provider في عمليات API.
يبين الهيكل التالي كيفية ارتباط هذه الكيانات ببعضها:
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. أي طلب غير مصرح به أو مصادقة غير صحيحة يتم رفضه قبل تنفيذ منطق الأعمال.
يمكن لكل workspace في Giftpack إنشاء مفتاح API واحد أو أكثر من خلال لوحة Giftpack.
تُستخدم API Keys من أجل:
مفاتيح API هي workspace-scoped.
ولا يمكنها الوصول إلى موارد خارج الـ workspace الأصلي.
لا يقوم Giftpack بمشاركة API Keys بين الـ workspaces.
إشعار أمني: مفاتيح API تمنح وصولًا إلى موارد على مستوى الـ workspace. تعامل معها كبيانات اعتماد سرية.
لإنشاء API Key:
يصبح مفتاح API فعالًا فور إنشائه. ويتم تسجيل أحداث إنشاء المفاتيح داخليًا لأغراض التدقيق والتتبع.
مهم: احتفظ بمفتاح API بأمان، ولا تعرضه في كود client-side أو في المستودعات العامة.
ضمّن 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 الوصول فقط إلى:
الوصول بين workspaces محظور تمامًا. قرارات التفويض تُنفّذ على الخادم ولا يمكن تجاوزها عبر معاملات العميل.
ينبغي للتكاملات المؤسسية تطبيق ضوابط مناسبة لدورة حياة المفاتيح.
ممارسات موصى بها:
عند إلغاء API Key، سيتم رفض جميع الطلبات اللاحقة التي تستخدمه.
لا يقوم Giftpack بتدوير API Keys تلقائيًا. إدارة المفاتيح مسؤولية الجهة المتكاملة.
يجب إرسال جميع طلبات API عبر HTTPS.
TLS 1.2يتم تشفير جميع البيانات أثناء النقل باستخدام TLS وفق معايير الصناعة.
يشمل ذلك:
لا يدعم Giftpack اتصالات النقل غير الآمنة.
تخضع طلبات API إلى rate limiting لضمان استقرار المنصة وعدالة الاستخدام. عند تجاوز الحد، تُرجع API:
429RATE_LIMIT_EXCEEDEDيجب على التكاملات:
لأحمال العمل المؤسسية عالية الحجم أو الاندفاعية، تواصل مع Giftpack لمناقشة إعدادات المعدل.
قد تعالج APIs الخاصة بـ Giftpack بيانات شخصية مُعرِّفة (PII)، بما في ذلك:
مسؤوليات المطور:
يعالج Giftpack البيانات فقط لغرض تنفيذ workflows الخاصة بالهدايا والمكافآت. لا يستخدم Giftpack بيانات recipients للإعلانات أو أي profiling غير مرتبط.
في البيئات المؤسسية، يجب أن تقوم التكاملات بـ:
يحافظ Giftpack على سجلات داخلية لـ:
تتبع أخطاء المصادقة والتفويض بنية موحدة.
{
"error_code": "UNAUTHORIZED",
"message": "Invalid or missing API key",
"action": "Verify your API key and include it in the X-API-KEY header"
}
أشهر رموز أخطاء المصادقة:
UNAUTHORIZEDFORBIDDENRATE_LIMIT_EXCEEDEDفي بيئات الإنتاج:
إذا اشتبهت في تعرّض API Key للاختراق:

تستخدم 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 في السجلات لاستخدامه في التشخيص التشغيلي.
تستخدم Giftpack دلالات HTTP القياسية:
200 / 201 – نجح الطلب400 – خطأ تحقق أو طلب غير صحيح401 – API Key مفقود أو غير صالح403 – صلاحيات غير كافية404 – المورد غير موجود409 – تعارض (مثل مورد مكرر أو انتهاك حالة)429 – تم تجاوز حد المعدل5xx – خطأ داخلي في الخادمليست كل الأخطاء قابلة لإعادة المحاولة.
آمن لإعادة المحاولة
429 (تجاوز حد المعدل)5xx (أخطاء الخادم)استخدم exponential backoff عند إعادة المحاولة. تجنب إعادة المحاولة العنيفة والفورية.
لا تُعد المحاولة
400 (أخطاء التحقق)401 / 403 (فشل المصادقة أو الصلاحيات)404 (مرجع مورد غير صالح)409 (تعارضات منطق الأعمال)تشير هذه الحالات إلى مشاكل من جانب العميل يجب تصحيحها قبل إعادة الإرسال.
نجاح استجابة HTTP لا يعني اكتمال fulfillment.
على سبيل المثال:
201 Created يؤكد إنشاء campaignغالبًا ما تتقدم عمليات Giftpack بشكل غير متزامن.
لتحديد حالة lifecycle:
GETتعامل دائمًا مع نجاح HTTP على أنه قبول للطلب، وليس اكتمالًا للأعمال.
إذا كان التكامل لديك يعيد المحاولة، فتأكد من أن الطلبات المكررة لا تُحدث آثارًا جانبية غير مقصودة.
عند الحاجة:
قد يرفض Giftpack إنشاء موارد مكررة حسب منطق الـ endpoint.
عند تجاوز حدود المعدل:
429يجب على التكاملات:
إذا واجهت أخطاء غير متوقعة:
request_idrequest_id عند التواصل مع دعم Giftpackيساعد ذلك على تتبع المشكلة بسرعة داخل سجلات الخادم.

تدفقات Giftpack تعمل بشكل غير متزامن.
الاستجابة الناجحة من API تعني أن الطلب تم قبوله. تحديثات lifecycle مثل redemption وfulfillment وshipping وdelivery يتم إرسالها عبر أحداث webhook.
تكاملات الإنتاج يجب أن تعتبر webhooks آلية تحديث الحالة الأساسية. استخدم polling لنقاط الحالة فقط للمطابقة أو الاستعادة.
تتم إدارة وعرض أنواع أحداث webhook مباشرة من لوحة Giftpack. لعرض أو إعداد المشغلات المتاحة:
https://giftpack.ai/app/developer/webhooks
واجهة اللوحة هي مصدر الحقيقة للأحداث المتاحة في الإنتاج.
أمثلة مدعومة حاليًا:
giftee.createdgiftee.launchedgiftee.preparinggiftee.shippedgiftee.deliveredgiftee.failedgiftee.returnedgiftee.reviewedقد تتغير التغطية بمرور الوقت. ارجع دائمًا إلى اللوحة عند إعداد الإنتاج.
يتم إعداد webhooks لكل workspace عبر اللوحة. كل إعداد يتضمن:
nameendpointevent_typesactivesecret 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.
وهذا يعني:
يُعتبر التسليم ناجحًا عندما يُرجع endpoint لديك أي حالة HTTP من نوع 2xx.
الاستجابات غير 2xx تؤدي إلى محاولات إضافية.
يجب أن يقوم endpoint webhook لديك بـ:
POST مع payload من نوع JSON2xx لتأكيد النجاحمثال إقرار الاستلام:
HTTP/1.1 200 OK
Content-Type: application/json
{"ok": true}
استخدم webhook event ID كمفتاح deduplication.
يوفر Giftpack سجلًا كاملًا لأحداث webhook في اللوحة. كل حدث يحتوي على:
حالات السجل:
0 – failed1 – processing2 – successواجهة تفاصيل الحدث تعرض:
مثال كائن التفاصيل:
{
"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"
}
كل سجل محاولة يتضمن:
هذا السجل يوفّر تتبعًا كاملًا ويسهّل تصحيح التكامل.
يوفر Giftpack وحدة اختبار Webhook مدمجة داخل اللوحة. يمكنك:
هذا يتيح:
مثال استجابة اختبار:
{
"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 بشكل موثوق:
التكامل المعتمد على webhook هو المصدر المعتمد لتحديثات lifecycle. لا تفترض أن استجابات API المتزامنة تمثل الحالة النهائية.
لضمان أن أحداث 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:
X-GIFTPACK-SIGNATUREt و v1expected_signature = HMAC_SHA256(secret, `${timestamp}.${raw_body}`)
لمنع replay attacks:
مثال نافذة زمنية:
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:
إذا تم تدوير secret، حدّث التكامل فورًا.
إذا فشل التحقق:
2xxتكرار فشل التوقيع قد يشير إلى:
تسليم webhook يتبع نموذج at-least-once. الأحداث المكررة واردة.

تم تصميم Giftpack API حول workflows أعمال حقيقية.
بدلاً من التنقل بين endpoints مباشرةً، اختر أولاً حالة العمل التي تريد تنفيذها. كل حالة أدناه توضح:
تفاصيل التحقق من توقيع webhook موثقة في قسم Webhooks والأحداث غير المتزامنة.
سيناريو العمل
تريد أن:
هذا تدفق Giftee قائم على Campaign.
نظرة lifecycle
Create Campaign
↓
Add Giftee
↓
Generate Redemption Link
↓
Recipient Claims
↓
Order Processing
↓
Shipped
↓
Delivered / Failed / Returned
POST /v1/campaigns
يحدد:
POST /v1/giftees
كل giftee يمثل مستلمًا واحدًا داخل الحملة.
POST /v1/campaigns/{campaignId}/giftees/{gifteeId}/redeemlink
يرجع:
share_claim_linkيمكنك:
لهذه الحالة، اشترك في lifecycle الخاص بـ giftee:
giftee.created
giftee.launched
giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned
giftee.reviewed
تمثل هذه الأحداث الحالة التشغيلية لكل giftee. راجع قسم Webhooks والأحداث غير المتزامنة لمعرفة:
سيناريو العمل
تريد أن:
هذا تدفق Direct Marketplace Order.
نظرة lifecycle
Select Product
↓
Create Marketplace Order
↓
Preparing
↓
Shipped
↓
Delivered / Failed / Returned
GET /v1/providers/{providerCode}/products
استخدم هذا endpoint لتصفح المنتجات المتاحة. ثم جلب التفاصيل عند الحاجة:
GET /v1/providers/{providerCode}/products/{productId}
اختر:
POST /v1/marketplaceorders
قدّم:
يُقبل الطلب بشكل غير متزامن وتبدأ عملية fulfillment.
fulfillment في marketplace ينتهي إلى أحداث lifecycle الخاصة بـ giftee:
giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned
راجع قسم Webhooks والأحداث غير المتزامنة لمعرفة:
سيناريو العمل
تريد أن:
هذا تدفق gifting قائم على النقاط.
نظرة lifecycle
Enable Points
↓
Allocate Points
↓
Recipient Redeems
↓
Giftee Created
↓
Fulfillment Lifecycle
POST /v1/pointrecipients/{memberId}/enablepointfeature
يتيح هذا للمستلم الاحتفاظ بالنقاط واستردادها.
PATCH /v1/pointrecipients/{memberId}/points
قدّم:
يتم تحديث الرصيد فورًا.
عند استرداد المستلم للنقاط:
استرداد النقاط ينتهي إلى أحداث lifecycle الخاصة بـ giftee:
giftee.created
giftee.preparing
giftee.shipped
giftee.delivered
giftee.failed
giftee.returned
راجع قسم Webhooks والأحداث غير المتزامنة لمعرفة: