APIREST · OpenAPI 3.1

واجهة REST API واحدة للمنصة كلها.

كل ما تفعله تطبيقات Medal متاح عبر HTTPS على https://io.medalsocial.com/api/v1 — المنشورات والبريد الإلكتروني وجهات الاتصال والصفقات والحجوزات والبوابة وGDPR والفحص ومكتب المساعدة وWebhooks والقنوات وتأكيدات القدرات ومساحات العمل.

اعرض على GitHub npm

البداية السريعة

من مفتاح API إلى أول استجابة.

bashأول طلب لكcopy
curl https://io.medalsocial.com/api/v1/posts \
  -H "Authorization: Bearer $MEDAL_API_KEY"

المصادقة

أنشئ مفتاح API من إعدادات مساحة العمل وأرسله في الترويسة Authorization: Bearer medal_… — يرتبط كل مفتاح بمساحة عمل واحدة فقط، فلا يمكن لأي تكامل الوصول إلى بيانات غيرها. تعمل رموز OAuth أيضاً؛ أرفق معها ترويسة x-workspace-id ليصل الطلب إلى مساحة العمل الصحيحة.

عنوان أساسي واحد، وكل الموارد

يغطي https://io.medalsocial.com/api/v1 المنشورات والبريد وجهات الاتصال والصفقات والحجوزات والبوابة وGDPR والفحص ومكتب المساعدة وWebhooks والقنوات وتأكيدات القدرات ومساحات العمل. كل شيء يدخل ويخرج بصيغة JSON.

jsonالأخطاء تأتي بصيغة JSONcopy
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header"
  }
}

الحدود وإعادة المحاولة والترقيم

القراءة محدودة بـ 300 طلب في الدقيقة (دفعة 100) والكتابة بـ 60 في الدقيقة (دفعة 30). إرسال البريد 100 في الدقيقة، ودفعات البريد 10 في الدقيقة، واستيراد جهات الاتصال 5 في الدقيقة، وتصدير GDPR 5 في الساعة. تراجَع عند 429 واحترم ترويسة Retry-After. تستخدم نقاط القوائم ترقيماً بالمؤشر: أعد إرسال next_cursor لجلب الصفحة التالية.

تحقّق من كل Webhook

تحمل كل عملية تسليم ترويسة X-Medal-Signature — وهي HMAC-SHA256 على {timestamp}.{rawBody} — إلى جانب X-Medal-Timestamp. أعد حساب التوقيع على الجسم الخام وقارنه قبل أن تثق بالمحتوى.

عقد OpenAPI 3.1 مُتحقَّق منه

لا يوجد عنوان عام لملف OpenAPI. العقد المُتحقَّق منه يُشحن داخل حزمة npm بدلاً من ذلك — @medalsocial/sdk/openapi.json وopenapi.yaml وopenapi-types — فتولّد عملاء أو خوادم محاكاة أو أدوات للوكلاء من إصدار تثبّته بنفسك.

حزمة TypeScript المصادقة ومفاتيح API مرجع الأخطاء Webhooks عقد OpenAPI على GitHub