تخطَّ إلى المحتوى

أهلاً بيك في ميرور

سجّل دخولك لمتابعة طلباتك واشتراكاتك ورصيد محفظتك.

هدية في محفظتك عند إنشاء حساب جديد

تسجيل الدخول إنشاء حساب جديد
تواصل عبر واتساب

شروحات ودلائل

إرسال WhatsApp وSMS والبريد عبر Mersal API باستخدام PHP

قراءة في 4 دقائق

Mersal API PHP — MirrorORG

ربط نظامك بمنصة رسائل يبدو سطرًا واحدًا: طلب POST ثم رد 200. لكن التكامل الذي يعمل سنوات يحتاج أكثر: مفتاحًا لا يظهر في الكود، وتحققًا من الرقم قبل الإرسال، ومعالجة لأخطاء التحقق والاشتراك، وإعادة محاولة لا ترسل الرسالة مرتين. هذا الدليل يبني عميلًا صغيرًا لـ Mersal API بلغة PHP يرسل واتساب وSMS والبريد، ويتعامل مع كل حالة يعيدها الخادم كما يصفها التوثيق.

قواعد التكامل

  • المفتاح يُرسل في ترويسة Api-key، لا بصيغة Bearer؛ صيغة Bearer مخصصة لبوابة الذكاء الاصطناعي بمفتاح مختلف.
  • رد 2xx يعني أن الرسالة قُبلت ودخلت الطابور، لا أنها سُلّمت؛ التسليم يُعرف من Webhooks أو واجهات الاستعلام.
  • أعد المحاولة فقط عند أخطاء 5xx وانقطاع الشبكة، وبفواصل متزايدة، ولا تعد المحاولة على 403 أو 422.

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

المسارالحقول الأساسية لكل مستلمحقول اختيارية
POST /api/sms/sendnumber, messagegateway_identifier, schedule_at
POST /api/whatsapp/sendnumber, messagemedia (image أو audio أو video أو document) مع url، وfilename
POST /api/email/sendemail, subject, message (يقبل HTML)sender_name, reply_to_email، ومرفقات
GET /api/get/{channel}/{id?}حالة رسالة محددة، أو آخر الرسائل للقناة إذا حُذف المعرّف

العنوان الأساسي للواجهة https://mersal.it/api، وكل الطلبات والردود بصيغة JSON. وكل واجهات الإرسال تقبل مصفوفة contact، فيمكن إرسال عدة رسائل في طلب واحد، وهو ما يوصي به التوثيق للدفعات الكبيرة بدل طلب لكل مستلم.

خطوات التنفيذ

  1. 1

    أنشئ المفتاح واحفظه في متغير بيئة

    المفتاح في إعدادات الحساب ← صفحة API، ويمكن إعادة توليده. من يملكه يستطيع الإرسال من رصيدك، فلا تضعه في الكود أو المستودع أو أي ملف يصل إليه المتصفح.

  2. 2

    طبّع الرقم قبل الإرسال

    حوّل الأرقام إلى الصيغة الدولية بعلامة + قبل بناء الطلب، وارفض ما لا يطابق. خطأ 422 من الخادم يعني أنك أرسلت حقلًا ناقصًا أو غير صالح.

  3. 3

    سجّل الطلب قبل إرساله

    احفظ في قاعدتك سجلًا بمفتاح فريد مثل «طلب 1042 ← تأكيد»، وحدّثه بالنتيجة. إذا تكرر الحدث نفسه، يمنعك السجل من الإرسال مرة ثانية.

  4. 4

    أرسل وعالج الرد

    الكود التالي (PHP 8 أو أحدث) يغطي النجاح وأخطاء التحقق والمفتاح وأخطاء الخادم.

php
<?php
final class MersalClient {
	private const BASE = 'https://mersal.it/api';

	public function __construct( private string $key ) {}

	/** يرسل دفعة رسائل لقناة: sms أو whatsapp أو email. */
	public function send( string $channel, array $contacts, int $tries = 4 ): array {
		$body = json_encode( array( 'contact' => $contacts ), JSON_UNESCAPED_UNICODE );
		for ( $i = 0; $i < $tries; $i++ ) {
			$ch = curl_init( self::BASE . "/$channel/send" );
			curl_setopt_array( $ch, array(
				CURLOPT_POST           => true,
				CURLOPT_RETURNTRANSFER => true,
				CURLOPT_TIMEOUT        => 20,
				CURLOPT_HTTPHEADER     => array( 'Api-key: ' . $this->key, 'Content-Type: application/json' ),
				CURLOPT_POSTFIELDS     => $body,
			) );
			$raw  = curl_exec( $ch );
			$code = (int) curl_getinfo( $ch, CURLINFO_HTTP_CODE );
			curl_close( $ch );
			$json = json_decode( (string) $raw, true ) ?: array();

			if ( $code >= 200 && $code < 300 ) {
				return array( 'ok' => true, 'data' => $json['data'] ?? array() ); // queued أو scheduled
			}
			if ( 422 === $code ) {
				return array( 'ok' => false, 'fix' => $json['errors'] ?? array() ); // مثل contact.0.number
			}
			if ( 403 === $code ) {
				return array( 'ok' => false, 'auth' => $json['error'] ?? 'forbidden' ); // مفتاح أو اشتراك
			}
			// 5xx أو انقطاع: انتظار متزايد مع عشوائية صغيرة
			usleep( ( 2 ** $i ) * 1000000 + random_int( 0, 300000 ) );
		}
		return array( 'ok' => false, 'retry_later' => true );
	}
}

$mersal = new MersalClient( getenv( 'MERSAL_API_KEY' ) );
$result = $mersal->send( 'whatsapp', array(
	array(
		'number'   => '+201012345678',
		'message'  => 'فاتورة طلبك #1042 مرفقة.',
		'media'    => 'document',
		'url'      => 'https://example.com/invoices/1042.pdf',
		'filename' => 'invoice-1042.pdf',
	),
) );
403 قد لا يكون المفتاحواجهات الإرسال تعيد 403 أيضًا إذا انتهى اشتراك الحساب، برسالة «Your Subscription Is Expired»، حتى لو كان المفتاح صحيحًا. سجّل نص الخطأ كما هو، وأرسل تنبيهًا لفريقك بدل إعادة المحاولة.

بعد الإرسال: الحالة الحقيقية

  • Webhooks: الأفضل. سجّل نقطة استقبال في لوحة مرسال لتصلك أحداث التسليم والفشل والردود فور حدوثها، وهو موضوع المقال التالي في السلسلة.
  • الاستعلام:GET /api/get/whatsapp يعيد آخر الرسائل، ومع المعرّف يعيد رسالة واحدة. مفيد للمراجعة لا للمتابعة المستمرة.
  • الجدولة: للدفعات الكبيرة المتوقعة، مثل نشرة شهرية، وزّع التسليم بحقل schedule_at بصيغة Y-m-d H:i:s بدل إطلاق كل شيء في لحظة.

أسئلة المطورين

هل أستخدم مفتاح الـ API نفسه لبوابة الذكاء الاصطناعي؟
لا. بوابة الذكاء الاصطناعي تستخدم مفتاح AI Pool منفصلًا بترويسة Authorization: Bearer، ولا يعمل أي من المفتاحين مكان الآخر. إذا ظهر 403 Invalid Api Key فتأكد من نوع المفتاح.
كيف أختار بوابة معينة للإرسال؟
أضف gateway_identifier لكل مستلم بمعرّف البوابة، مثل اتصال Cloud API محدد أو هاتف أندرويد. بدونه تُستخدم البوابة الافتراضية النشطة لحسابك.
هل يمكن إرسال المفتاح في الرابط؟
التوثيق يقبله كمعامل api_key احتياطيًا، لكن الروابط تُحفظ في سجلات الخوادم والوسطاء. استخدم الترويسة دائمًا.

مقالات مرتبطة

مرجع الواجهة

نظرة عامة والمصادقة والأخطاء وحدود المعدل في توثيق مرسال. تمت مراجعتها 18 أكتوبر 2026.

ادمج نظامك مع Mersal API

واجهات مستقلة لواتساب وSMS والبريد بمصفوفة مستلمين وجدولة واختيار بوابة، وأحداث تسليم وردود تصل إلى خادمك.

اشتراك مرسال للمطورين

شارك المقال

اترك تعليقاً

لن يتم نشر عنوان بريدك الإلكتروني. الحقول الإلزامية مشار إليها بـ *