المصادقة (Authentication)

جميع طلبات API تتطلب مفتاح API صالح. يُرسل المفتاح في هيدر Authorization مع كل طلب.

Header Authorization: Bearer YOUR_API_TOKEN
يمكنك إنشاء مفاتيح API من لوحة التحكم → مفاتيح API. المفتاح يظهر مرة واحدة فقط عند الإنشاء.

رابط API الأساسي

Base URL https://waslapi.com/api/v1

أكواد الأخطاء

الكودالمعنى
200نجاح
201تم الإنشاء بنجاح
400خطأ في البيانات المرسلة
401غير مصرح - مفتاح API غير صالح
403محظور - تجاوزت حد الاشتراك
404غير موجود
422خطأ في التحقق من البيانات
429تجاوزت حد الطلبات (Rate Limit)
500خطأ في الخادم

إدارة الأرقام (Instances)

GET /instances

عرض جميع أرقام الواتساب المسجلة في حسابك.

مثال cURL:
cURL
curl -X GET https://waslapi.com/api/v1/instances \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
مثال PHP:
PHP
$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://waslapi.com/api/v1/instances');

$instances = $response->json();
POST /instances

إنشاء رقم واتساب جديد.

المعاملات:
المعاملالنوعمطلوبالوصف
namestringنعماسم الرقم (للتعريف)
proxy_countrystringلاكود الدولة للبروكسي (مثال: sa, ae)
مثال cURL:
cURL
curl -X POST https://waslapi.com/api/v1/instances \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "رقم المتجر", "proxy_country": "sa"}'
GET /instances/{id}/qr

جلب رمز QR لربط الرقم بتطبيق واتساب. افتح واتساب → الأجهزة المرتبطة → امسح الرمز.

cURL
curl -X GET https://waslapi.com/api/v1/instances/1/qr \
  -H "Authorization: Bearer YOUR_API_TOKEN"
GET /instances/{id}/status

فحص حالة اتصال الرقم (متصل / غير متصل / معلّق).

DELETE /instances/{id}

حذف رقم واتساب نهائياً مع جميع بياناته.

الرسائل (Messages)

POST /messages/send-text

إرسال رسالة نصية.

المعاملات:
المعاملالنوعمطلوبالوصف
instance_idintegerنعممعرّف الرقم
tostringنعمرقم المستلم (مع كود الدولة بدون +)
messagestringنعمنص الرسالة
مثال cURL:
cURL
curl -X POST https://waslapi.com/api/v1/messages/send-text \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": 1,
    "to": "966501234567",
    "message": "مرحباً! هذه رسالة تجريبية."
  }'
مثال Python:
Python
import requests

url = "https://waslapi.com/api/v1/messages/send-text"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "instance_id": 1,
    "to": "966501234567",
    "message": "مرحباً من Python!"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
مثال Node.js:
Node.js
const response = await fetch('https://waslapi.com/api/v1/messages/send-text', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    instance_id: 1,
    to: '966501234567',
    message: 'مرحباً من Node.js!'
  })
});

const data = await response.json();
console.log(data);
POST /messages/send-media

إرسال رسالة وسائط (صورة، فيديو، مستند، صوت).

المعاملات:
المعاملالنوعمطلوبالوصف
instance_idintegerنعممعرّف الرقم
tostringنعمرقم المستلم
media_typestringنعمنوع الوسائط: image, video, document, audio
media_urlstringنعمرابط الملف (URL عام)
captionstringلانص مرفق مع الوسائط
filenamestringلااسم الملف (للمستندات)
cURL
curl -X POST https://waslapi.com/api/v1/messages/send-media \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": 1,
    "to": "966501234567",
    "media_type": "image",
    "media_url": "https://example.com/photo.jpg",
    "caption": "صورة المنتج"
  }'
GET /messages

عرض سجل الرسائل المرسلة مع إمكانية الفلترة حسب الرقم والحالة والتاريخ.

معاملات الفلترة (Query Params):
المعاملالنوعالوصف
instance_idintegerفلترة حسب رقم محدد
statusstringحالة الرسالة: sent, delivered, failed
date_fromdateمن تاريخ (YYYY-MM-DD)
date_todateإلى تاريخ (YYYY-MM-DD)
per_pageintegerعدد النتائج في الصفحة (افتراضي 20)

Webhooks

إعداد Webhooks

يمكنك تحديد Webhook URL لكل رقم واتساب عند الإنشاء أو التحديث. المنصة ترسل لك الأحداث التالية:

الحدثالوصف
message.receivedعند استقبال رسالة جديدة
message.sentعند إرسال رسالة بنجاح
message.failedعند فشل إرسال رسالة
instance.connectedعند اتصال الرقم
instance.disconnectedعند انقطاع اتصال الرقم
جميع طلبات Webhook تتضمن هيدر X-Webhook-Signature يحتوي على توقيع HMAC-SHA256 للتحقق من المصدر.

الاستهلاك

GET /usage

عرض بيانات استهلاك الاشتراك الحالي.

cURL
curl -X GET https://waslapi.com/api/v1/usage \
  -H "Authorization: Bearer YOUR_API_TOKEN"
الاستجابة:
JSON
{
  "plan": "احترافي",
  "messages_used": 1250,
  "messages_limit": 10000,
  "messages_remaining": 8750,
  "bandwidth_used_mb": 45.2,
  "bandwidth_limit_mb": 500,
  "instances_count": 3,
  "instances_limit": 5,
  "expires_at": "2025-04-15"
}