المصادقة
كيفية المصادقة لطلبات إرسال القنوات وطلبات بوابة الذكاء الاصطناعي.
تستخدم واجهة برمجة تطبيقات Mersal آليتي مصادقة منفصلتين، حسب عائلة النقاط الطرفية التي تستدعيها. تستخدم كل آلية نوعًا مختلفًا من المفاتيح يُنشأ في مكان مختلف من لوحة التحكم، ولا يمكن استخدام أحدهما بدلاً من الآخر.
نقاط إرسال القنوات (Api-key)
تتم مصادقة POST /api/sms/send و POST /api/whatsapp/send و POST /api/email/send، بالإضافة إلى نقاط الاستعلام GET /api/get/{channel}/{id?} المرتبطة بها، باستخدام مفتاح API الشخصي الخاص بك. تبحث Mersal عن المفتاح بالترتيب التالي:
- الترويسة
Api-key: <your-api-key>(موصى به) - معامل الرابط
?api_key=<your-api-key> - حقل نص الطلب
api_key
ليس رمز Bearer
اسم الترويسة هو فعليًا Api-key، وليس Authorization: Bearer. لا تستخدم أسلوب رمز Bearer مع نقاط إرسال القنوات — هذا الأسلوب مخصص لبوابة الذكاء الاصطناعي فقط.
إيجاد مفتاح API الخاص بك
افتح إعدادات حسابك
سجّل الدخول إلى لوحة تحكم مرسال وافتح إعدادات الحساب.
افتح صفحة API key
ستجد مفتاح API الشخصي الخاص بك معروضاً هناك، مع إمكانية إعادة توليده في أي وقت.
خزّنه بشكل آمن
تعامل معه كأنه كلمة مرور — أي شخص يملك هذا المفتاح يمكنه إرسال رسائل واستهلاك رصيد الإرسال في حسابك. خزّنه في متغير بيئة وليس داخل الكود. راجع إدارة مفاتيح API.
مثال بكل اللغات
curl -X POST https://mersal.it/api/sms/send \
-H "Api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contact":[{"number":"+201234567890","message":"Hello from Mersal"}]}'<?php
$ch = curl_init('https://mersal.it/api/sms/send');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Api-key: ' . getenv('MERSAL_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'contact' => [
['number' => '+201234567890', 'message' => 'Hello from Mersal'],
],
]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);const response = await fetch("https://mersal.it/api/sms/send", {
method: "POST",
headers: {
"Api-key": process.env.MERSAL_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
contact: [{ number: "+201234567890", message: "Hello from Mersal" }],
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://mersal.it/api/sms/send",
headers={"Api-key": os.environ["MERSAL_API_KEY"]},
json={"contact": [{"number": "+201234567890", "message": "Hello from Mersal"}]},
)
data = response.json()متطلبات الاشتراك
تتطلب نقاط إرسال القنوات وجود اشتراك/باقة فعّالة على حسابك. إذا انتهت صلاحية باقتك، ستُرجع كل الطلبات الحالة 403 بغض النظر عن صحة مفتاح API نفسه:
{
"status": "error",
"error": "Your Subscription Is Expired! Buy A New Plan"
}بوابة الذكاء الاصطناعي (رمز Bearer)
تستخدم POST /api/ai/v1/chat/completions و GET /api/ai/v1/models نوعًا مختلفًا من المفاتيح: مفتاح AI Pool، يُنشأ خصيصًا للوصول إلى بوابة الذكاء الاصطناعي، ويُرسل كرمز Bearer قياسي:
Authorization: Bearer <ai-pool-key>curl https://mersal.it/api/ai/v1/chat/completions \
-H "Authorization: Bearer YOUR_AI_POOL_KEY" \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"Hello"}]}'تُنشأ مفاتيح AI Pool بشكل منفصل عن مفتاح API الخاص بالقنوات — ابحث عن قسم AI Pool / AI Gateway في لوحة التحكم. راجع بوابة الذكاء الاصطناعي: إكمالات المحادثة للاطلاع على عقد الطلب/الاستجابة الكامل.
استجابات الأخطاء
| الحالة | رمز الحالة | المحتوى |
|---|---|---|
| مفتاح API مفقود (نقاط القنوات) | 403 | {"status":"error","message":"API key is required. Provide via header (Api-key) or URL parameter (api_key)","error":"Invalid Api Key"} |
| مفتاح API غير صالح (نقاط القنوات) | 403 | {"status":"error","error":"Invalid Api Key"} |
| انتهاء صلاحية الاشتراك | 403 | {"status":"error","error":"Your Subscription Is Expired! Buy A New Plan"} |
للاطلاع على القائمة الكاملة لاتفاقيات الأخطاء، راجع الأخطاء ورموز الحالة.