مرجع واجهة مسار

أرسل قوالب واتساب من نظامك أنت.

English

واجهة REST واحدة فوق المحرّك نفسه الذي تستخدمه لوحة التحكم. لا يوجد مسار ثانٍ إلى المستلم: الخصم والحصة ومنع التكرار وحجز الإرسال متطابقة سواء أُرسلت الرسالة من شاشة أو من كودك.

العنوان الأساسي: https://router.atyaf.co/api/v1

المصادقة

أرسل مفتاحك كرمز Bearer في كل طلب. المفتاح هو ما يحدّد الحساب — لا يقبل أي مسار معرّف حساب، وأي عنصر يخص حساباً آخر يجيب 404.

curl https://router.atyaf.co/api/v1/me \
  -H "Authorization: Bearer msr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

المفتاح يبدأ بـ msr_live_ ثم 48 حرفاً ثم 6 أحرف تدقيق. شرطات سفلية لا وسطية: الشرطة السفلية ليست حرفاً في Base64، فلا يمكن أن يُخطئ أحد بين بصمة عشوائية ومفتاح حقيقي.

يُعرض المفتاح مرة واحدة عند الإنشاء ويُحفظ كبصمة SHA-256 فقط. لا يمكن استرجاعه — إن فُقد فأبطِله وأنشئ غيره.

يمكن تقييد المفتاح بقائمة عناوين وتحديد تاريخ انتهاء له. كلاهما يُرفض عند المصادقة، قبل أي خصم.

الصلاحيات

كل مسار يطلب صلاحية واحدة. امنح المفتاح ما يحتاجه تكامله فقط — مفتاح للتقارير بلا messages:send لا يستطيع استهلاك رصيدك، فتسريبه ليس طارئاً.

الأخطاء

كل إخفاق يعود بالغلاف نفسه ورمز ثابت. ابنِ منطقك على الرمز لا على حالة HTTP ولا على نص الرسالة: كثير من الرفوض تتشارك الحالة وتختلف علاجاتها، ونص الرسالة مترجم وقابل لإعادة الصياغة.

{
  "error": {
    "code": "scope_missing",
    "message": "…",
    "request_id": "req_1a2b3c…",
    "required_scope": "messages:send"
  }
}

كل استجابة تحمل ترويسة Masar-Request-Id، وتتكرّر داخل جسم الخطأ. اذكرها في طلب الدعم فتقودنا إلى طلب واحد بعينه في سجلّك.

حدود المعدّل

الحدود لكل مفتاح ولكل دقيقة، لا لكل عنوان IP — عميلان خلف اتصال مكتب واحد لا يتشاركان الحصة. كل استجابة تحمل X-RateLimit-Limit وX-RateLimit-Remaining، والرفض يحمل Retry-After.

القراءة والكتابة عدا الإرسال	600 في الدقيقة
POST /v1/messages	120 في الدقيقة

منع التكرار

كل طلب كتابة ينفق مالاً أو لا يمكن التراجع عنه يحتاج ترويسة Idempotency-Key: ‏POST /v1/messages و POST /v1/campaigns وبدء الحملة وإيقافها واستئنافها وإلغاؤها. أي نص فريد يكفي، وUUID لكل طلب هو الخيار المعتاد.

وهي إلزامية لا اختيارية لأن الخصم المكرّر يُعالَج باسترداد، أما القالب المكرّر على واتساب فيُعالَج ببلاغ من المستلم — وتقييم جودة الرقم لا يتعافى.

• المفتاح نفسه بالمحتوى نفسه: يُعاد جواب الطلب الأول مع الترويسة Idempotent-Replayed: true، ولا يُرسل ولا يُخصم شيء ثانية.
• المفتاح نفسه بمحتوى مختلف: 422 idempotency_conflict. هذا يمسك الخطأ الشائع — مفتاح واحد يُعاد استخدامه داخل حلقة؛ فالإعادة الصامتة تعني ألا يصل شيء لكل المستلمين بعد الأول بينما تجيب الواجهة 200.
• المفتاح نفسه والطلب الأول ما زال يُعالَج: 409 idempotency_in_flight. أعد المحاولة بعد لحظة.

تُؤخذ بصمة المحتوى على الرقم بعد التوحيد، فإعادة المحاولة بصيغة رقم مختلفة تُعيد الجواب بدل أن تتعارض.

المسارات

مواصفة OpenAPI

هذه الواجهة كاملة منشورة كمستند OpenAPI 3.1 على رابط ثابت. وجّه أي مولّد إليه لتحصل على عميل مكتوب بلغتك بدل عميل يدوي يتخلّف عن الواجهة مع الوقت.

https://router.atyaf.co/docs/openapi.json

يُعاد توليد المستند من المسارات الحيّة مع كل إصدار، فما هو موجود موصوف وما هو موصوف موجود. المصادقة Bearer على كل عملية، ولا يقبل أي مسار معرّف حساب.

إرسال رسالة

قالب معتمد واحد إلى مستلم واحد. الجواب 202 مع الرسالة في الطابور؛ ويصلك التسليم عبر الويب هوك أو بقراءة الرسالة.

curl

curl -X POST https://router.atyaf.co/api/v1/messages \
  -H "Authorization: Bearer $MASAR_KEY" \
  -H "Idempotency-Key: order-1234" \
  -H "Content-Type: application/json" \
  -d '{
        "to": "+970599123456",
        "template_id": 12,
        "variables": ["Ahmad", "1234"]
      }'

HTTP/1.1 202 Accepted
Masar-Request-Id: req_1a2b3c…
X-RateLimit-Remaining: 119

{
  "data": {
    "id": 8417,
    "to": "+970599123456",
    "status": "queued",
    "dispatch_state": "pending",
    "price_microusd": 18100,
    "price": "0.0181"
  }
}

الرمز 202 يعني «خُصم ودخل الطابور» لا «سُلّم». يُخصم الرصيد قبل الإرسال، لأن خصماً لرسالة لم تخرج يُصلحه استرداد، أما رسالة خرجت ولم تُخصم على أحد فلا يصلحها شيء.

PHP

<?php

$response = Http::withToken($key)
    ->withHeaders(['Idempotency-Key' => 'order-1234'])
    ->post('https://router.atyaf.co/api/v1/messages', [
        'to' => '+970599123456',
        'template_id' => 12,
        'variables' => ['Ahmad', '1234'],
    ]);

if ($response->header('Idempotent-Replayed') === 'true') {
    // This retry sent nothing and charged nothing. The body is the
    // original call's answer.
}

$messageId = $response->json('data.id');

الويب هوك

نرسل الأحداث موقّعة إلى رابطك عبر POST. التسليمات تتبع Standard Webhooks، فأي مكتبة متوافقة تتحقّق منها دون كود خاص.

ثلاث ترويسات ترافق كل تسليم:

webhook-id	msg_…
webhook-timestamp	1767225600
webhook-signature	v1,<base64> v1,<base64>

التوقيع هو HMAC-SHA256 على المعرّف والطابع الزمني والجسم الخام موصولة بنقاط — تحقّق من البايتات كما وصلتك تماماً، لا من كائن أعدتَ ترميزه.

signed = webhook-id + "." + webhook-timestamp + "." + raw_body
signature = base64(hmac_sha256(signed, base64_decode(secret_without_prefix)))

ارفض أي تسليم يبعد طابعه الزمني أكثر من 300 ثانية عن ساعتك. التوقيع يبقى صالحاً إلى الأبد بعد التقاطه، وهذه النافذة هي ما يمنع إعادة إرساله إليك لاحقاً.

يمكن أن يكون هناك مفتاحان فعّالان معاً. أثناء التدوير تحمل ترويسة التوقيع توقيعاً لكل مفتاح مفصولين بمسافة، ويُقبل التسليم إذا طابق أيّهما — فتضيف الجديد، وتتأكد أن التحقق ما زال ينجح، ثم تُنهي القديم في وقتك أنت.

التحقق من تسليم

<?php

/**
 * Verify one Masar delivery.
 *
 * $body MUST be the raw request body, exactly as received. Decoding it to
 * an array and re-encoding produces different bytes — a space, a unicode
 * escape, a key order — and the signature will never match again.
 */
function masar_webhook_is_valid(string $body, array $headers, array $secrets): bool
{
    $id        = $headers['webhook-id'] ?? '';
    $timestamp = (int) ($headers['webhook-timestamp'] ?? 0);
    $offered   = $headers['webhook-signature'] ?? '';

    // Replay window first. A signature stays valid forever once captured.
    if ($timestamp <= 0 || abs(time() - $timestamp) > 300) {
        return false;
    }

    $signed = $id . '.' . $timestamp . '.' . $body;

    foreach (preg_split('/\s+/', trim($offered)) as $candidate) {
        foreach ($secrets as $secret) {
            $key = base64_decode(substr($secret, strlen('whsec_')), true) ?: $secret;
            $mine = 'v1,' . base64_encode(hash_hmac('sha256', $signed, $key, true));

            // hash_equals, never ===: a comparison that short-circuits leaks
            // the position of the first wrong byte.
            if (hash_equals($mine, $candidate)) {
                return true;
            }
        }
    }

    return false;
}

الأحداث

كل حدث يُرسَل مرة واحدة لكل واقعة. انتقال الحالة من «أُرسِلت» إلى «وصلت» إلى «قُرِئت» ثلاث تسليمات، والإشعار الذي يكرّره المزوّد يبقى واحداً.

الحدث	متى يُرسَل
message.accepted	خُصِم ثمنها ودخلت الطابور. تُرسَل للإرسال المفرد عبر الواجهة ولكل مستلم في الحملة، وإعادة الطلب بالمفتاح نفسه لا تنتج حدثاً ثانياً.
message.sent	سُلِّمت إلى واتساب وقبِلها. معرّف الرسالة لدى المزوّد موجود من هنا فصاعداً.
message.delivered	أقرّ جهاز المستلم باستلامها.
message.read	فتحها المستلم. فقط لمن يفعّل إشعارات القراءة.
message.failed	لن تصل، وأي مبلغ خُصِم أُعيد. تُرسَل سواء رفض المزوّد الإرسال فوراً، أو أبلغ عن الفشل لاحقاً، أو توقّفنا نحن عن المحاولة.
template.approved	صار القالب قابلاً للإرسال. تُرسَل سواء وصل الحكم عبر ويب هوك من ميتا أو اكتشفته مطابقة الفهرس عندنا.
template.rejected	لن يُرسَل القالب، والجسم يحمل السبب. رفض مراجعنا نحن يُحتسب رفضاً.
channel.quality_changed	تغيّر تقييم الجودة أو مستوى الإرسال الذي تحتفظ به ميتا لأحد أرقامك. الجسم يصف الرقم كما هو الآن.
wallet.low_balance	الرصيد دون حدّ الشحن التلقائي الذي حدّدته، أو دون ما أنفقته الأسبوع الماضي، مع اليوم الذي يصل فيه إلى الصفر بالوتيرة الحالية. مرة واحدة يومياً على الأكثر.

أنشئ مفتاحاً من لوحة التحكم