التوثيق التقني الكامل لواجهة برمجة التطبيقات (API) لمنصة مستخبي">

🔌 واجهة برمجة التطبيقات (API)

التوثيق التقني الكامل للمطورين لبناء تطبيقات مبنية على منصة مستخبي.

🕐 آخر تحديث: 20 أغسطس 2024 | الإصدار: 2.0.0

🚀 نظرة عامة على API

توفر منصة مستخبي واجهة برمجة تطبيقات (RESTful API) قوية تتيح للمطورين:

✓ Base URL: https://api.mstkhby.com/v2
⚠️ مطلوب: API متاح فقط لمشتركي خطة "منشئ محتوى" وما فوق

🔐 المصادقة والتفويض

الحصول على API Key

  1. اشترك في خطة منشئ محتوى: أو أعلى
  2. اذهب للإعدادات: الإعدادات ← المطورون
  3. أنشئ API Key: اضغط "إنشاء مفتاح جديد"
  4. حدد الصلاحيات: اختر النطاقات المطلوبة (Scopes)
  5. احفظ المفتاح: انسخه فوراً - لن يظهر مجدداً!

طرق المصادقة

الطريقة الرأس (Header) الاستخدام
API Key X-API-Key: your_key_here بسيط، للتطبيقات الخادمية
Bearer Token (JWT) Authorization: Bearer jwt_token للمستخدمين النهائيين
OAuth 2.0 Authorization: Bearer access_token لتطبيقات الطرف الثالث

مثال على الطلب

GET /v2/me/messages HTTP/1.1 Host: api.mstkhby.com X-API-Key: mstkhby_live_abc123xyz Content-Type: application/json Accept: application/json

⏱️ حدود الطلب (Rate Limiting)

لتمنع إساءة الاستخدام وتضمن استقرار الخدمة، نطبق حدوداً على الطلبات:

الخطة الحد اليومي الحد بالدقيقة الحد بالثانية
بريميوم 10,000 100 10
منشئ محتوى 100,000 500 50
Enterprise غير محدود 1,000 100

رؤوس الاستجابة

X-RateLimit-Limit: 500 X-RateLimit-Remaining: 498 X-RateLimit-Reset: 1692345600 // عند تجاوز الحد: HTTP/1.1 429 Too Many Requests { "error": "Rate limit exceeded", "retry_after": 60 }

🔗 نقاط النهاية (Endpoints)

المصادقة (Authentication)

الطريقة المسار الوصف
POST /auth/register تسجيل حساب جديد
POST /auth/login تسجيل الدخول
POST /auth/refresh تجديد Token
POST /auth/logout تسجيل الخروج
GET /auth/me معلومات المستخدم الحالي

الرسائل (Messages)

الطريقة المسار الوصف
POST /messages/send إرسال رسالة جديدة
GET /messages/inbox صندوق الوارد
GET /messages/:id تفاصيل رسالة
DELETE /messages/:id حذف رسالة
POST /messages/:id/react تفاعل مع رسالة
POST /messages/:id/reply رد على رسالة

المستخدمون (Users)

الطريقة المسار الوصف
GET /users/:username ملف مستخدم
PATCH /users/me تحديث ملفي
POST /users/me/follow متابعة مستخدم
DELETE /users/me/follow/:id إلغاء المتابعة

التحليلات (Analytics)

الطريقة المسار الوصف
GET /analytics/overview نظرة عامة
GET /analytics/messages إحصائيات الرسائل
GET /analytics/growth نمو المتابعين
GET /analytics/export تصدير البيانات

💻 أمثلة على الطلبات

إرسال رسالة

POST /v2/messages/send HTTP/1.1 Host: api.mstkhby.com Authorization: Bearer eyJhbGciOiJIUzI1NiIs... Content-Type: application/json { "recipient": "ahmed_alii", "content": "مرحباً! كيف حالك؟", "privacy_level": "anonymous", "self_destruct": { "type": "after_read", "views": 1 }, "allow_replies": true } // Response 201 Created { "id": "msg_abc123", "status": "sent", "created_at": "2024-08-20T10:30:00Z", "self_destructs_at": null }

جلب صندوق الوارد

GET /v2/messages/inbox?page=1&limit=20&status=unread HTTP/1.1 Host: api.mstkhby.com X-API-Key: mstkhby_live_abc123 // Response 200 OK { "data": [ { "id": "msg_xyz789", "sender": { "anonymous": true, "alias": null }, "content": "رسالة تجريبية", "read": false, "created_at": "2024-08-20T09:15:00Z", "reactions": {"❤️": 5} } ], "pagination": { "page": 1, "limit": 20, "total": 45, "pages": 3 } }

الحصول على التحليلات

GET /v2/analytics/overview?period=30d HTTP/1.1 Host: api.mstkhby.com X-API-Key: mstkhby_live_abc123 // Response 200 OK { "period": "30d", "messages_received": 1250, "messages_sent": 340, "new_followers": 89, "total_reactions": 5670, "top_content": [...], "engagement_rate": 12.5 }

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

جميع الأخطاء تُرجع بتنسيق JSON موحد:

{ "error": { "code": "ERROR_CODE", "message": "وصف الخطأ بالعربية", "message_en": "Error description in English", "details": {...}, // اختياري "documentation_url": "https://docs.mstkhby.com/errors/ERROR_CODE" } }

رموز الأخطاء الشائعة

الكود HTTP Status الوصف
AUTH_INVALID 401 مفتاح API أو Token غير صالح
RATE_LIMITED 429 تجاوز حد الطلبات
NOT_FOUND 404 المورد غير موجود
VALIDATION_ERROR 422 بيانات غير صحيحة
FORBIDDEN 403 ليس لديك صلاحية
SERVER_ERROR 500 خطأ داخلي في الخادم

🪝 Webhooks (الاستدعاءات)

استقبل إشعارات فورية عند حدوث أحداث:

الأحداث المدعومة

إعداد Webhook

POST /v2/webhooks HTTP/1.1 Host: api.mstkhby.com Authorization: Bearer ... { "url": "https://your-app.com/webhook", "events": ["message.received", "follow.new"], "secret": "your_webhook_secret" } // Response 201 Created { "webhook_id": "wh_abc123", "status": "active" }

تنسيق Payload

// POST to your webhook URL { "event": "message.received", "timestamp": "2024-08-20T10:30:00Z", "data": { "message_id": "msg_xyz", "sender_anonymous": true, "content_preview": "مرحباً..." }, "signature": "sha256=..." // للتحقق }

📚 مكتبات SDK

نوفر SDKs رسمية للغات والأطر الشائعة:

🟨

JavaScript/Node.js

npm install @mstkhby/sdk

🐍

Python

pip install mstkhby-sdk

💎

Ruby

gem install mstkhby

☕

Java

Maven/Gradle package

📘

PHP

composer require mstkhby/sdk

🍎

Swift

SPM / CocoaPods

مثال سريع (JavaScript)

import { Mstkhby } from '@mstkhby/sdk'; const client = new Mstkhby({ apiKey: 'mstkhby_live_abc123' }); // إرسال رسالة const message = await client.messages.send({ recipient: 'username', content: 'Hello! 👋', privacyLevel: 'anonymous' }); console.log(`Message sent: ${message.id}`);

🧪 بيئة الاختبار (Sandbox)

قبل الانتقال للإنتاج، استخدم بيئة الاختبار:

Sandbox Production
Base URL https://api-sandbox.mstkhby.com/v2 https://api.mstkhby.com/v2
API Key Prefix mstkhby_test_ mstkhby_live_
البيانات وهمية (Fake) حقيقية
Rate Limits مرنة جداً محدودة
Webhooks لا تعمل تعمل
⚠️ هام: لا تستخدم مفاتيح Sandbox في الإنتاج والعكس!

💬 الدعم الفني للمطورين

تحتاج مساعدة؟ تواصل معنا:

✓ SLA: وقت استجابة 4 ساعات لأخطاء الإنتاج، 24 ساعة للاستفسارات العامة

📝 سجل التغييرات

v2.0.0 - أغسطس 2024

v1.x - مهمل (Deprecated)

الإصدار 1.x سيُوقف في يناير 2025. يرجى الترقية إلى v2.

→ العودة للرئيسية