# حزمة ربط MZ3B

أدوات دون رسم إضافي، وليست رسائل مجانية غير محدودة. الإرسال الحقيقي يستهلك رصيد الحساب حسب ملخص الخادم. الخدمة مستقلة وليست واجهة Meta الرسمية، ولا تضمن وصول الرسالة.

## البداية الآمنة

حمّل الملفات التالية إلى مجلد خاص على خادم تطبيقك مع الحفاظ على أسمائها:

- [عميل Node.js 22 أو أحدث](https://mz3b.com/examples/mz3b-node.mjs).
- [القوالب وتشخيص النتائج](https://mz3b.com/examples/mz3b-tools.mjs).
- [فحص الجاهزية من الخادم](https://mz3b.com/examples/mz3b-doctor.mjs).

احفظ المفتاح باسم `MZ3B_API_KEY` في مدير الأسرار على الخادم. يبقى الاسم السابق `MZ3B_KEY` مدعومًا كبديل. لا تضع القيمة في أوامر التشغيل أو المحادثات أو المستودع أو السجلات أو تطبيق الهاتف أو المتصفح. لا تطبع ترويسات الطلب، ولا تُحمّل ملف إعدادات غير موثوق.

بعد حقن السر بأمان في بيئة الخادم، شغّل:

```sh
node mz3b-doctor.mjs
```

الأداة تنفذ قراءة واحدة فقط إلى `GET /api/v1/account/summary`. لا ترسل ولا تخصم ولا تسجل موظفًا ولا تعيد ربط جلسة. استيراد الملفات لا ينفذ أي طلب. لا تطبع اسم الحساب أو الرقم أو الرصيد أو المفتاح.

- رمز الخروج `0`: جاهزية حديثة مع الصلاحيات السبع؛ ليس إثبات وصول.
- رمز الخروج `2`: توجد خطوة مراجعة في `actions`.
- رمز الخروج `1`: يلزم فحص إعداد السر أو الصلاحيات أو الشبكة.

معاني الإجراءات: `refresh_status` تحديث الملاحظة القديمة أو المجهولة؛ `review_connection` مراجعة الربط؛ `review_protection` مراجعة الحماية، وهي ليست إثبات حظر؛ `top_up` الشحن؛ `review_key_scopes` مراجعة الصلاحيات؛ `review_service` مراجعة الخدمة.

لفحص تكامل رموز الدخول وحده، استخدم `diagnoseSummary` مع صلاحيات `account:read` و`verifications:send` و`verifications:read` و`verifications:check`، بدل اشتراط صلاحيات تنبيهات الموظفين أيضًا.

## دمج تطبيقك خطوة بخطوة

1. اقرأ الملخص من خادم التطبيق فقط. اعرض بطاقة مختصرة بحالة الاتصال ووقت الملاحظة والرصيد المدفوع والتجربة وصلاحيتها وتكلفة الإرسال وروابط الإدارة والشحن.
2. عند طلب المستخدم الفعلي استلام رمز واتساب، أنشئ العملية عبر `newVerification` بوقت الموافقة ومرجعها ومعرّف جلسة الدخول الحقيقيين.
3. احفظ العملية ومفتاح منع التكرار في قاعدة بيانات تطبيقك **قبل** `sendVerification`. احفظ معرّف المحاولة في جلسة الدخول نفسها مع الرقم المقصود.
4. مرر الرمز الذي أدخله المستخدم إلى `checkVerification`. لا تسمح بالدخول إلا عندما يعيد الخادم `status: approved`. لا تقبل معرّف محاولة يختاره المتصفح بدل محاولة جلسة المستخدم.
5. سجّل الموظف المخول بعد موافقته الفعلية عبر `enrollStaff`. احفظ معرّف المستلم؛ استخدم `revokeStaff` لإلغاء الموافقة. الإلغاء يمنع إرسالًا جديدًا ولا يسحب رسالة بدأت بالفعل.
6. حضّر تنبيه الطلب عبر `orderTemplate` ثم `newOrderAlert`. احفظ الجسم والمفتاح ومرجع الحدث مرة واحدة، ثم نفذ `sendOrderAlert`. اقرأ النتيجة لاحقًا عبر `message`.

الصلاحيات المطلوبة حسب الميزة: `account:read` و`verifications:send` و`verifications:check` و`verifications:read` و`messages:send` و`messages:read` و`recipients:manage`. لا تبدّل مفتاحًا قائمًا تلقائيًا عند الخطأ.

أمثلة وظائف الخادم الكاملة موجودة في [دليل الحزمة والأمثلة](https://mz3b.com/examples/README.en.md)، وأمثلة `curl` بالعربية في [دليل التكامل](https://mz3b.com/integration.md). الأمثلة لا تنشئ قاعدة بيانات تطبيقك ولا تحل محل مصادقة مستخدميه أو صلاحياتهم أو حماية الطلبات وحدود الاستخدام.

## قالب تنبيه موظف

```js
import { createMZ3B } from './mz3b-node.mjs';
import { orderTemplate } from './mz3b-tools.mjs';
const client = createMZ3B();
const content = orderTemplate({
  template: 'new_order', order: '42', locale: 'ar', revision: '1',
});
// إنشاء جسم توضيحي فقط؛ لا استدعاء إرسال في هذا المثال.
const operation = client.newOrderAlert({
  to: 'STAFF_APPROVED_E164', ...content,
  url: 'https://shop.example.com/orders/42',
});
// استبدل القيم التوضيحية واحفظ العملية في قاعدة بياناتك قبل إرسالها.
```

القوالب الثلاثة: `new_order` و`order_updated` و`action_required`. هي للموظفين الموافقين وليست تسويقًا للعملاء. ثبّت `reference` للحدث والمستلم، وزد `revision` لحدث جديد فعلًا فقط، لا لإعادة المحاولة. تعديل اللغة أو القالب بعد حفظ العملية يغيّر الجسم وقد يسبب تعارضًا.

## عدم التكرار والمهلات

احفظ معرّف الحدث والجسم الأصلي ومفتاح منع التكرار ومعرّف النتيجة في مخزن محمي دائم. لا تسجل الأسرار أو الرموز أو الأرقام الكاملة. استدعاء مُنشئ العملية مرة أخرى يولد مفتاحًا جديدًا؛ لا تفعله عند كل إعادة محاولة.

إذا كان معرّف النتيجة معروفًا، اقرأ حالتها. إذا فُقد الرد الأول، احتفظ بالطلب والمفتاح نفسيهما وأعد العملية الأصلية وفق عقد الواجهة، دون إنشاء موافقة أو عملية أو رقم مرسل بديل. العميل لا يعيد الطلبات تلقائيًا. عند `uncertain` أو مهلة الشبكة احتفظ بالحجز ولا تعتبره فشلًا مؤكدًا. `accepted` و`pending` لا تثبتان وصول الرسالة، ونجاح HTTP لا يثبت نجاح التحقق.

احترم `Retry-After` وراجع تعارض `409`. انتهـاء رمز التحقق يتطلب محاولة وموافقة جديدتين عند طلب المستخدم، ولا يعيد حد التخمين. فحص الجاهزية ليس حجزًا: عالج نفاد الرصيد أو انقطاع الرقم عند الإرسال حتى لو كان الفحص السابق ناجحًا.

## أنواع الاختبار الثلاثة

- [المختبر التعليمي](https://mz3b.com/docs#toolkit): أمثلة ثابتة داخل المتصفح. لا مفتاح أو رقم حقيقي أو رمز صالح أو إرسال أو خصم. ليس محاكيًا كاملًا للخادم.
- `validateVerification` و`validateOrderAlert`: فحص مدخلات عبر واجهات الخادم؛ يعيد `willSend: false` و`creditsCharged: 0`. محاكاة OTP تحتاج موافقة فعلية حديثة؛ لا تصطنعها. محاكاة التنبيه لا تسجل الموظف ولا تفحص موافقته أو الرصيد أو الوصول. حدود الاستعلام تبقى مطبقة.
- `sendVerification` و`sendOrderAlert`: إرسال حقيقي واستهلاك رصيد. لا تختبر دون مستلم محدد وموافقته الخاصة بالاختبار. بادئة المفتاح `mz_test_` لا تعني أنه تجريبي.

## بطاقة الحساب وروابط الطلبات

اعرض القيم الفعلية من `billing`؛ الأرصدة مشتركة بين مشاريع الحساب. الإعفاء يظهر في `billing.unlimited` وتكلفة الإرسال، وليس رصيدًا وهميًا. التجربة لا تكون قابلة للاستخدام إلا قبل انتهاء صلاحيتها ومع `eligibleForSender: true`.

استعلم عبر خادمك كل 30 ثانية على الأكثر أثناء ظهور البطاقة، مع طلب واحد قيد التنفيذ واحترام حد 12 قراءة للحساب في الدقيقة. اعزل التخزين المؤقت بحسب المشروع والمفتاح، واجعل الحالة مجهولة بعد 45 ثانية بلا ملاحظة جديدة. لا تحفظ شارة جاهزية خضراء إلى الأبد.

رابط الطلب يجب أن يكون HTTPS بنطاق عام دون بيانات دخول أو عنوان IP أو مضيف محلي أو منفذ غير قياسي. MZ3B لا يفتح الرابط أو يجلب معاينته. تحقّق أنت من صلاحية الموظف للطلب بعد تسجيل دخوله، واحفظ مسار رجوع نسبيًا آمنًا داخل تطبيقك؛ لا تسمح بإعادة توجيه خارجية أو تضع سرًا في الرابط.

## ما يتوفر وما لم يُنفّذ

متاح: الواجهات السابقة، عميل Node، ثلاثة قوالب باللغتين، تشخيص النتائج، أداة قراءة الجاهزية، وثماني حالات تعليمية. القوالب تنشئ النص فقط وليست أتمتة مجدولة. لا تغيير للأسعار أو الرصيد.

غير مشمول: حزمة Laravel مختبرة، الرد الآلي بالذكاء الاصطناعي، صندوق فريق، الأتمتة المجدولة، تنبيهات صحة الرقم التلقائية أو إشعارات التسليم لخادم العميل. لا تسوّقها كميزات تعمل الآن.