المرجع الكامل لـ WhatsApp API — للبشر وللآلة

1. نظرة عامة

هذه الصفحة هي المرجع الكامل لواجهة بوابة واتساب REST — نفس الواجهة التي تعمل خلف لوحة الويب وتطبيقات الجوال وتكاملات طرف ثالث. كُتبت لجمهورين معاً: البشر يقرؤون النص، والآلة تقرأ GET /openapi.json (مواصفة OpenAPI 3 يفرض اختبارات البرمجة مطابقتها للشيفرة).

البوابة متعددة المستأجرين: لكل تطبيق مستأجر مفتاح مطوّر خاص به، وباقات إعادة بيعه، وعملاؤه وجلساته — معزولة تماماً عن أي تطبيق آخر. تطبيق «الدفتر المحاسبي» هو أحد التكاملات المرجعية المبنية على نفس هذه الواجهة تماماً، وليس له أي امتياز.

الخمس بيانات الاعتمادية التي ستواجهها

المفردات المشتركة

2. مسارا التكامل

كل تكامل يبدأ باختيار أحد المسارين. يشتركان في نفس الجلسات والإرسال ونموذج الأخطاء — والفرق في من يتعرف، ومن يربط الرقم، ومن يدفع ثمن الحصة.

3. البدء السريع

الرابط الأساسي: https://masarroute.com (وحين التطوير المحلي http://localhost:3011). كل طلب ورد بـ JSON وUTF-8، والإصدار في المسار: /api/v1.

curl https://masarroute.com/health

# Public: active platform plans with prices and discounts — no key needed
curl https://masarroute.com/api/v1/plans

# Your first send — needs an active plan + a linked session + a wsk key
curl -X POST "https://masarroute.com/api/v1/messages/send" \
  -H "X-API-Key: wsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"to":"966500000000","text":"Hello from the gateway"}'

curl https://masarroute.com/openapi.json -o openapi.json

4. المصادقة

تُحفظ المفاتيح مُجزّأة (SHA-256 + pepper) ولا يمكن استرجاعها — تُعرض مرة واحدة عند الإنشاء، وإلا فالمخرج هو التدوير أو الإبطال.

التسجيل (رمز OTP على واتساب)

{
  "name": "Zakaria",
  "country_code": "967",
  "phone": "772935854",
  "password": "Secret#2026",
  "password_confirm": "Secret#2026",
  "email": "[email protected]"     // optional
}

{ "phone": "772935854", "code": "123456" }

الدخول

ثلاث طرق، كلها تعيد JWT. حقل identifier يقبل رقماً أو بريداً، وجميع صيغ الرقم مقبولة:

772935854 · 967772935854 · 00967772935854 · +967772935854

{
  "identifier": "772935854",     // phone or email (case-insensitive)
  "password": "••••••••"
}

// 1) request-otp { "identifier": "772935854" }   // existing accounts only
// 2) verify-otp  { "phone": "772935854", "code": "123456" }

الدخول الاجتماعي: افتح رابط الدخول في المتصفح (يحوّل 302 للمزود بحالة لمرة واحدة)، وافق، فيعيد الرجوع 302 إلى /login حاملاً JWT في الفراغمنت (لا يُسجَّل). البريد الموثّق لدى المزود يربط الحساب المطابق، وغير الموثّق ينشئ حساباً بلا بريد. الموقوفون وعملاء التطبيقات مرفوضون. يتطلب مفاتيح GOOGLE_/GITHUB_ في .env، ورابط الرجوع أدناه مسجلاً في لوحة كل مزود.

GET /api/v1/auth/oauth/google/login
GET /api/v1/auth/oauth/google/callback
GET /api/v1/auth/oauth/github/login
GET /api/v1/auth/oauth/github/callback

استعادة كلمة السر برمز OTP

رمز من ٦ أرقام يصل إلى واتساب إن كان المُدخل رقماً، وإلى البريد إن كان بريداً (يتطلب ضبط SMTP_HOST في .env).

// request-reset
{ "identifier": "772935854" }

// verify-reset — invalidates every other reset code
{
  "identifier": "772935854",
  "code": "123456",
  "password": "NewPass#2026",
  "password_confirm": "NewPass#2026"
}
// verify-reset step 1 — code only, verifies without consuming
{ "identifier": "772935854", "code": "123456" }
// → { "verified": true, ... }

توثيق الرقم يحدث لحظة الربط

ربط جهاز واتساب (QR أو كود إقران) يثبت ملكية الرقم: يُوسم الحساب بـ phone_verified_at تلقائياً حين تبلغ الجلسة connected. لذلك يستطيع تطبيق الجوال حذف صفحة الـOTP — التوثيق أثر جانبي للربط. ويبقى مسار /client/auth/otp لاسترجاع المفتاح بعد إعادة التثبيت.

5. باقات المنصة والتسعير

يعيد باقات المنصة النشطة مع سعرها بعد التخفيض. حقول إضافية على كل باقة:

• original_price — السعر قبل التخفيض.
• price_monthly / price_yearly — السعر بعد التخفيض.
• has_discount وdiscount_label — وجود التخفيض ونصه للعرض.
• devices_unlimited — true عندما يكون حد الأجهزة ٠ (مفتوح).

التسعير التلقائي للباقة المخصصة

السعر = (عدد الرسائل ÷ ١٠٠٠) × سعر الألف حسب الشريحة + (الأجهزة − ١) × ٢. سعر الألف ينخفض كلما زاد الحجم، والجهاز الأول مشمول.

{
  "messages": 500000, "devices": 25,
  "price": 146, "yearly_price": 1460,
  "price_per_thousand": 0.162,
  "tier": "500K",
  "plan_slug": "pro",          // nearest fixed plan
  "plan_name": "Professional"
}

شرائح التسعير الحالية (لكل ١٠٠٠ رسالة): أقل من ٥ آلاف ٠٫٣٠ · ٥ آلاف ٠٫٢٦ · ٢٥ ألف ٠٫٢٣ · ١٠٠ ألف ٠٫٢١ · ٢٥٠ ألف ٠٫١٨ · ٥٠٠ ألف ٠٫١٦٢ · مليون ٠٫١٤٥ · مليون ونصف ٠٫١١٥ · ٥ ملايين ٠٫٠٩

اشتراكك واستهلاكك

واجهات التسعير والتخفيض (للإدارة فقط)

6. التخفيضات

التخفيضات تخص باقات المنصة فقط ولا تشمل باقات إعادة البيع ولا عملاء التطبيقات.

• النطاق: باقة واحدة، عدة باقات، أو كل الباقات.
• النوع: نسبة مئوية (١-٩٠) أو مبلغ ثابت.
• تخفيض مخصّص لباقة يتقدّم على التخفيض الشامل.
• يمكن تحديد تاريخ بداية ونهاية، والإيقاف الفوري من اللوحة.

curl -X POST "https://masarroute.com/api/v1/admin/discounts" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan_ids":["PLAN_UUID"],"kind":"percent","value":15,
       "note":"end-of-month promo"}'

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

7. تطبيقك وهويته

التطبيق هو مستؤجرك داخل البوابة. أنشئه من لوحة العميل ← تطبيقاتي؛ يُعرض مفتاح X-App-Key مرة واحدة ويُخزَّن مُجزّأاً، وفقدانه يعني توليده من جديد (وموت المفتاح القديم فوراً).

يتحقق من صلاحية المفتاح ويعيد اسم التطبيق ومعرّفه وعدد العملاء — استعمله فحصاً صحياً لتكاملك.

const response = await fetch(`${BASE_URL}/api/v1/app/me`, {
  headers: { "X-App-Key": process.env.GATEWAY_APP_KEY }
});
const { app, clients } = await response.json();

دورة حياة المفتاح

باقات إعادة البيع والمحاسبة

8. تسجيل عملاء تطبيقك

{
  "phone": "500000000",
  "country_code": "966",
  "name": "Acme Store",
  "app_plan_id": "APPLICATION_PLAN_ID"   // optional at signup
}

رقم محلي مع رمز الدولة، أو رقم دولي كامل. ينشئ الطلب المستخدم والاشتراك في معاملة واحدة، ويعيد مفتاح api_key مرة واحدة جاهزاً للاستخدام فوراً:

{
  "client": { "id": "…", "phone": "+966500000000" },
  "subscription": { "status": "active", … },
  "api_key": "wsk_live_…",              // once only — store it
  "key_notice": "Store the key now — it will not be shown again",
  "phone_verified": false,               // becomes true at linking
  "message": "client registered under the app"
}

قاعدة صارمة: التطبيق يبيع باقاته هو فقط — طلب بباقة المنصة أو بباقة تطبيق آخر يُرفض بـ 400: «هذه الباقة ليست من باقات تطبيقك».

قائمة العملاء والباقات

يعيد plans (كتالوج إعادة البيع الخاص بك) وbase_plans (باقات المنصة، لمرجعك أنت — عملاؤك لا يشترونها). أنشئ باقاتك من لوحة العميل ← تطبيقاتي.

إسناد أو تجديد أو تغيير باقة العميل

curl -X POST "https://masarroute.com/api/v1/app/clients/CLIENT_ID/subscribe" \
  -H "X-App-Key: wsapp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"app_plan_id":"APPLICATION_PLAN_ID"}'

تجديد نفس الباقة يضيف المدة إلى نهاية الفترة الحالية. تغيير الباقة يبدأ فترة جديدة ويصفّر عدّاد الرسائل. عند انتهاء الحصة تتوقف الإرسال حتى التجديد أو ترقية الباقة.

طريقتان لتسجيل عميل تطبيقك — اختر واحدة

كلاهما يمنح المستخدم مفتاح wsk_live_…، والفرق في ما يثبت هويته وفي أين يجد رسالته إن فقد المفتاح.

من يتحمّل كلفة رسائل عملائك

القاعدة واحدة في كل مكان (الفحص والخصم معاً):

1. إن كان لعميلك باقة خاصة به ⇒ تُحتسب منها.
2. وإلا ⇒ تُحتسب من باقة صاحب التطبيق: رصيد واحد تشتريه أنت لتطبيقك كله.

لهذا يبقى رصيدك في لوحتك يَنقص مع كل رسالة يرسلها عملاؤك، ويرفض محرك الإرسال عند نفاده بـ QUOTA_EXCEUSTED. وحذف عميل لا يصفّر رصيدك — الاشتراك صف مستقلّ.

9. الشراء عبر Google Play

كتالوج عام لباقات تطبيقك

يقرأ تطبيقك باقاته دون أي مصادقة:

{
  "plans": [
    {
      "slug": "whatsapp_1000",     // = product_id in Google Play
      "name": "Plan 1000",
      "description": "1000 messages / month",
      "message_limit": 1000,
      "duration_days": 30,
      "price": 10,
      "device_limit": 5,
      "is_active": true,
      "original_price": 15,          // present only when discounted
      "discount_percent": 33,
      "discount_label": "limited-time offer"
    }
  ]
}

slug هو نفسه معرّف المنتج في Google Play، والتطابق حرفي: ما ترسله في product_id بعد الشراء يجب أن يساويه تماماً.

التخفيضات على باقاتك

باقة المنصة ملك المنصة وحدها ولا تُعرض للمطورين. باقات تطبيقك تسعّرها أنت، وتضبط التخفيض بحقل واحد: price (السعر النهائي) وdiscount_percent (النسبة 0–90). لا يُطلب منك إدخال السعر مرتين.

• السعر «قبل الخصم» original_price يُشتق في البوابة من النسبة والسعر النهائي، ويُستخدم للعرض فقط — يظهر مشطوباً في تطبيقك.
• نسبة بلا سعر نهائي تُرفض: خصم على لا شيء ليس تخفيضاً.
• إن أرسلت original_price صريحاً (من واجهة برمجية) يُحترم، من غيره تُرفض بـ 400 إن لم يطابق النسبة.
• discount_label نص حر اختياري يظهر في تطبيقك (حتى 60 حرفاً).
• نسبة 0 = لا تخفيض، ويُمسح السعر قبل الخصم حتى لا يبقى رقماً مكرراً في السجل.
• التخفيض على سعر البيع فقط: لا يمس التكلفة التي تدفعها للمنصة ولا الاشتراكات القائمة، ويظهر هامشك في /accounting.

final p = WhatsAppPlan.fromJson(item);
final discounted = p.discountPercent > 0 && p.originalPrice > p.price + 0.001;
// Render: struck old price + new price + percent badge

قواعد معرّف منتج Play

• يبدأ بحرف لاتيني صغير، ثم أحرف صغيرة وأرقام و _ و . فقط (٣-٦٣ حرفاً).
• بلا مسافات وبلا شرطات -.
• صحيح: whatsapp_1000 · com.zico.ledger.whatsapp_1000
• خاطئ: 300-m (شرطة) · 1000 (يبدأ برقم) · WhatsApp_1000 (حرف كبير)

من أين تجلبه: Play Console ← Monetization ← Products ← In-app products ← افتح المنتج وانسخ خانة Product ID كما هي، والصقها في حقل معرّف المنتج عند إنشاء باقة التطبيق من لوحة العميل. أي رمز غير مطابق يُرفض فوراً مع اقتراح تصحيح.

تفعيل الاشتراك بعد الشراء

بعد نجاح الشراء في Google Play، يرسل التطبيق طلباً بمفتاح العميل نفسه wsk_live_… (لا بمفتاح التطبيق):

curl -X POST "https://masarroute.com/api/v1/client/subscribe" \
  -H "X-API-Key: wsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"product_id":"whatsapp_1000",
       "purchase_token":"...",
       "obfuscated_external_account_id":"..."}'

// 1) verify the purchase with BillingClient, then:
// 2) send product_id + purchase_token
val body = JSONObject()
    .put("product_id", productId)                 // same slug as in the gateway
    .put("purchase_token", purchase.token)         // from BillingClient
    .put("obfuscated_external_account_id", obfId)  // optional obfuscated id
fetch("$BASE/api/v1/client/subscribe", Request(url, body)) {
    val data = JSONObject(it.readText())
    if (data.has("subscription")) enableSending()
}

• المنتج يجب أن يكون من باقات تطبيق العميل نفسه: لا يُفعَّل منتج تطبيق آخر ولا باقة منصة.
• الحماية من التكرار: نفس purchase_token لا يُفعَّل مرتين (يُعاد نفس الاشتراك مع already_active: true).
• عند التجديد تُضاف المدة إلى نهاية الفترة الحالية إن كان الاشتراك بنفس الباقة سارياً.
• الحدود المطبَّقة بعد التفعيل هي حدود باقة التطبيق (لا الباقة الأساسية).

10. جلسات وربط الأرقام

الجلسة تربط رقم واتساب واحد بالبوابة. دورة حياتها qr ← connecting ← connected، ويبقى jid فارغاً حتى يكتمل الربط. الواجهات الثلاث تعرض الأفعال نفسها — اختر البادئة المطابقة لبيان دخولك.

curl -X POST "https://masarroute.com/api/v1/app/clients/CLIENT_ID/sessions" \
  -H "X-App-Key: wsapp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"device_name":"Store sales"}'

قد يعيد الطلب رمز QR مباشرة أو رمزاً لاحقاً. استعمل الحقلين qr وqr_image. الصورة qr_image هي data URI مولدة داخل الخادم ولا تُرسل إلى أي موقع خارجي.

الربط بكود الهاتف بدلاً من QR

curl -X POST "https://masarroute.com/api/v1/app/sessions/SESSION_ID/connect-phone" \
  -H "X-App-Key: wsapp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"phone":"966500000000"}'

يعيد الطلب الحقل code أو connected:true، ثم يدخله المستخدم من واتساب ← الأجهزة المرتبطة ← ربط جهاز ← إدخال الكود. تابع status حتى يصبح connected.

راقب status وqr_generation وqr_error. عند تغيّر qr_generation حدّث الصورة. الرمز يتغير تلقائياً قبل انتهائه.

let generation = -1;
const timer = setInterval(async () => {
  const status = await api(`/sessions/${sessionId}/status`);
  if (status.status === "connected") { clearInterval(timer); return; }
  if (status.qr_generation !== generation) {
    generation = status.qr_generation;
    document.querySelector("#qr").src = status.qr_image;
  }
}, 1500);

التدفق الكامل للربط برقم الهاتف (من الجوال)

المسار المُختبَر في تطبيق عميل حقيقي، بالترتيب. ينطبق على أي تطبيق يربط عملاءه بالبوابة:

// 1) register the client with no plan (api_key comes back once — store it)
const client = await api("/app/clients", {
  method: "POST",
  body: { phone: "966500000000", country_code: "966", name: "Acme" }
});
await saveKeyOnce(client.api_key);           // never print, never log

// 2) reuse the stored session, or create one (device_limit = 1)
let session = (await api(`/app/clients/${client.id}/sessions`)).sessions
  .find(s => s.status !== "connected");
if (!session) session = await api(`/app/clients/${client.id}/sessions`, { method: "POST" });

// 3) request the pairing code — never call connect before it
const { code } = await api(`/app/sessions/${session.id}/connect-phone`, {
  method: "POST",
  body: { phone: "967782174050" }            // international, no +
});
    showCode(code);                               // user: Linked devices → Link device

// 4) poll status only — never re-request the code
const timer = setInterval(async () => {
  const s = await api(`/app/sessions/${session.id}/status`);
  if (s.status === "connected") {             // link + phone verified
    clearInterval(timer);
    await showLinkedNumber(s.jid);            // 966500000000:[email protected]
  }
  if (s.qr_error) { clearInterval(timer); showError(s.qr_error); }
}, 1500);

11. إرسال الرسائل

curl -X POST "https://masarroute.com/api/v1/app/messages/send" \
  -H "X-App-Key: wsapp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"session_id":"SESSION_ID","to":"966500000000","text":"Hello"}'

يمكن استخدام client_id بدل session_id، وعندها تستخدم البوابة أول جلسة متصلة للعميل. تمر الرسالة بمحرك الحماية والحصة قبل الإرسال.

إرسال صورة أو مستند

‏multipart/form-data — الملف يُرفع مباشرة من التطبيق إلى البوابة، ثم إلى واتساب، ولا يُخزَّن على القرص.

curl -X POST "https://masarroute.com/api/v1/client/messages/send-media" \
  -H "X-API-Key: wsk_live_..." \
  -F "session_id=SESSION_UUID" \
  -F "to=967700000001" \
  -F "type=image" \
  -F "caption=Payment receipt" \
  -F "[email protected];type=image/png"

الصور المسموحة: JPEG · PNG · WEBP. المستندات: PDF · Word · Excel · PowerPoint · TXT · CSV.

الإرسال الجماعي

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

curl -X POST "https://masarroute.com/api/v1/client/messages/send-batch" \
  -H "X-API-Key: wsk_live_..." \
  -H "Idempotency-Key: batch-2026-09-27-morning" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"SESSION_UUID","items":[
        {"to":"967700000001","text":"Invoice 1042"},
        {"to":"967700000002","text":"Invoice 1043"}
      ]}'

الحد الأقصى 100 عنصر. الفشل الجزئي مقصود: رسالة فشلت لرقم لا تلغي البقية.

{
  "code": "OK",
  "total": 3,
  "succeeded": 2,
  "failed": 1,
  "overall_success": false,
  "results": [
    { "to": "967700000001", "ok": true,  "wa_message_id": "STG7D303278FCB129C7" },
    { "to": "967700000002", "ok": true,  "wa_message_id": "STG44A1B0C9D2E7F35" },
    { "to": "", "ok": false, "code": "INVALID_ITEM",
      "error": "fields to and text are required for every item" }
  ]
}

منع الإرسال المزدوج — Idempotency-Key

تطبيق بلا خادم يعيد الإرسال بعد انقطاع الشبكة. بدون حماية تصل الرسالة مرتين وتُحتسب مرتين — وهو أسرع طريق لإلغاء الرقم من واتساب.

أضف ترويسة Idempotency-Key بقيمة فريدة لكل عملية منطقية (استخدم معرّفاً تولّده أنت، لا معرّفاً عشوائياً جديداً كل محاولة):

curl -X POST "https://masarroute.com/api/v1/client/messages/send" \
  -H "X-API-Key: wsk_live_..." \
  -H "Idempotency-Key: invoice-1042-2026-09-27" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"SESSION_UUID","to":"967700000001","text":"Invoice 1042"}'

الطلبات الفاشلة لا تُخزَّن، فإعادة المحاولة ممكنة بحرية. مدة التخزين 24 ساعة، والمفتاح العالق يُستردّ تلقائياً بعد دقيقتين.

حالة التسليم بلا webhooks

‏webhooks تحتاج رابطاً عاماً، أي خادماً — وهو عكس نموذج تطبيق بلا خادم. هذه النقطتان تعطيانك نفس المعلومة بالاستقصاء من داخل التطبيق.

curl -X POST "https://masarroute.com/api/v1/client/messages/status" \
  -H "X-API-Key: wsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"ids":["W1","W2","W3"]}'

{
  "code": "OK",
  "requested": 3,
  "found": 2,
  "messages": [
    { "wa_message_id": "W1", "to": "967700000001", "type": "image",
      "status": "delivered", "created_at": "2026-09-27T05:10:00Z",
      "delivered_at": "2026-09-27T05:10:31Z" },
    { "wa_message_id": "W2", "to": "967700000002", "type": "text",
      "status": "read", "created_at": "2026-09-27T05:10:00Z",
      "delivered_at": "2026-09-27T05:10:28Z",
      "read_at": "2026-09-27T05:12:04Z" }
  ],
  "missing": ["W3"]
}

الحالات: sent · delivered · read · staged (وضع الاختبار) · blocked_safety مع error.

200  active subscription
401  UNAUTHORIZED           key missing or expired
402  NO_ACTIVE_PLAN         phone not verified yet
402  SUBSCRIPTION_INACTIVE  subscription ended or blocked
429  QUOTA_EXCEUSTED        quota exhausted (with Retry-After)

12. إشعارات التسليم (Webhooks)

بدل polling، سجّل رابطاً واستقبل إشعاراً عند كل تغيير حالة.

curl -X POST "https://masarroute.com/api/v1/client/webhooks" \
  -H "X-API-Key: wsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://my-app.example/hook","events":"sent,delivered,read"}'

الأحداث المتاحة: sent · delivered · read · failed — أو * للكل. الرد يعيد secret مرة واحدة فقط.

POST /hook
X-Gateway-Event: delivered
X-Gateway-Delivery: 4f2a…            ← unique id per delivery attempt
X-Gateway-Signature: sha256=ab73…    ← HMAC-SHA256 of the body below

{
  "event": "delivered",
  "wa_message_id": "STG7D303278FCB129C7",
  "to": "967700000001",
  "session_id": "b0cd44b0-…",
  "user_id": "17647a33-…",
  "timestamp": "2026-09-27T05:14:22Z"
}

إدارة الاشتراكات:

GET    /api/v1/client/webhooks              list subscriptions
POST   /api/v1/client/webhooks/:id/toggle   enable / disable
DELETE /api/v1/client/webhooks/:id          delete

البوابة تقبل http:// وhttps:// فقط، ولها مهلة 8 ثوانٍ. الرد برمز حالة ≥ 300 يُسجَّل في سجل الخادم.

13. محرك الحماية والحدود

كل رسالة تعبر محرك الحماية والحصة قبل أن تخرج. المحرك موجود لإبقاء الأرقام حيّة: واتساب يحظر الحسابات التي تتصرف كالروبوتات، لذا تفرض البوابة قواعد الحجم والتكرار والإحماء — مع رمز مستقل لكل رفض.

حدود المعدل

14. رموز الأخطاء 79

كل فشل تعيده البوابة يحمل ظرفاً واحداً: رمزاً آلياً ثابتاً، ورسالة إنسانية، وrequest_id تستدعيه عند التواصل مع الدعم. الحالة HTTP وحدها ليست ما تتفرّع عليه — تفرّع على الرمز.

{
  "code": "RATE_LIMITED",
  "message": "too many requests",
  "error": "تجاوزت حد الطلبات",
  "request_id": "b31f9c2e-…",
  "retry_after": 60
}

‏request_id يعود أيضاً في ترويسة X-Request-Id، وكل 429 يحمل Retry-After. هذا الجدول موثّق آلياً: كل رمز هنا موجود في شيفرة البوابة، وكل رمز ترسله البوابة موجود هنا — نسيان أحدهما يُسقط الاختبارات.

مدخلات غير صالحة

الطلب مرفوض قبل أي معالجة. صحّح البيانات وأعد.

المصادقة والاشتراك والحصة

هنا يقرّر التطبيق سلوكه: «سجّل الدخول» / «اشترِ باقة» / «انتظر» / «نفدت باقتك».

لا يوجد

المورد غير موجود — حدّث الحالة قبل إعادة المحاولة.

خدمة AI Models API

أخطاء بوابة AI ‏(POST /api/v1/chat وPOST /api/v1/chat/completions بمفاتيح sk_): الباقة، الحصة، النموذج، وفشل المزود الخارجي.

تعارض

لا تكرّر الطلب؛ إما أنه نُفّذ أو يحتاج تغيّراً.

خطأ خادم

سجّل request_id وأعد المحاولة بتدرّج.

15. واجهة العميل — /api/v1/client

مصفوفة لتطبيقات الهاتف التي لا تملك خادماً: كل مستخدم يدير جلسته وحصته بنفسه بمفتاح wsk خاص به. لا يحتاج التطبيق إلى X-App-Key ولا إلى أي خادم وسيط — الهاتف يتحدث مع البوابة مباشرة.

المصادقة: تسجيل واسترجاع في نقطة واحدة

لا يوجد أي مفتاح داخل حزمة التطبيق. البرهان على ملكية الرقم هو استقبال كود على واتساب — وهذا ما يجعل التسجيل الوهمي بلا قيمة، ويعالج فقدان المفتاح عند إعادة التثبيت.

curl -X POST "https://masarroute.com/api/v1/client/auth/otp" \
  -H "Content-Type: application/json" \
  -d '{"phone":"772935010","country_code":"967"}'

يردّ بـ action يحدّد ما يعرضه التطبيق:

curl -X POST "https://masarroute.com/api/v1/client/auth/verify" \
  -H "Content-Type: application/json" \
  -d '{"phone":"772935010","country_code":"967","code":"482913",
       "name":"Zakaria",
       "app_key":"wsapp_live_..."}'

الرد يعيد api_key مرة واحدة فقط. وعند action: "recover" تكون المفاتيح القديمة مبطلة — وهو بالضبط ما تحتاجه بعد إعادة التثبيت.

إدارة المفاتيح — مخرج التسرّب

الاستجابة لا تكشف إلا البادئة (key_prefix) — لا تُعاد المفاتيح كاملة ولا الـ hash.

curl -X POST "https://masarroute.com/api/v1/client/keys/rotate" \
  -H "X-API-Key: wsk_live_..."

يعيد مفتاحاً جديداً ويُبطل القديم فوراً. العملية محميّة من الإبطال الذاتي: لا يمكنك إبطال المفتاح المستخدم في هذا الطلب، ولا كل مفاتيحك دفعة واحدة وإلا لا يبقى وسيلة للدخول.

عزل المستأجرين

كل wsk يرى جلساته ورسائله وحصته وحده. طلب جلسة أو رسالة لا يملكها يُرجع 404 — لا نكشف وجودها. والجلسة الرئيسية (مرسل OTP) لا تظهر أبداً في هذه الواجهة.

16. فهرس المسارات الكامل 178

كل عملية تُسجّل فعلاً في البوابة، مرتّبة حسب المجال. الصفوف لغتها محايدة عن قصد: الطريقة والمسار وبيان الدخول المطلوب. أما أشكال الطلبات والمعاملات ومخططات البيانات ففي المواصفة الآلية أدناه.

curl https://masarroute.com/openapi.json | jq ".paths | keys | length"

العمليات الأساسية 6

صفحات HTML 7

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

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

الاشتراك والحصة 6

الجلسات والربط 28

الرسائل 13

إشعارات التسليم 4

واجهة التطبيق 7

عملاء التطبيق 8

الإدارة 67

أخرى 1

17. واجهة نماذج الذكاء الاصطناعي — توثيق مستقل

للجانب AI في المنصة بيت خاص: توثيق مستقل بفهرس 30 عملية وأمثلة جاهزة للنسخ بلغات PHP وLaravel وNode وPython؛ وصفحة أسعار مستقلة بباقات رصيد حيّة وأسعار النماذج لكل مليون توكن؛ وصفحة أسئلة شائعة. ولم يعد شيء عن AI هنا — هذا المرجع خالص لواتساب.

18. للآلة والذكاء الاصطناعي

هذا القسم للأدوات والوكلاء والمولّدات. البوابة تنشر مصدر حقيقة واحد بثلاثة أوجه متزامنة: هذه الصفحة للبشر، وGET /openapi.json للآلة، وحزمة اختبارات تسقط البناء إن اختلفت الثلاثة.

كيف يبدأ الوكيل

1. احصل على /openapi.json أولاً — فيه الـ 214 عملية كاملة، وبيان الدخول لكل عملية (مصفوفة فارغة = عام)، ومخططات الوسائط، و enum لكل رموز الأخطاء الـ 79.
2. أرسل بيانات الدخول المُعلنة على العملية تحديداً — أي مخطط خاطئ يُرفض قبل تشغيل أي معالج.
3. تفرّع على body.code لا على الحالة HTTP. وفي 429 التزم بـ Retry-After (وأيضاً retry_after) قبل إعادة المحاولة.
4. أرسل Idempotency-Key مع أي إرسال قد تعيد المحاولة فيه — فيصبح الإعادة بلا خطر تضاعف.
5. اذكر request_id عند طلب المساعدة من البشر — إنه مفتاح فهرس سجلات الخادم.

const spec = await fetch("https://masarroute.com/openapi.json").then(r => r.json());
const send = spec.paths["/api/v1/messages/send"].post;
console.log(send.security);          // [{ apiKeyHeader: [] }]
console.log(spec.components.schemas.Error.properties.code.enum.length); // 79

19. قواعد الأمان

1. خزّن المفاتيح في Secret Manager أو متغير بيئة على الخادم — لا في المستودع أبداً.
2. لا ترسل المفتاح إلى المتصفح أو حزم تطبيقات الهاتف؛ البيانات الوحيدة في العميل هي مفتاح المستخدم wsk المُنشأ وقت التشغيل.
3. راقب last_used_at واستبدل المفتاح فور أي تسريب مشتبه به (تدوير للعميل، توليد للتطبيق).
4. طبّق idempotency بمعرّف طلب خاص بك حتى لا تتكرر الرسالة أبداً.
5. ضع حدوداً خاصة بإرسالاتك ولا تُعد الإرسال عشوائياً بعد المهلة — استقصِ الحالة بدلاً من ذلك.
6. استخدم HTTPS في كل بيئة الإنتاج، وأبقِ التسجيل العام مطفأً إن لم تكن بحاجته.
7. تحقّق من توقيعات webhooks (HMAC-SHA256) قبل ثقة أي محتوى — انظر القسم 12.
8. ‏X-Bootstrap-Key بنية خادمية فقط؛ تسريبه داخل تطبيق يعني تسريب مسار التسجيل للعالم كله.
9. الدخول للإدارة على /zico خلف JWT وflag المدير — ولا تعرض رموز الإدارة لشيفرة غير المدراء.