هذه النقاط الأربع تفتح إضافة مرسل واتساب عبر الواجهة البرمجية: قوالب رسائل الطلبات التي اعتمدتها المنصة، ورصيد واتساب الخاص بالمتجر، وسجل الرسائل المرسلة للزبائن، ونداء يرسل قالباً واحداً لزبون طلب واحد. الرسالة المرسلة عبر الواجهة البرمجية تخضع لقواعد الرسائل التلقائية نفسها: تُخصم رسالة واحدة من الرصيد عند وضعها في الطابور، وتعود إلى الرصيد إذا لم يفوترها واتساب، سواء رُفضت أو لم تصل أبداً أو وصلت دون فوترة. والرسالة التي لا تُرسل لا يُخصم منها شيء.

لا يمكن إرسال نص حرّ. كل رسالة هي أحد القوالب الستة المذكورة أسفله، تُملأ من بيانات الطلب (الاسم الأول للزبون، رقم الطلب، اسم المتجر، شركة التوصيل، مكتب الاستلام، المبلغ)، بالعربية أو الفرنسية، مع زر "تتبع طلبي".

قبل أن تبدأ

يجب أن تكون إضافة مرسل واتساب مفعّلة في المتجر (صفحة الإضافات في لوحة التحكم). نقاط القراءة الثلاث تعمل بدونها، أما الإرسال فيُرجع 403 addon_not_active.
شحن الرصيد يتم من صفحة الإضافة في لوحة التحكم (/dashboard/whatsapp-sender، زر شحن الرصيد). الواجهة البرمجية تقرأ الرصيد ولا تشحنه.
الرسائل تُرسل إلى الأرقام الجزائرية للهاتف النقال فقط (05 أو 06 أو 07). أي رقم آخر يُتجاوز بـ invalid_number دون أي خصم.
يحتاج المفتاح صلاحيات واتساب. المفاتيح المُنشأة من لوحة التحكم (الإعدادات ← واجهة API، /dashboard/api) تحصل على الاثنتين. الصلاحيات تُجمَّد لحظة إنشاء المفتاح، فالمفتاح الذي أُنشئ قبل الإصدار v1.6 لا يملكهما: أنشئ مفتاحاً جديداً من لوحة التحكم لاستعمال هذه النقاط. والمفتاح المُنشأ عبر POST /v1/keys لا يحصل إلا على الصلاحيات التي يملكها المفتاح الذي أنشأه.

النطاق	الوصف
`whatsapp:read`	الاطلاع على قوالب رسائل واتساب ورصيدك وسجل الرسائل المرسلة
`whatsapp:send`	إرسال رسائل واتساب لزبائنك بخصوص طلباتهم (تُخصم كل رسالة من رصيد واتساب)

GET /v1/whatsapp/templates

قائمة القوالب: النص العربي والفرنسي، وقيم مثال لكل خانة، وحالة الاعتماد لكل لغة.

المصادقة: مفتاح منصة بصلاحية whatsapp:read.

الحالة هي آخر ما قرأته المنصة من واتساب. تُحدَّث مرة كل 10 دقائق على الأكثر ما دامت الرسائل تُرسل، وUNKNOWN تعني أنها لم تُقرأ بعد. هذا النداء لا يتصل بواتساب أبداً. لا تُرسل إلا القوالب المعتمدة APPROVED: الإرسال بلغة قالبها غير معتمد يُتجاوز بـ template_not_approved دون أي خصم.

الطلب

curl 'https://api.dzbuild.app/v1/whatsapp/templates' \
  -H "Authorization: Bearer $DZ_KEY"

الاستجابة 200

يظهر هنا عنصر واحد من الستة.

{
  "data": {
    "items": [
      {
        "key": "shipped_home",
        "name": "dz_order_shipped_home",
        "toggle": "shipped",
        "languages": {
          "ar": {
            "body": "أهلاً {{1}}، طلبك رقم {{2}} من {{3}} في الطريق مع {{4}}.\nسيصلك خلال {{5}}. سيتصل بك عامل التوصيل قبل الوصول، يرجى إبقاء هاتفك متاحاً وتجهيز المبلغ: {{6}} دج.\nاضغط على الزر لتتبع طلبك.",
            "example": ["أحمد", "1024", "متجري", "Yalidine", "يوم إلى 3 أيام", "3500"],
            "status": "APPROVED"
          },
          "fr": {
            "body": "Bonjour {{1}}, votre commande n° {{2}} chez {{3}} est en route avec {{4}}.\nLivraison prévue sous {{5}}. Le livreur vous appellera avant d'arriver : restez joignable et préparez le montant de {{6}} DA.\nAppuyez sur le bouton pour suivre votre commande.",
            "example": ["Ahmed", "1024", "Ma Boutique", "Yalidine", "1 à 3 jours", "3500"],
            "status": "APPROVED"
          }
        }
      }
    ]
  }
}

القوالب الستة

`key`	`toggle`	ما يقرؤه الزبون
`received`	`received`	وصل طلبه وسيتصل به المتجر لتأكيده.
`confirmed`	`confirmed`	تم تأكيد طلبه وهو قيد التجهيز، مع المبلغ المطلوب.
`shipped_home`	`shipped`	طلبه في الطريق إلى عنوانه، مع مدة التوصيل المتوقعة المضبوطة في الإضافة.
`shipped_desk`	`shipped`	طلبه في الطريق إلى مكتب استلام تذكره الرسالة.
`delivery_failed`	`delivery_failed`	لم يتمكن الموصل من الوصول إليه اليوم وسيعاود المحاولة غداً.
`desk_ready`	`desk_ready`	الطرد ينتظره في مكتب الاستلام.

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

GET /v1/whatsapp/balance

الرصيد وحالة الإضافة وعدّادات الرسائل التي تظهر في صفحة الإضافة.

المصادقة: مفتاح منصة بصلاحية whatsapp:read.

الطلب

curl 'https://api.dzbuild.app/v1/whatsapp/balance' \
  -H "Authorization: Bearer $DZ_KEY"

الاستجابة 200

{
  "data": {
    "balance": 412,
    "low_balance": false,
    "addon_active": true,
    "stats": {
      "sent": 12,
      "delivered": 230,
      "read": 158,
      "failed": 4,
      "free": 9,
      "used_month": 96
    }
  }
}

الحقل	المعنى
`balance`	عدد الرسائل المتبقية في الرصيد. المتجر الذي لم يشحن أبداً رصيده `0`.
`low_balance`	`true` عندما يقل الرصيد عن 50 رسالة.
`addon_active`	هل إضافة مرسل واتساب مفعّلة في المتجر.
`stats.sent`، `stats.delivered`، `stats.read`، `stats.failed`	رسائل آخر 30 يوماً حسب حالتها الحالية. `delivered` تشمل الرسائل التي قرأها الزبون، فلا تجمع `delivered` و`read`.
`stats.free`	رسائل آخر 30 يوماً التي وصلت إلى الزبون ولم يفوترها واتساب. أُعيدت إلى رصيدك.
`stats.used_month`	الرسائل المخصومة من الرصيد منذ أول الشهر دون أن تُعاد إليه، أي التي فوترها واتساب والتي لم يبلّغ واتساب عن نتيجتها بعد.

GET /v1/whatsapp/messages

رسائل المتجر من الأحدث إلى الأقدم: الرسائل التلقائية (source قيمته auto) والمرسلة عبر الواجهة البرمجية (source قيمته api). رقم هاتف الزبون لا يُرجَع أبداً.

المصادقة: مفتاح منصة بصلاحية whatsapp:read.

معاملات الاستعلام

المعامل	النوع	الافتراضي	ملاحظات
`order_id`	أرقام	لا شيء	رسائل هذا الطلب فقط. أي قيمة ليست أرقاماً فقط تُرجع `400 bad_request`.
`limit`	int	50	من 1 إلى 200.
`cursor`	string	لا شيء	قيمة `next_cursor` من الصفحة السابقة. انظر الترقيم.

الطلب

curl 'https://api.dzbuild.app/v1/whatsapp/messages?order_id=6894' \
  -H "Authorization: Bearer $DZ_KEY"

الاستجابة 200

{
  "data": {
    "items": [
      {
        "id": 4181,
        "order_id": 6894,
        "event": "shipped_home",
        "source": "api",
        "status": "read",
        "language": "fr",
        "template_name": "dz_order_shipped_home",
        "error_title": null,
        "refunded": false,
        "billing": "charged",
        "created_at": "2026-09-26 10:14:03"
      },
      {
        "id": 4180,
        "order_id": 6894,
        "event": "confirmed",
        "source": "auto",
        "status": "delivered",
        "language": "ar",
        "template_name": "dz_order_confirmed",
        "error_title": null,
        "refunded": true,
        "billing": "free",
        "created_at": "2026-09-25 18:02:41"
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}

الحقل	المعنى
`event`	في الرسالة التلقائية: حدث الطلب الذي أطلقها (`received` أو `confirmed` أو `shipped` أو `delivery_failed` أو `desk_ready`). في رسالة الواجهة البرمجية: مفتاح القالب المرسل.
`source`	`auto` أو `api`.
`status`	انظر الجدول أدناه.
`language`	`ar` أو `fr`.
`template_name`	اسم القالب المسجّل لدى واتساب.
`error_title`	سبب تجاوز الرسالة أو فشلها، وإلا فـ `null`.
`refunded`	`true` بعد أن يعود رصيد الرسالة.
`billing`	`charged` عندما يفوتر واتساب الرسالة، و`free` عندما يعود رصيدها (فشلت، أو لم تصل خلال 30 يوماً، أو وصلت دون أن يفوترها واتساب)، و`null` ما دام واتساب لم يبلّغ عن النتيجة.
`created_at`	بصيغة `YYYY-MM-DD HH:MM:SS` بتوقيت الخادم.

`status`	المعنى
`queued`	مدفوعة وتنتظر (قيد الإرسال). ترسلها المنصة خلال دقيقة تقريباً.
`sending`	تُسلَّم الآن إلى واتساب (قيد الإرسال).
`sent`	قبلها واتساب (أُرسلت).
`delivered`	وصلت إلى هاتف الزبون (وصلت).
`read`	فتحها الزبون (قُرئت).
`failed`	لم يتمكن واتساب من إيصالها (فشلت). إذا فشل الإرسال إلى واتساب نفسه، يعود الرصيد خلال دقائق. وإذا أبلغ واتساب عن الفشل، تنتظر المنصة 24 ساعة قبل إعادة الرصيد، لأن واتساب قد يبلّغ بعدها أنها وصلت إلى جهاز آخر للزبون، فتتحول حالتها إلى `delivered`. تصبح `refunded` قيمتها `true` بعد عودة الرصيد.
`skipped`	لم تُرسل ولم يُخصم منها شيء (لم تُرسل). `error_title` يذكر السبب.

الرسالة المتجاوزة تحمل أحد هذه الأسباب في error_title:

`error_title`	المعنى
`invalid_number`	رقم غير صالح: الهاتف ليس رقماً جزائرياً للنقال.
`suppressed`	رقم بلا واتساب.
`template_not_approved`	القالب بانتظار الموافقة في تلك اللغة.
`empty_param`	بيانات ناقصة: الطلب ينقصه معطى يحتاجه القالب.

POST /v1/orders/{id}/whatsapp

يضع قالباً واحداً في طابور الإرسال لزبون طلب واحد ويخصم رسالة واحدة من الرصيد. ترسلها المنصة خلال دقيقة تقريباً.

المصادقة: مفتاح منصة بصلاحية whatsapp:send. يتطلب Idempotency-Key.

الجسم

الحقل	النوع	إلزامي	ملاحظات
`template`	string	نعم	قيمة `key` من `GET /v1/whatsapp/templates`، أو `shipped` التي تختار `shipped_home` أو `shipped_desk` أو `desk_ready` حسب نوع توصيل الطلب (منزل أو مكتب أو استلام).
`language`	`ar` أو `fr`	لا	الافتراضي هو لغة الرسائل المختارة في إعدادات الإضافة، أو لغة المتجر إن لم تُختر لغة.

ما يفعله النداء

يتحقق من أن الإضافة مفعّلة وأن الطلب تابع للمتجر. طلب متجر آخر يُرجع 404 مثل طلب غير موجود.
لا يأخذ مفاتيح الرسائل التلقائية في الإضافة بعين الاعتبار: يمكنك إرسال قالب أوقفه التاجر للرسائل التلقائية.
كل قالب يُرسل مرة واحدة لكل طلب عبر الواجهة البرمجية. النداء الثاني يُرجع 409 already_sent مع id وstatus للرسالة السابقة. الاستثناء الوحيد محاولة سابقة تم تجاوزها، مثلاً لأن الرقم كان غير صالح ثم صُحّح في الطلب: عندها يعيد النداء المحاولة.
يتحقق من الرقم واعتماد القالب وبيانات الطلب. أي مشكلة تُرجع 422 وسببها هو رمز الخطأ، وتُسجَّل رسالة متجاوزة دون أي خصم.
يخصم رسالة واحدة من الرصيد. الرصيد الفارغ يُرجع 402 no_credit ولا يُسجَّل شيء.
يُرجع 202. تابع الرسالة بـ GET /v1/whatsapp/messages?order_id= مع رقم الطلب. الرسالة التي يرفضها واتساب تصبح failed وتعود إلى الرصيد.

رسائل الواجهة البرمجية تُحسب منفصلة عن الرسائل التلقائية. إرسال shipped_home عبر الواجهة البرمجية لا يمنع رسالة "الطلب في الطريق" التلقائية للطلب نفسه، والرسالة التلقائية لا تمنع الإرسال عبر الواجهة البرمجية. وكل واحدة مدفوعة.

الطلب

curl -X POST 'https://api.dzbuild.app/v1/orders/6894/whatsapp' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wa-6894-shipped-1" \
  -d '{"template": "shipped", "language": "fr"}'

الاستجابة 202

قيمة template هي المفتاح الذي وُضع في الطابور، بعد تحويل shipped إلى القالب المناسب.

{
  "data": {
    "message_id": 4181,
    "status": "queued",
    "template": "shipped_home",
    "language": "fr"
  }
}

الأخطاء

HTTP	الرمز	السبب
400	`bad_request`	رقم الطلب ليس أرقاماً فقط، أو الجسم ليس JSON صالحاً، أو `Idempotency-Key` غائب أو غير صالح.
402	`no_credit`	رصيد واتساب فارغ. لم يُسجَّل شيء.
403	`forbidden`	`Missing scope: whatsapp:send`
403	`addon_not_active`	إضافة مرسل واتساب غير مفعّلة في المتجر.
404	`not_found`	لا يوجد طلب بهذا الرقم في المتجر.
409	`already_sent`	هذا القالب أُرسل من قبل لهذا الطلب عبر الواجهة البرمجية.
422	`unknown_template`	`template` ليست `shipped` ولا مفتاحاً من القائمة.
422	`invalid_language`	`language` ليست `ar` ولا `fr`.
422	`invalid_number`	هاتف الطلب ليس رقماً جزائرياً للنقال.
422	`suppressed`	هاتف الطلب بلا واتساب.
422	`template_not_approved`	القالب غير معتمد بعد في تلك اللغة.
422	`empty_param`	الطلب ينقصه معطى يحتاجه القالب.
422	`idempotency_key_reuse`	استُعمل `Idempotency-Key` نفسه مع جسم مختلف أو لطلب آخر.
500	`send_failed`	تعذر وضع الرسالة في الطابور. أعد المحاولة بالمفتاح نفسه.

هكذا يبدو 409 already_sent.

{
  "error": {
    "code": "already_sent",
    "message": "This template was already sent for this order",
    "id": 4181,
    "status": "delivered"
  }
}

إعادة المحاولة وIdempotency-Key

أول استجابة لكل مفتاح تُحفظ 24 ساعة. إعادة المحاولة بالمفتاح نفسه والجسم نفسه تُرجع تلك الاستجابة مع Idempotency-Replay: 1، حتى لو كانت 402 أو 403 أو 422. لذلك بعد شحن الرصيد أو تفعيل الإضافة أو تصحيح الطلب، أعد المحاولة بـ Idempotency-Key جديد: المفتاح القديم يبقى يُرجع الخطأ القديم. والـ 202 المُعادة تعني أنه لم تُوضع رسالة ثانية في الطابور.

المفتاح نفسه مع جسم مختلف أو لطلب آخر يُرجع 422 idempotency_key_reuse. استجابات 5xx و429 لا تُحفظ أبداً، فأعد المحاولة بالمفتاح نفسه. وإن كانت الرسالة قد وُضعت في الطابور فعلاً قبل الخطأ، تُرجع إعادة المحاولة 409 already_sent مع id الرسالة، ولا يُخصم شيء مرتين. انظر Idempotency.

حدود معروفة

نص مدة التوصيل. القالب shipped_home يحمل مدة التوصيل المتوقعة كما كتبها التاجر في إعدادات الإضافة. إذا كان هذا الحقل فارغاً، يحمل المدة الافتراضية للإضافة مكتوبة بلغة الرسائل المختارة في إعداداتها (أو لغة المتجر إن لم تُختر لغة). رسالة فرنسية من متجر مدته بالعربية، مكتوبة أو افتراضية، تُظهر ذلك النص العربي وسط الرسالة الفرنسية. المدة المكتوبة بالأرقام فقط، مثل 24-72h، تُقرأ بالطريقة نفسها في اللغتين.
بطء الإرسال بعد فحص الاعتماد. عندما يمضي أكثر من 10 دقائق على آخر قراءة لحالة اعتماد قالب، يعيد الإرسال قراءتها من واتساب قبل وضع الرسالة في الطابور. يحدث ذلك مرة واحدة على الأكثر لكل قالب ولغة كل 10 دقائق، وقد يؤخر POST حتى 15 ثانية، لذا اضبط مهلة عميل HTTP لديك على 20 ثانية على الأقل.

المقالات ذات الصلة

رسائل واتساب

قبل أن تبدأ

GET /v1/whatsapp/templates

الطلب

الاستجابة 200

القوالب الستة

GET /v1/whatsapp/balance

الطلب

الاستجابة 200

GET /v1/whatsapp/messages

معاملات الاستعلام

الطلب

الاستجابة 200

POST /v1/orders/{id}/whatsapp

الجسم

ما يفعله النداء

الطلب

الاستجابة 202

الأخطاء

إعادة المحاولة وIdempotency-Key

حدود معروفة