عنوان التوثيق ومفتاح مشروعك. هذا ما يحتاجه التطبيق.

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

العقد الكامل OpenAPI · الدليل النصي الكامل مع أمثلة curl وNode.js

ابدأ بفحص لا يرسل ولا يخصم

curl --silent --show-error --max-time 20 https://mz3b.com/api/v1/account/summary \
  -H "Authorization: Bearer $MZ3B_KEY"

يعيد project.name وready وreasons وحالة الاتصال ورقم المرسل المقنّع. اقرأ الرصيد المدفوع في billing.paidCredits والتجربة وصلاحيتها في billing.trial وتكلفة الإرسال في billing.sendCost. الأرقام فعلية من قاعدة البيانات، والرصيد مشترك بين مشاريع الحساب. روابط الإدارة والشحن موجودة في links.

الاستعلام لا يعيد تشغيل واتساب ولا يحجز رصيدًا. الجاهزية لحظية وقد تتغير. عند تعذر الوصول إلى الخادم تكون الحالة مجهولة، وليست نجاحًا مبنيًا على بيانات قديمة. الحد 12 قراءة لكل حساب في الدقيقة.

أكثر من رقم بمفتاح المشروع نفسه

فعّل مجموعة الأرقام من إعداد المشروع في اللوحة: أساسي واحتياطي، أو توزيع الاستخدام، مع حد يومي لكل رقم يشمل جميع مشاريعه. يعرض ملخص الحساب routing وحالات الأرقام المقنّعة. الاختيار قبل أول إرسال فقط؛ لا نكرر عملية غير مؤكدة من رقم بديل، ولا نتجاوز حظرًا أو حماية أو حدود واتساب. المشاريع القديمة لا تتغير حتى حفظ المجموعة. قواعد المجموعة والحدود وإعادة المحاولة.

المصادقة والصلاحيات

أرسل المفتاح في ترويسة Bearer من خادمك:

Authorization: Bearer YOUR_PROJECT_KEY

الصلاحيات: verifications:send وverifications:check وverifications:read لرموز التحقق؛ messages:send وmessages:read للتنبيهات؛ recipients:manage لقائمة الموظفين؛ account:read للرصيد والجاهزية. يعرض الملخص الصلاحيات الفعلية. المفاتيح القديمة غير المقيدة تستمر دون تبديل، أما المفتاح المقيد فيُرفض بـ 403 INSUFFICIENT_SCOPE خارج صلاحياته. يوضح الدليل الكامل إنشاء مفاتيح محدودة الصلاحية بواسطة مالك الحساب.

إرسال رمز

يجب أن يكون الرقم بصيغة E.164. لا ترسل الطلب إلا بعد أن يختار المستخدم بوضوح استلام الرمز عبر WhatsApp. أرسل مرجع موافقة فريدًا ووقت الضغط ومعرّف جلسة تسجيل الدخول؛ تُخزن هذه القيم كبصمات HMAC فقط. استبدل CURRENT_ISO_8601_TIMESTAMP بوقت الضغط الحالي بصيغة ISO 8601. أرسل UUID جديدًا في Idempotency-Key لكل عملية منطقية؛ إعادة المفتاح والحمولة نفسيهما تعيد النتيجة، أما إعادة المفتاح بحمولة مختلفة فتُرفض بـ 409.

curl -X POST https://mz3b.com/api/v1/verifications \
  -H "Authorization: Bearer mz_test_your_key" \
  -H "Idempotency-Key: 33ee8e91-8532-4f91-a561-8a1600b45213" \
  -H "Content-Type: application/json" \
  -d '{
    "to":"+97450000000",
    "locale":"ar",
    "purpose":"authentication",
    "consent":{
      "granted":true,
      "occurredAt":"CURRENT_ISO_8601_TIMESTAMP",
      "reference":"login:your-unique-request-id"
    },
    "context":{
      "userSessionId":"your-login-session-id",
      "deviceId":"your-opaque-device-id"
    }
  }'

قُبل طلب الإرسال، ولم يُؤكد الوصول بعد

الحالة pending لا تثبت وصول الرسالة. استخدم الرمز الذي يقدمه المستلم لإثبات صحة الاختبار. عند نتيجة غير مؤكدة لا تبدأ طلبًا جديدًا تلقائيًا.

{
  "id": "23e99cd1-f69a-43b8-b33f-12a0b96ca447",
  "status": "pending",
  "channel": "whatsapp",
  "expiresIn": 300
}

التحقق من الرمز

أرسل الرمز الذي أدخله المستخدم. الحالة approved وحدها نجاح. قد تعود pending عند رمز خاطئ مع محاولات متبقية، أو failed عند نفادها. في التطبيقات المحمية، جميع الرموز المرسلة إلى المستلم نفسه خلال عشر دقائق تشترك في خمس محاولات تحقق إجمالًا؛ لذلك لا يعيد طلب رمز جديد عدّاد التخمين.

curl -X POST https://mz3b.com/api/v1/verifications/23e99cd1-f69a-43b8-b33f-12a0b96ca447/check \
  -H "Authorization: Bearer mz_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}'

تنبيه طلب من رقم المشروع أو مجموعة أرقامه

سجّل الموظف المخول بعد موافقته الفعلية عبر POST /api/v1/message-recipients بالمفتاح نفسه. أرسل رقمه وrole: staff ودليل الموافقة. التسجيل لا يرسل ولا يخصم، ويُحفظ مرجع الموظف لإلغاء موافقته لاحقًا. الحد 25 موظفًا نشطًا لكل مشروع؛ هذه ليست واجهة للإرسال الجماعي أو التسويق.

curl --silent --show-error --max-time 20 https://mz3b.com/api/v1/messages \
  -H "Authorization: Bearer $MZ3B_KEY" \
  -H "Idempotency-Key: $PERSISTED_ORDER_OPERATION_ID" \
  -H "Content-Type: application/json" \
  --data-binary @order-alert.json

# order-alert.json (save the exact body before sending):
{
  "to": "STAFF_APPROVED_E164",
  "text": "الطلب 42 جاهز للمراجعة",
  "reference": "order:42:ready:v1",
  "url": "https://shop.example.com/orders/42"
}

يحجز التنبيه رسالة واحدة من التجربة السارية ثم الرصيد المدفوع. يعيد id وstatus وbilling. اقرأ لاحقًا GET /api/v1/messages/{id}. لا يفتح الخادم رابط الطلب أو يجلب معاينته؛ اجعل تفاصيل الطلب محمية بتسجيل دخول الموظف في تطبيقك.

المفتاح والجسم نفسيهما يعيدان العملية دون إرسال أو خصم جديد. رقم المستلم ومرجع الحدث يمنعان تكرار الحدث حتى لو تغير مفتاح منع التكرار. accepted ليس تأكيد وصول. عند uncertain اقرأ الحالة ولا تنشئ عملية بديلة. لا يرد الرصيد إلا عند إثبات عدم الإرسال.

الأمثلة الكاملة: تسجيل الموظف، إلغاء الموافقة، الإرسال، القراءة، الحدود والتعامل مع فقد الاستجابة.

محاكاة واضحة بلا إرسال أو خصم

أرسل جسم طلبك والمفتاح وترويسة منع التكرار إلى POST /api/v1/verifications/validate أو POST /api/v1/messages/validate. الرد willSend: false وcreditsCharged: 0. هذا فحص مدخلات، وليس إثبات جاهزية أو وصول. محاكاة التنبيه لا تسجل موظفًا ولا تتحقق من موافقته؛ افحص الجاهزية وسجله قبل الإرسال الحقيقي.

مثال Node.js من جهة الخادم

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

import { createMZ3B } from './mz3b-node.mjs';
const mz3b = createMZ3B(); // MZ3B_KEY: server secret manager
const readiness = await mz3b.summary(); // no send / no debit

// After recipient consent, create and PERSIST the operation in your DB.
// Use the SAME persisted operation on retry; never recreate it on timeout.
// const result = await mz3b.sendVerification(persistedOperation);
// const check = await mz3b.checkVerification(result.id, receivedCode);
// const verified = check.status === 'approved';

الأخطاء والنتائج غير المؤكدة

احتفظ بالمعرّف والمفتاح والجسم الأصلي. إذا انقطع الاتصال قبل وصول المعرّف، أعد الطلب نفسه لاستخراج نتيجته؛ لا تولد عملية جديدة تلقائيًا. بعد انتهاء نافذة موافقة OTP استخدم المعرّف المحفوظ أو اطلب مراجعة عند استمرار عدم اليقين. قد تبقى النتيجة مجهولة بعد فقد تاريخ البوابة؛ المجهول ليس فشلًا مؤكدًا.

قواعد الأمان

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

Webhooks

إضافة الرصيد تعتمد على توقيع Standard Webhooks في /api/webhooks/dodo. يدعم الخادم استقبال حالات جلسات WAHA ووصول الرسائل وطلبات الإيقاف عند تهيئة الربط في /api/webhooks/waha بتوقيع HMAC-SHA512 مع منع إعادة الحدث. لا تُخزن رسالة الإيقاف أو رقم المستلم بصورته الخام. قد لا تصل إشعارات التسليم إذا لم يكن ربط أحداث واتساب مفعّلًا؛ غيابها ليس دليل وصول. رابط العودة من الدفع يعرض النتيجة فقط ولا يثبت الدفع.