للمطورين

API قوي وسهل الاستخدام

اربط Mirage مع تطبيقاتك وأنظمتك الخاصة عبر REST API بسيط ومرن

احصل على API Key الوثائق
Base URL: https://bot.miragemarketingai.com/api/v1

REST API

واجهة برمجية بسيطة ومعيارية تدعم JSON

Webhooks

إشعارات فورية عند وصول رسائل جديدة

آمن

توثيق بـ API Keys وتشفير HTTPS

أمثلة سريعة

ابدأ التكامل في دقائق

POST محادثة مع الذكاء الاصطناعي

cURL 
curl -X POST https://bot.miragemarketingai.com/api/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "ما هي خدماتكم؟",
    "conversation_id": "conv_123"
  }'
Response 
{
  "success": true,
  "reply": "مرحباً! نحن نقدم خدمات الذكاء الاصطناعي...",
  "conversation_id": "conv_123",
  "response_time": 1.234
}

GET معلومات البوت

JavaScript 
const response = await fetch('https://bot.miragemarketingai.com/api/v1/bot-info', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);
Response 
{
  "success": true,
  "data": {
    "name": "مساعد العملاء",
    "response_length": "medium",
    "rate_limit": 100,
    "is_active": true,
    "created_at": "2024-01-15T10:30:00Z",
    "instructions": "أنت مساعد ذكي..."
  }
}

GET إحصائيات الاستخدام

Python 
import requests

response = requests.get(
    'https://bot.miragemarketingai.com/api/v1/usage-stats',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

stats = response.json()
print(f"Requests today: {stats['data']['today']['requests']}")
print(f"Tokens used: {stats['data']['today']['tokens']}")
Response 
{
  "success": true,
  "data": {
    "today": {
      "requests": 45,
      "tokens": 12500,
      "avg_response_time": 1.23
    },
    "month": {
      "requests": 1250,
      "tokens": 350000,
      "cost": 2.45
    },
    "total": {
      "requests": 5000,
      "tokens": 1500000,
      "cost": 10.50
    },
    "rate_limit": {
      "limit_per_hour": 100,
      "current_hour_usage": 12
    }
  }
}

GET معلومات API Key

PHP 
$response = Http::withHeaders([
    'Authorization' => 'Bearer ' . $apiKey
])->get('https://bot.miragemarketingai.com/api/v1/key-info');

$keyInfo = $response->json();
echo "Usage count: " . $keyInfo['data']['usage_count'];

نقاط النهاية المتاحة

قائمة كاملة بالـ Endpoints

المحادثة

POST
/v1/chat

إرسال رسالة والحصول على رد ذكي من AI

معلومات البوت

GET
/v1/bot-info

الحصول على معلومات وإعدادات البوت

الإحصائيات

GET
/v1/usage-stats

إحصائيات الاستخدام اليومية والشهرية

API Key

GET
/v1/key-info

معلومات عن API Key والصلاحيات

التوثيق (Authentication)

جميع الطلبات تتطلب API Key في الـ Header:

Authorization: Bearer YOUR_API_KEY

يمكنك إنشاء وإدارة API Keys من حسابك

حدود الاستخدام

حدود مرنة تناسب حجم عملك مع إمكانية الزيادة عند الحاجة.

Starter 100 req/min
Business 500 req/min
Enterprise Unlimited

Headers المطلوبة

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

مكتبات جاهزة

استخدم لغتك المفضلة مع مكتباتنا الرسمية

PHP

Laravel & Native

composer require mirage/api

JavaScript

Node.js & Browser

npm install @mirage/api

Python

Django & Flask

pip install mirage-api

Ruby

Rails & Sinatra

gem install mirage-api

صيغ الاستجابة

جميع الاستجابات بصيغة JSON موحدة

استجابة ناجحة

200 OK 
{
  "success": true,
  "data": {
    "id": "msg_123456",
    "status": "sent",
    "to": "+966500000000",
    "channel": "whatsapp",
    "message": "مرحباً!",
    "sent_at": "2024-01-19T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-19T10:30:00Z"
  }
}

استجابة خطأ

400 Bad Request 
{
  "success": false,
  "error": {
    "code": "INVALID_PHONE",
    "message": "رقم الهاتف غير صحيح",
    "details": "يجب أن يبدأ الرقم بـ +"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-19T10:30:00Z"
  }
}

أكواد الأخطاء الشائعة

401 UNAUTHORIZED

API Key غير صحيح أو منتهي

429 RATE_LIMIT

تجاوزت حد الطلبات المسموح

400 INVALID_INPUT

بيانات الطلب غير صحيحة

404 NOT_FOUND

المورد المطلوب غير موجود

500 SERVER_ERROR

خطأ في الخادم

402 PAYMENT_REQUIRED

الباقة منتهية أو غير كافية

أفضل الممارسات

نصائح لاستخدام API بكفاءة

استخدم Webhooks

بدلاً من الاستعلام المتكرر (polling)، استخدم Webhooks لتلقي الإشعارات الفورية عند وصول رسائل جديدة.

احفظ API Key بأمان

لا تشارك API Key في الكود العام أو المستودعات. استخدم متغيرات البيئة (.env) لحفظها.

استخدم Caching

احفظ البيانات التي لا تتغير كثيراً (مثل قوائم المنتجات) في الذاكرة المؤقتة لتقليل عدد الطلبات.

راقب حدود الاستخدام

تحقق من headers الاستجابة (X-RateLimit-Remaining) لمعرفة عدد الطلبات المتبقية.

معالجة الأخطاء

تعامل مع جميع أكواد الأخطاء المحتملة وأعد المحاولة تلقائياً عند حدوث أخطاء مؤقتة (5xx).

سجّل الطلبات

احتفظ بسجل للطلبات والاستجابات (مع إخفاء API Key) لتسهيل تتبع المشاكل وحلها.

جاهز للبدء؟

احصل على API Key وابدأ التكامل في دقائق

ابدأ الآن تواصل معنا
ابدأ الآن