واجهة API والتكاملات في دورني: REST API وWebhooks والكاشير والودجت

ماذا يمكنك أن تبني

ست تكاملات تعمل اليوم، دون أي تطوير خاص من جهة دورني.

نقاط تلقائية من الكاشيركل عملية بيع برقم هاتف العميل أو بريده تضيف نقاطه. الإيصالات المكررة يتم تجاهلها.ربط الكاشير ←
مزامنة العملاءأنشئ عميلاً أو حدّث بياناته من نظام إدارة العملاء أو متجرك أو نظام ERP، واقرأ رصيد نقاطه.نقاط الوصول ←
التحقق من الهدايا عند الكاونترتحقق من رمز QR أو مرجع من 8 أحرف من برنامجك، وسجّل الهدية كمسلّمة.نقاط الوصول ←
Webhooks فوريةمشارك جديد، هدية مربوحة أو مسلّمة، نقاط مكتسبة، مكافأة مستبدلة: خادمك يُبلَّغ فوراً.Webhooks ←
لعبة على موقعكزر عائم أو نافذة منبثقة أو جزء داخل الصفحة: سطر واحد من الكود على موقعك أو متجرك الإلكتروني.الودجت والتضمين ←
روابط ورموز QRالقائمة الرقمية، الحجز، رابط البايو، النماذج: روابط عامة لطاولاتك ومطبوعاتك وحساباتك.الروابط ورموز QR ←

البدء السريع

ثلاث خطوات لأول طلب. حوالي خمس دقائق.

1
فعّل التكاملات
التكاملات (API وWebhooks والكاشير) متوفرة في باقات بريميوم والمؤسسات. صاحب الحساب هو من يدير المفاتيح.
2
أنشئ مفتاح API
سمّه، واختر صلاحياته وإن أردت نشاطاً تجارياً واحداً. المفتاح الكامل (dw_live_…) يظهر مرة واحدة فقط: احفظه على خادمك.
3
أرسل أول طلب
GET /me يعيد اسم المفتاح وصلاحياته والأنشطة التجارية التي يصل إليها.

داخل التطبيقالقائمةالتكاملاتمفاتيح APIإنشاء مفتاح

أول طلب · cURL

curl https://app.dawwerni.com/api/ext/v1/me \
  -H "Authorization: Bearer $DAWWERNI_API_KEY"

200 OK الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "apiVersion": "v1",
  "key": {
    "id": 7,
    "name": "POS bridge - Tunis",
    "prefix": "dw_live_a1b2c3d4",
    "scopes": [
      "customers:read",
      "customers:write",
      "points:write",
      "redemptions:write",
      "rewards:read",
      "webhooks:manage",
      "winnings:verify"
    ],
    "businessScope": null
  },
  "businesses": [
    {
      "id": 186,
      "name": "Café Amira"
    }
  ],
  "rateLimitPerMinute": 120
}

المصادقة

كل طلب يحمل مفتاح API في ترويسة Authorization (Bearer) أو في X-Api-Key. كل شيء عبر HTTPS وبصيغة JSON.

HTTP headers

Authorization: Bearer dw_live_a1b2c3d4••••••••••••••••••••••••••••••••••••••••
# or
X-Api-Key: dw_live_a1b2c3d4••••••••••••••••••••••••••••••••••••••••

استخدم المفتاح على خوادمك فقط: الواجهة لا تقبل الطلبات من المتصفح (CORS)، والمفتاح المنشور في موقع أو تطبيق جوال يصبح مكشوفاً.
المفتاح يعمل فقط ضمن صلاحياته وأنشطته التجارية؛ وإلا تجيب الواجهة بـ 403.
إذا كان المفتاح يغطي عدة أنشطة تجارية، أرسل businessId في الطلب (وإلا 400 BUSINESS_REQUIRED).
المفتاح الملغى يتوقف فوراً (401 API_KEY_REVOKED). حتى 20 مفتاحاً نشطاً لكل حساب.

الصلاحيات (scopes)

الصلاحية	تسمح بـ
`customers:read`	البحث عن العملاء وقراءة نقاطهم
`customers:write`	إنشاء العملاء أو تحديثهم
`points:write`	تسجيل المبيعات ومنح النقاط
`rewards:read`	عرض مكافآت الولاء
`redemptions:write`	استبدال النقاط بمكافأة
`winnings:verify`	التحقق من الهدايا وتسليمها
`webhooks:manage`	إدارة عناوين Webhooks

القواعد العامة

العنوان الأساسي: https://app.dawwerni.com/api/ext/v1 — صيغة JSON فقط (Content-Type: application/json في طلبات POST).
التواريخ: بصيغة ISO 8601. حقول حساب العميل (createdAt وupdatedAt) بالتوقيت المحلي دون منطقة زمنية؛ والبقية (المفاتيح وWebhooks والسجلات) بتوقيت UTC مع «Z».
أرقام الهاتف: يُنصح بالصيغة الدولية (+21698123456). نقبل «00216…» والمسافات؛ يتم التعرف على العميل بالبريد أولاً ثم بالهاتف.
التقسيم إلى صفحات: القوائم تقبل page (من 0) وsize (20 افتراضياً، 100 كحد أقصى) وتعيد data وpage.
عدم التكرار (Idempotency): أضف ترويسة Idempotency-Key (مثلاً UUID) لكل طلب POST. إعادة نفس الطلب خلال 24 ساعة تعيد الاستجابة الأصلية مع Idempotent-Replayed: true دون تنفيذ العملية مرة أخرى.
حد الطلبات: 120 طلباً في الدقيقة لكل مفتاح. بعد ذلك: HTTP 429 مع ترويسة Retry-After.
الإصدارات: الإصدار v1 يتلقى إضافات فقط (حقول ونقاط وصول جديدة). تجاهل الحقول غير المعروفة في الاستجابات.

شكل القوائم

{
  "data": [ … ],
  "page": { "number": 0, "size": 20, "totalElements": 42, "totalPages": 3, "hasNext": true }
}

ترويسات حد الطلبات

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
# when exceeded: HTTP 429 + Retry-After: <seconds>

نقاط الوصول (Endpoints)

كل الاستجابات أدناه ناتجة عن طلبات حقيقية للواجهة على مقهى تجريبي في تونس.

معلومات المفتاح

GET/api/ext/v1/me

الصلاحية: أي مفتاح صالح

اسم المفتاح وبادئته وصلاحياته، والأنشطة التجارية التي يصل إليها، وحد الطلبات. مفيد لاختبار إعداداتك.

curl "https://app.dawwerni.com/api/ext/v1/me" \
  -H "Authorization: Bearer $DAWWERNI_API_KEY"

200 OK الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "apiVersion": "v1",
  "key": {
    "id": 7,
    "name": "POS bridge - Tunis",
    "prefix": "dw_live_a1b2c3d4",
    "scopes": [
      "customers:read",
      "customers:write",
      "points:write",
      "redemptions:write",
      "rewards:read",
      "webhooks:manage",
      "winnings:verify"
    ],
    "businessScope": null
  },
  "businesses": [
    {
      "id": 186,
      "name": "Café Amira"
    }
  ],
  "rateLimitPerMinute": 120
}

البحث عن العملاء

GET/api/ext/v1/customers

الصلاحية: customers:read

قائمة مقسّمة لحسابات الولاء. صفِّ حسب الهاتف أو البريد؛ دون تصفية: كل عملاء الأنشطة التجارية للمفتاح.

المعاملات
الاسم	المكان	النوع	الوصف
`phone`	query	string	هاتف العميل (رمّز + بـ %2B) (اختياري)
`email`	query	string	بريد العميل (اختياري)
`businessId`	query	integer	حصر النتائج في نشاط تجاري واحد (اختياري)
`page`	query	integer ≥ 0	رقم الصفحة من 0 (اختياري)
`size`	query	integer 1–100 (20)	حجم الصفحة (اختياري)

curl "https://app.dawwerni.com/api/ext/v1/customers?phone=%2B21698123456" \
  -H "Authorization: Bearer $DAWWERNI_API_KEY"

200 OK الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "data": [
    {
      "id": 313,
      "businessId": 186,
      "name": "Amira B.",
      "email": "[email protected]",
      "phone": "+21698123456",
      "points": {
        "spendable": 0,
        "locked": 0,
        "lifetimeEarned": 0
      },
      "createdAt": "2026-10-13T21:36:40.087382",
      "updatedAt": "2026-10-13T21:36:40.121926"
    }
  ],
  "page": {
    "number": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1,
    "hasNext": false
  }
}

قراءة عميل

GET/api/ext/v1/customers/313

الصلاحية: customers:read

حساب ولاء واحد بمعرّفه في دورني.

المعاملات
الاسم	المكان	النوع	الوصف
`id`*	path	integer	معرّف العميل في دورني (إلزامي)

curl "https://app.dawwerni.com/api/ext/v1/customers/313" \
  -H "Authorization: Bearer $DAWWERNI_API_KEY"

200 OK الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "id": 313,
  "businessId": 186,
  "name": "Amira B.",
  "email": "[email protected]",
  "phone": "+21698123456",
  "points": {
    "spendable": 0,
    "locked": 0,
    "lifetimeEarned": 0
  },
  "createdAt": "2026-10-13T21:36:40.087382",
  "updatedAt": "2026-10-13T21:36:40.121926"
}

404 Not Found الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "error": {
    "code": "CUSTOMER_NOT_FOUND",
    "message": "Customer not found"
  }
}

إنشاء عميل أو تحديثه

POST/api/ext/v1/customers

الصلاحية: customers:write

يبحث عن العميل بالبريد ثم بالهاتف؛ ينشئه إن لم يوجد (201) أو يكمل بياناته (200).

المعاملات
الاسم	المكان	النوع	الوصف
`phone`	body	string (E.164)	الهاتف؛ الهاتف أو البريد إلزامي (اختياري)
`email`	body	string	البريد؛ الهاتف أو البريد إلزامي (اختياري)
`name`	body	string ≤ 120	الاسم المعروض (اختياري)
`businessId`	body	integer	إلزامي إذا كان المفتاح يغطي عدة أنشطة (اختياري)
`Idempotency-Key`	header	string ≤ 255	إعادة آمنة لمدة 24 ساعة (اختياري)

curl -X POST "https://app.dawwerni.com/api/ext/v1/customers" \
  -H "Authorization: Bearer $DAWWERNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Amira Ben Salah", "phone": "+21698123456", "email": "[email protected]" }'

201 Created الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "id": 313,
  "businessId": 186,
  "name": "Amira Ben Salah",
  "email": "[email protected]",
  "phone": "+21698123456",
  "points": {
    "spendable": 0,
    "locked": 0,
    "lifetimeEarned": 0
  },
  "createdAt": "2026-10-13T21:36:40.0873817",
  "updatedAt": "2026-10-13T21:36:40.0873817"
}

200 OK الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "id": 313,
  "businessId": 186,
  "name": "Amira B.",
  "email": "[email protected]",
  "phone": "+21698123456",
  "points": {
    "spendable": 0,
    "locked": 0,
    "lifetimeEarned": 0
  },
  "createdAt": "2026-10-13T21:36:40.087382",
  "updatedAt": "2026-10-13T21:36:40.1219263"
}

400 Bad Request الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "error": {
    "code": "CUSTOMER_IDENTIFIER_REQUIRED",
    "message": "Provide a phone or an email"
  }
}

رصيد النقاط

GET/api/ext/v1/customers/313/points

الصلاحية: customers:read

النقاط المتاحة والمجمّدة والمكتسبة إجمالاً، مقسّمة حسب البرنامج (الألعاب / الولاء) وبطاقة الأختام.

المعاملات
الاسم	المكان	النوع	الوصف
`id`*	path	integer	معرّف العميل في دورني (إلزامي)

curl "https://app.dawwerni.com/api/ext/v1/customers/313/points" \
  -H "Authorization: Bearer $DAWWERNI_API_KEY"

200 OK الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "customerId": 313,
  "businessId": 186,
  "total": 192,
  "spendable": 192,
  "locked": 0,
  "lifetimeEarned": 192,
  "byProgram": {
    "GAMES": 0,
    "LOYALTY": 192
  },
  "balanceMode": "COMBINED",
  "loyaltyMode": "POINTS",
  "stampCount": 0,
  "stampsRequired": 10,
  "stampRewardsAvailable": 0
}

تسجيل عملية شراء (نقاط)

POST/api/ext/v1/purchases

الصلاحية: points:write

يسجّل إيصال الكاشير ويضيف النقاط حسب قواعد برنامج الولاء. يتم إنشاء العميل إن لم يكن موجوداً.

externalId يعرّف الإيصال: إعادة إرسال نفس externalId تعيد النتيجة الأولى مع "duplicate": true دون منح أي نقاط.
دون "points" يتم تحويل المبلغ حسب قاعدة بطاقة الولاء (نقاط لكل وحدة مدفوعة). فعّل بطاقة الولاء من قسم الولاء؛ وإلا تكون pointsAwarded صفراً.
المرتجعات لا تسحب نقاطاً: أرسل عمليات البيع فقط.

المعاملات
الاسم	المكان	النوع	الوصف
`externalId`*	body	string ≤ 120	معرّف فريد للإيصال في الكاشير (إلزامي)
`amount`*	body	number ≥ 0	المبلغ المدفوع (إلزامي)
`customer`*	body	{ id \| phone \| email, name }	العميل: معرّف دورني، أو الهاتف / البريد (+ الاسم) (إلزامي)
`currency`	body	ISO 4217 (TND, EGP, SAR…)	رمز العملة ISO (TND وEGP وSAR وUSD…) (اختياري)
`points`	body	integer 0–1 000 000	نقاط محددة (وإلا تُحسب بقاعدتك) (اختياري)
`items`	body	[{ sku, name, quantity, unitPrice }]	بنود الإيصال (يُحفظ عددها فقط) (اختياري)
`businessId`	body	integer	إلزامي إذا كان المفتاح يغطي عدة أنشطة (اختياري)
`Idempotency-Key`	header	string ≤ 255	إعادة آمنة لمدة 24 ساعة (اختياري)

curl -X POST "https://app.dawwerni.com/api/ext/v1/purchases" \
  -H "Authorization: Bearer $DAWWERNI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: f3b0c442-98fc-4c1c-9a3a-6b0e5a1d2c01" \
  -d '{ "customer": { "phone": "+21698123456", "name": "Amira Ben Salah" }, "amount": 42.5, "currency": "TND", "externalId": "R-2026-000123", "items": [ { "sku": "LATTE", "name": "Latte", "quantity": 2, "unitPrice": 7.5 } ] }'

201 Created الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "purchaseId": 9,
  "externalId": "R-2026-000123",
  "duplicate": false,
  "businessId": 186,
  "amount": 42.5,
  "currency": "TND",
  "itemsCount": 1,
  "pointsRequested": null,
  "pointsAwarded": 42,
  "customer": {
    "id": 313,
    "businessId": 186,
    "name": "Amira Ben Salah",
    "email": "[email protected]",
    "phone": "+21698123456",
    "points": {
      "spendable": 42,
      "locked": 0,
      "lifetimeEarned": 42
    },
    "createdAt": "2026-10-13T21:36:40.087382",
    "updatedAt": "2026-10-13T21:36:40.2972964"
  },
  "balance": {
    "customerId": 313,
    "businessId": 186,
    "total": 42,
    "spendable": 42,
    "locked": 0,
    "lifetimeEarned": 42,
    "byProgram": {
      "GAMES": 0,
      "LOYALTY": 42
    },
    "balanceMode": "COMBINED",
    "loyaltyMode": "POINTS",
    "stampCount": 0,
    "stampsRequired": 10,
    "stampRewardsAvailable": 0,
    "program": "LOYALTY",
    "outcome": "OK"
  },
  "source": "api"
}

200 OK الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "purchaseId": 9,
  "externalId": "R-2026-000123",
  "duplicate": true,
  "businessId": 186,
  "amount": 42.5,
  "currency": "TND",
  "itemsCount": 1,
  "pointsRequested": null,
  "pointsAwarded": 0,
  "customer": {
    "id": 313,
    "businessId": 186,
    "name": "Amira Ben Salah",
    "email": "[email protected]",
    "phone": "+21698123456",
    "points": {
      "spendable": 42,
      "locked": 0,
      "lifetimeEarned": 42
    },
    "createdAt": "2026-10-13T21:36:40.087382",
    "updatedAt": "2026-10-13T21:36:40.2972964"
  },
  "balance": {
    "customerId": 313,
    "businessId": 186,
    "total": 42,
    "spendable": 42,
    "locked": 0,
    "lifetimeEarned": 42,
    "byProgram": {
      "GAMES": 0,
      "LOYALTY": 42
    },
    "balanceMode": "COMBINED",
    "loyaltyMode": "POINTS",
    "stampCount": 0,
    "stampsRequired": 10,
    "stampRewardsAvailable": 0,
    "program": "LOYALTY",
    "outcome": "OK"
  },
  "source": "api"
}

400 Bad Request الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "error": {
    "code": "EXTERNAL_ID_REQUIRED",
    "message": "externalId (POS receipt id, max 120 chars) is required"
  }
}

عرض المكافآت

GET/api/ext/v1/rewards

الصلاحية: rewards:read

المكافآت النشطة لأنشطتك: تكلفتها بالنقاط والمخزون والبرنامج الذي يمكن الدفع به.

المعاملات
الاسم	المكان	النوع	الوصف
`businessId`	query	integer	حصر النتائج في نشاط تجاري واحد (اختياري)
`page`	query	integer ≥ 0	رقم الصفحة من 0 (اختياري)
`size`	query	integer 1–100 (20)	حجم الصفحة (اختياري)

curl "https://app.dawwerni.com/api/ext/v1/rewards" \
  -H "Authorization: Bearer $DAWWERNI_API_KEY"

200 OK الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "data": [
    {
      "id": 34,
      "businessId": 186,
      "name": "Free cappuccino",
      "description": "One cappuccino, any size",
      "pointsCost": 100,
      "stock": 50,
      "program": "BOTH"
    }
  ],
  "page": {
    "number": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1,
    "hasNext": false
  }
}

استبدال مكافأة

POST/api/ext/v1/redemptions

الصلاحية: redemptions:write

يخصم النقاط ويُنقص المخزون وينشئ عملية استبدال «قيد الانتظار» تظهر في صفحات الولاء.

يجب أن تكون للعميل مشاركة واحدة على الأقل في لعبة (وإلا 422 NO_PARTICIPATION_FOR_CUSTOMER).
مع externalId، إعادة إرسال نفس الاستبدال لا تكرره ("duplicate": true).

المعاملات
الاسم	المكان	النوع	الوصف
`customerId`*	body	integer	معرّف العميل في دورني (إلزامي)
`rewardId`*	body	integer	معرّف المكافأة (GET /rewards) (إلزامي)
`externalId`	body	string ≤ 120	مرجعك، يمنع التكرار (اختياري)
`notes`	body	string ≤ 250	ملاحظة داخلية (اختياري)
`Idempotency-Key`	header	string ≤ 255	إعادة آمنة لمدة 24 ساعة (اختياري)

curl -X POST "https://app.dawwerni.com/api/ext/v1/redemptions" \
  -H "Authorization: Bearer $DAWWERNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customerId": 313, "rewardId": 33, "externalId": "RD-1001", "notes": "Counter 1" }'

201 Created الاستجابةمثال مبني من كود الواجهة (يتطلب مشاركة حقيقية في لعبة)

{
  "redemptionId": 57,
  "businessId": 186,
  "rewardId": 33,
  "rewardName": "Free cappuccino",
  "pointsUsed": 100,
  "status": "PENDING",
  "requestedAt": "2026-10-13T21:40:12.418302",
  "program": "LOYALTY",
  "customerId": 313,
  "externalId": "RD-1001",
  "duplicate": false
}

422 Unprocessable Entity الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "error": {
    "code": "NO_PARTICIPATION_FOR_CUSTOMER",
    "message": "This customer has no participation yet; redemptions through the API need at least one"
  }
}

التحقق من هدية

POST/api/ext/v1/winnings/verify

الصلاحية: winnings:verify

مثل مسح رمز QR في التطبيق: يتحقق من الرمز، ويسجّل الهدية كمسلّمة ويعيد بيانات الفائز.

code يقبل رمز QR، أو الرابط الكامل /verify-winning/…، أو المرجع من 8 أحرف الموجود في بريد الفائز.
هدية سبق تسليمها تعيد 200 مع "verified": false و"alreadyClaimed": true.

المعاملات
الاسم	المكان	النوع	الوصف
`code`*	body	string	رمز QR أو رابط التحقق أو المرجع من 8 أحرف (إلزامي)

curl -X POST "https://app.dawwerni.com/api/ext/v1/winnings/verify" \
  -H "Authorization: Bearer $DAWWERNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "a1b2c3d4" }'

200 OK الاستجابةمثال مبني من كود الواجهة (يتطلب مشاركة حقيقية في لعبة)

{
  "verified": true,
  "alreadyClaimed": false,
  "message": "Winning verified successfully",
  "winning": {
    "id": 9120,
    "ref": "a1b2c3d4",
    "businessId": 186,
    "gameId": 412,
    "prize": "Free croissant",
    "fullName": "Amira Ben Salah",
    "email": "[email protected]",
    "phone": "+21698123456",
    "status": "taked",
    "createdAt": "2026-10-12T17:05:44.120931"
  }
}

404 Not Found الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "error": {
    "code": "WINNING_NOT_FOUND",
    "message": "No gift matches this code"
  }
}

400 Bad Request الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "error": {
    "code": "INVALID_CODE",
    "message": "The code is not a valid Dawwerni gift code"
  }
}

عرض Webhooks

GET/api/ext/v1/webhooks

الصلاحية: webhooks:manage

عناوينك وأحداثها وحالة التسليم.

المعاملات
الاسم	المكان	النوع	الوصف
`page`	query	integer ≥ 0	رقم الصفحة من 0 (اختياري)
`size`	query	integer 1–100 (20)	حجم الصفحة (اختياري)

curl "https://app.dawwerni.com/api/ext/v1/webhooks" \
  -H "Authorization: Bearer $DAWWERNI_API_KEY"

200 OK الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "data": [
    {
      "id": 2,
      "url": "https://example.com/webhooks/dawwerni",
      "description": "CRM sync",
      "events": [
        "winning.created",
        "points.earned"
      ],
      "active": false,
      "failureCount": 0,
      "lastSuccessAt": null,
      "lastFailureAt": null,
      "disabledAt": null,
      "disabledReason": null,
      "secretHint": "whsec_...9fQe",
      "createdAt": "2026-10-13T20:36:40.854516Z"
    }
  ],
  "page": {
    "number": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1,
    "hasNext": false
  }
}

إنشاء Webhook

POST/api/ext/v1/webhooks

الصلاحية: webhooks:manage

يسجّل عنوان HTTPS عاماً والأحداث المطلوبة. الاستجابة تحتوي على مفتاح التوقيع (ويظهر لاحقاً في التطبيق أيضاً).

HTTPS فقط؛ العناوين الخاصة أو المحلية مرفوضة. حتى 10 عناوين لكل حساب.

المعاملات
الاسم	المكان	النوع	الوصف
`url`*	body	https URL	عنوان HTTPS عام لخادمك (إلزامي)
`events`*	body	string[]	الأحداث المطلوبة (انظر Webhooks) (إلزامي)
`description`	body	string ≤ 255	وصف حر (اختياري)
`active`	body	boolean (true)	false لإنشائه متوقفاً (اختياري)

curl -X POST "https://app.dawwerni.com/api/ext/v1/webhooks" \
  -H "Authorization: Bearer $DAWWERNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://crm.example.com/webhooks/dawwerni", "events": [ "points.earned", "winning.created" ], "description": "CRM sync" }'

201 Created الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "id": 2,
  "url": "https://example.com/webhooks/dawwerni",
  "description": "CRM sync",
  "events": [
    "winning.created",
    "points.earned"
  ],
  "active": false,
  "failureCount": 0,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "disabledAt": null,
  "disabledReason": null,
  "secretHint": "whsec_...9fQe",
  "createdAt": "2026-10-13T20:36:40.854516100Z",
  "secret": "whsec_<shown once: store it in your server config>"
}

400 Bad Request الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "error": {
    "code": "INVALID_WEBHOOK_URL",
    "message": "Only https:// URLs are allowed"
  }
}

400 Bad Request الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "error": {
    "code": "UNKNOWN_EVENT",
    "message": "Unknown event: order.paid"
  }
}

حذف Webhook

DELETE/api/ext/v1/webhooks/2

الصلاحية: webhooks:manage

يحذف العنوان ويلغي عمليات التسليم المعلّقة.

المعاملات
الاسم	المكان	النوع	الوصف
`id`*	path	integer	معرّف العنوان (إلزامي)

curl -X DELETE "https://app.dawwerni.com/api/ext/v1/webhooks/2" \
  -H "Authorization: Bearer $DAWWERNI_API_KEY"

204 No Content الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

رموز الأخطاء

كل الأخطاء بنفس الشكل. اعتمد على الرمز (ثابت)؛ الرسالة بالإنجليزية وقد تتغير.

403 Forbiddenاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This API key is missing the scope points:write"
  }
}

HTTP	الرمز	المعنى
400	`VALIDATION_FAILED`	معامل ناقص أو غير صحيح
400	`INVALID_JSON`	المحتوى ليس JSON صالحاً
400	`CUSTOMER_IDENTIFIER_REQUIRED`	الهاتف أو البريد مطلوب
400	`INVALID_PHONE`	هاتف غير صالح (يُنصح بالصيغة الدولية)
400	`INVALID_EMAIL`	بريد غير صالح
400	`EXTERNAL_ID_REQUIRED`	externalId ناقص (120 حرفاً كحد أقصى)
400	`INVALID_AMOUNT`	المبلغ ناقص أو سالب
400	`INVALID_CURRENCY`	العملة ليست رمز ISO 4217
400	`INVALID_POINTS`	points خارج النطاق من 0 إلى 1٬000٬000
400	`BUSINESS_REQUIRED`	المفتاح يغطي عدة أنشطة: أرسل businessId
400	`INVALID_IDEMPOTENCY_KEY`	Idempotency-Key: من 1 إلى 255 حرف ASCII
400	`INVALID_EXTERNAL_ID`	externalId طويل جداً
400	`CODE_REQUIRED`	code ناقص
400	`INVALID_CODE`	ليس رمز هدية من دورني
400	`INVALID_WEBHOOK_URL`	العنوان مرفوض (HTTPS عام فقط)
400	`EVENTS_REQUIRED`	اختر حدثاً واحداً على الأقل
400	`UNKNOWN_EVENT`	حدث غير معروف
401	`UNAUTHENTICATED`	لم يتم إرسال مفتاح API
401	`INVALID_API_KEY`	مفتاح API غير صالح
401	`API_KEY_REVOKED`	مفتاح API ملغى
403	`ACCOUNT_INACTIVE`	حساب دورني غير نشط
403	`FEATURE_NOT_ENABLED`	التكاملات غير مشمولة في الباقة
403	`INSUFFICIENT_SCOPE`	المفتاح ينقصه صلاحية
403	`BUSINESS_FORBIDDEN`	النشاط التجاري خارج نطاق المفتاح
403	`BUSINESS_UNAVAILABLE`	تم حذف النشاط التجاري للمفتاح
404	`CUSTOMER_NOT_FOUND`	العميل غير موجود
404	`REWARD_NOT_FOUND`	المكافأة غير موجودة
404	`WINNING_NOT_FOUND`	لا توجد هدية بهذا الرمز
404	`WEBHOOK_NOT_FOUND`	عنوان Webhook غير موجود
409	`WINNING_NOT_CLAIMABLE`	مشاركة دون هدية (خاسرة أو ملغاة)
409	`IDEMPOTENCY_CONFLICT`	نفس Idempotency-Key قيد المعالجة: أعد المحاولة
409	`DUPLICATE_EXTERNAL_ID`	نفس externalId قيد المعالجة: أعد المحاولة
415	`UNSUPPORTED_MEDIA_TYPE`	أرسل Content-Type: application/json
422	`IDEMPOTENCY_KEY_REUSED`	Idempotency-Key مستخدم لطلب آخر
422	`INSUFFICIENT_POINTS`	النقاط غير كافية
422	`REWARD_INACTIVE`	المكافأة معطّلة
422	`REWARD_OUT_OF_STOCK`	المكافأة نفدت
422	`NO_PARTICIPATION_FOR_CUSTOMER`	العميل لم يلعب أي لعبة بعد
422	`REDEMPTION_REJECTED`	مرفوض حسب قواعد الولاء
422	`WEBHOOK_LIMIT_REACHED`	حتى 10 عناوين
422	`NO_BUSINESS`	لا يوجد نشاط تجاري نشط في الحساب
429	`RATE_LIMITED`	طلبات كثيرة: انتظر Retry-After ثانية
500	`INTERNAL_ERROR`	خطأ غير متوقع: أعد المحاولة لاحقاً

Webhooks

يرسل دورني طلب POST موقّعاً عبر HTTPS إلى خادمك عند كل حدث تختاره. أجب بأي حالة 2xx خلال 5 ثوانٍ. يعمل مع أي أداة تستقبل Webhooks (خادمك، Make، n8n، Zapier…).

داخل التطبيقالقائمةالتكاملاتخطافات الويبإضافة عنوان استقبال

الأحداث

الحدث	يُرسل عندما
`participant.created`	يترك لاعب بياناته في لعبة (فائزاً أم لا)
`winning.created`	يربح لاعب هدية
`winning.claimed`	تُسلَّم هدية (مسح QR، تغيير الحالة أو /winnings/verify)
`points.earned`	تُضاف نقاط من عملية شراء وصلت عبر الواجهة أو من كاشير مربوط
`reward.redeemed`	تُستبدل مكافأة عبر الواجهة

مثال على المحتوى

{
  "id": "evt_8f2k4m9q1x7w3z5r0t6y2u4p",
  "type": "points.earned",
  "createdAt": "2026-10-13T20:36:40.512Z",
  "apiVersion": "v1",
  "data": {
    "customerId": 313,
    "businessId": 186,
    "points": 42,
    "reason": "purchase",
    "externalId": "R-2026-000123",
    "amount": 42.5,
    "currency": "TND",
    "source": "api",
    "balance": {
      "customerId": 313,
      "businessId": 186,
      "total": 42,
      "spendable": 42,
      "locked": 0,
      "lifetimeEarned": 42,
      "byProgram": {
        "GAMES": 0,
        "LOYALTY": 42
      },
      "program": "LOYALTY",
      "outcome": "OK"
    }
  }
}

مثال مبني من كود الواجهة (يتطلب مشاركة حقيقية في لعبة)

الترويسات والتوقيع

HTTP

POST https://crm.example.com/webhooks/dawwerni
Content-Type: application/json; charset=utf-8
User-Agent: Dawwerni-Webhooks/1.0
X-Dawwerni-Event: points.earned
X-Dawwerni-Delivery: dlv_4k9x2m7q1w8z5r3t6y0u2p4s     (same value on every retry)
X-Dawwerni-Timestamp: 1791927400                    (unix seconds)
X-Dawwerni-Signature: sha256=<hex HMAC-SHA256(secret, timestamp + "." + raw body)>

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

احسب HMAC-SHA256(secret, timestamp + "." + المحتوى الخام) بصيغة hex مسبوقاً بـ «sha256=»، وقارنه بزمن ثابت مع X-Dawwerni-Signature. ارفض الطوابع الزمنية الأقدم من 5 دقائق. زر «إرسال حدث تجريبي» في التطبيق يرسل حدث ping.

// Node.js (Express): verify on the RAW body, not on re-serialised JSON
const crypto = require('crypto');
const express = require('express');
const app = express();

app.post('/webhooks/dawwerni', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.header('X-Dawwerni-Timestamp');
  const sig = req.header('X-Dawwerni-Signature') || '';
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.DAWWERNI_WEBHOOK_SECRET)
    .update(ts + '.' + req.body.toString('utf8'))
    .digest('hex');
  const ok = sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString('utf8'));
  // de-duplicate on req.header('X-Dawwerni-Delivery'), then handle event.type
  res.sendStatus(200); // answer within 5 seconds, do slow work afterwards
});

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

الفشل = حالة غير 2xx أو تجاوز المهلة أو خطأ شبكة. إعادة المحاولة بعد دقيقة، 5 دقائق، 30 دقيقة، ساعتين ثم 12 ساعة.
بعد 20 فشلاً متتالياً يتم تعطيل العنوان وتصلك إشعار في التطبيق. أعد تفعيله بعد إصلاح خادمك.
قد يصل الحدث مرتين أو بترتيب مختلف: أزل التكرار بالاعتماد على X-Dawwerni-Delivery.
سجل التسليم (30 يوماً) وتغيير المفتاح السري متاحان في التطبيق.

ربط الكاشير (POS)

دون كتابة كود: لكل ربط رابط سري تلصقه في نظام الكاشير. كل عملية بيع برقم هاتف العميل أو بريده تضيف نقاطه؛ الإيصالات المكررة والمرتجعات يتم تجاهلها.

داخل التطبيقالقائمةالتكاملاتأنظمة نقاط البيعربط

FoodicsFOODICSالمطاعم والمقاهي في السعودية والخليج: الطلبات المغلقة المرتبطة بعميل.
LoyverseLOYVERSEكاشير مجاني للمقاهي والمحلات: إيصالات البيع المرتبطة بعميل (Webhook «Receipts»).
كاشير آخر (JSON)GENERIC_JSONأي كاشير أو متجر إلكتروني أو أداة أتمتة تستطيع إرسال طلب JSON بعد عملية البيع.

رابط الربط

الرابط يحتوي على رمز سري: من يملكه يستطيع إرسال مبيعات إلى حسابك. يمكنك استبداله في أي وقت من التطبيق (القديم يتوقف فوراً).

URL

https://app.dawwerni.com/api/ext/v1/pos/{CONNECTOR}/{connectionId}?token=pos_<secret token>
# CONNECTOR = GENERIC_JSON | LOYVERSE | FOODICS
# the token can also be sent as the header  X-Dawwerni-Token: pos_<secret token>

صيغة JSON العامة

لـ«كاشير آخر»، أرسل هذا الـJSON بعد كل عملية بيع. الحقول المعتمدة:

`externalId`	معرّف فريد للإيصال (إلزامي)
`amount`	المبلغ المدفوع (إلزامي)
`currency`	رمز العملة ISO، اختياري
`type`	"sale" (افتراضي)؛ "refund" يتم تجاهله
`customer`	phone وemail وname: الهاتف أو البريد ضروري لكسب النقاط
`items`	بنود الإيصال، اختيارية

cURL

curl -X POST "$DAWWERNI_POS_URL" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "R-2026-000200", "amount": 31.5, "currency": "TND", "type": "sale", "customer": { "phone": "+21698123456", "name": "Amira" }, "items": [ { "sku": "CROISSANT", "name": "Croissant", "quantity": 3, "unitPrice": 2.5 } ] }'

200 OK الاستجابةاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "received": 1,
  "processed": 1,
  "duplicates": 0,
  "ignored": 0,
  "failed": 0
}

عدة إيصالات دفعة واحدة

أرسل {"purchases": [...]} (حتى 100 إيصال). الاستجابة تعدّ الإيصالات المعالجة والمكررة والمتجاهلة والفاشلة؛ التفاصيل في «آخر الأحداث».

الطلب

{
  "purchases": [
    {
      "externalId": "R-2026-000200",
      "amount": 31.5,
      "currency": "TND",
      "type": "sale",
      "customer": {
        "phone": "+21698123456",
        "name": "Amira"
      },
      "items": [
        {
          "sku": "CROISSANT",
          "name": "Croissant",
          "quantity": 3,
          "unitPrice": 2.5
        }
      ]
    },
    {
      "externalId": "R-2026-000201",
      "amount": 12,
      "currency": "TND",
      "customer": {
        "email": "[email protected]"
      }
    },
    {
      "externalId": "R-2026-000202",
      "amount": 9,
      "type": "refund"
    }
  ]
}

200 OKاستجابة حقيقية من الواجهة (بيانات تجريبية)

{
  "received": 3,
  "processed": 1,
  "duplicates": 1,
  "ignored": 1,
  "failed": 0
}

توقيع اختياري

إذا عيّنت مفتاح توقيع على الربط، يجب أن يحمل كل طلب X-Dawwerni-Timestamp وX-Dawwerni-Signature (نفس طريقة Webhooks الصادرة، بهامش 5 دقائق).

Node.js

// Optional: sign the request when a signing secret is set on the connection
const crypto = require('crypto');
const body = JSON.stringify(sale);
const ts = Math.floor(Date.now() / 1000).toString();
const signature = 'sha256=' + crypto.createHmac('sha256', process.env.DAWWERNI_POS_SIGNING_SECRET)
  .update(ts + '.' + body).digest('hex');
await fetch(process.env.DAWWERNI_POS_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Dawwerni-Timestamp': ts, 'X-Dawwerni-Signature': signature },
  body
});

أخطاء رابط الكاشير

400	`INVALID_JSON`	المحتوى ليس JSON صالحاً
400	`PAYLOAD_TOO_LARGE`	الحد الأقصى للمحتوى 512 كيلوبايت
401	`INVALID_CONNECTION_TOKEN`	ربط غير معروف أو رمز غير صالح
401	`INVALID_SIGNATURE`	توقيع ناقص أو قديم أو خاطئ
403	`CONNECTION_PAUSED`	الربط متوقف في دورني
403	`FEATURE_NOT_ENABLED`	التكاملات غير مشمولة في الباقة
404	`UNKNOWN_CONNECTOR`	نوع كاشير غير معروف في الرابط
422	`UNSUPPORTED_PAYLOAD`	محتوى غير مقروء
429	`RATE_LIMITED`	120 حدثاً في الدقيقة لكل ربط

الودجت والتضمين في الويب

اعرض ألعابك ونماذجك على موقعك أو متجرك الإلكتروني، دون API ودون مطوّر.

ودجت الألعاب (widget.js)

اختر لعبة ونمط العرض (زر عائم أو نافذة منبثقة أو داخل صفحة) والمواقع المسموح بها؛ التطبيق يعطيك الكود الجاهز للصق.

داخل التطبيقالقائمةالحملاتالموقع والمتجر الإلكترونيأداة جديدة

HTML

<!-- Floating button or pop-up: paste before </body> -->
<script src="https://app.dawwerni.com/widget.js" data-dawwerni-key="dw_YOUR_WIDGET_KEY" async></script>

اللعبة تفتح في إطار معزول (Shadow DOM + iframe): تنسيقات موقعك لا تؤثر عليها، والعكس صحيح.
نافذة منبثقة فوراً، أو بعد مهلة، أو عند التمرير، أو عند نية المغادرة، مع تحديد تكرار العرض.
المواقع المسموح بها: الودجت يظهر فقط على نطاقاتك (ونطاقاتها الفرعية).
لغة اللعبة: الخاصية data-lang (ar وfr وen)، وإلا لغة صفحتك.
مرات الظهور والفتح تُحتسب في التطبيق. يتم تفعيل الودجت عند الطلب: تواصل معنا.

نمط «داخل صفحة»

HTML

<!-- Inline: the game appears inside this block -->
<div data-dawwerni-game="dw_YOUR_WIDGET_KEY"></div>
<script src="https://app.dawwerni.com/widget.js" data-dawwerni-key="dw_YOUR_WIDGET_KEY" data-lang="ar" async></script>

نموذج تواصل مضمّن

يمكن تضمين نموذج دورني منشور داخل iframe؛ يرسل النموذج ارتفاعه ليتأقلم دون شريط تمرير.

داخل التطبيقالقائمةالعملاء المحتملوننماذج الطلباتمشاركةتضمين في موقعك

HTML

<iframe id="dw-lead-your-form" src="https://app.dawwerni.com/f/your-form?embed=1&src=website"
  title="Contact form" style="width:100%;max-width:600px;min-height:640px;border:0" loading="lazy"></iframe>
<script>
  // optional: the form reports its height so the frame never shows a scrollbar
  window.addEventListener('message', function (e) {
    if (e.origin !== 'https://app.dawwerni.com') return;
    var d = e.data || {};
    if (d.type === 'dawwerni-lead-form:height' && d.slug === 'your-form') {
      document.getElementById('dw-lead-your-form').style.height = (d.height + 8) + 'px';
    }
  });
</script>

الروابط العامة ورموز QR

كل وحدة تنشر صفحة عامة. التطبيق يعطيك الرابط الدقيق (ورمز QR جاهزاً للطباعة للقائمة ورابط البايو والنماذج)؛ هذه صيغ الروابط.

القائمة الرقمية (رقم الطاولة اختياري)	`https://app.dawwerni.com/m/{menu-slug}?table=12`
رابط البايو لإنستغرام وتيك توك	`https://app.dawwerni.com/l/{bio-slug}`
صفحة حجز المواعيد	`https://app.dawwerni.com/book/{booking-slug}`
نموذج التواصل (src = مصدر الزيارة)	`https://app.dawwerni.com/f/{form-slug}?src=instagram`
كتالوج المنتجات	`https://app.dawwerni.com/c/{catalog-slug}`
لعبة (الرمز يعطيه التطبيق)	`https://app.dawwerni.com/review/{game-code}`

هذه الصفحات لا تحتاج مفتاح API. روابط الألعاب يولّدها التطبيق: لا تركّبها بنفسك.

تحتاج مساعدة في الربط؟

كاشير غير مذكور، نظام ERP، أو تكامل حسب الطلب (باقة المؤسسات)؟ أخبرنا بالأداة التي تستخدمها ونرد عليك بأفضل حل.

راسلنا على WhatsApp أرسل بريداً ([email protected])عرض الباقات