المطورون

اربط أنظمتك بـ Marcomm AI

اقرأ ملخصات الأخبار والأخبار الحرجة وطلبات الموافقة المعلقة من أنظمتك الخاصة، ووافق أو ارفض من أدوات الموافقة لديك. يتوفر API في باقة Team وما فوقها بعد مراجعة قصيرة.

البدء

1
اطلب الوصول
صف نظامك واختر البيانات التي تحتاجها. نراجع الطلبات المقدمة.
2
أنشئ مفتاحًا
بعد الموافقة، أنشئ مفتاحًا من الإعدادات، API. يظهر المفتاح مرة واحدة فقط، لذا احفظه في نظامك.
3
أرسل طلبًا
أرسل المفتاح في ترويسة Authorization ثم استدعِ إحدى نقاط النهاية أدناه.

مثال على طلب

curl https://app.marcomm.works/api/v1/news/digest?days=7 \
  -H "Authorization: Bearer mc_live_..."

المصادقة

أرسل مفتاحك على هيئة رمز Bearer مع كل طلب. يعمل المفتاح الشخصي باسم الشخص الذي أنشأه، فيمكنه قراءة الموافقات والبت فيها باسمه. أما مفتاح مساحة العمل فينشئه مشرف ويقتصر على القراءة. يمكن أن تنتهي صلاحية المفاتيح، وأن تُقيَّد بعناوين IP، وأن تُدوَّر: يظل المفتاح القديم يعمل 24 ساعة بعد التدوير.

النطاقات (Scopes)

يحمل المفتاح النطاقات التي تمت الموافقة عليها لتطبيقك فقط.

news: ملخص الأخبار والمقالات والوسائل الإعلامية.
crisis: الأخبار الحرجة وحوادث الأزمات.
approvals: طلبات الموافقة المعلقة، والموافقة عليها أو رفضها بمفتاح شخصي.
content: قراءة البيانات الصحفية ومقالات المدونة.

نقاط النهاية

تبدأ المسارات بـ /api/v1. تستخدم نقاط القراءة GET وتقبل معاملات استعلام. الاستجابة بصيغة JSON على الشكل {"data": ...}.

الطريقة	المسار	النطاق	الوظيفة
GET	/api/v1/news/digest	news	حجم التغطية والمشاعر وأبرز الوسائل الإعلامية خلال فترة.
GET	/api/v1/news/articles	news	البحث في التغطية الإخبارية.
GET	/api/v1/news/outlets	news	الوسائل الإعلامية التي تغطي شركاتك.
GET	/api/v1/crisis/incidents	crisis	حوادث الأزمات والمقالات الحرجة.
GET	/api/v1/approvals	approvals	البيانات الصحفية ومقالات المدونة التي تنتظر صاحب المفتاح، وتلك التي طلب صاحب المفتاح الموافقة عليها.
GET	/api/v1/press-releases	content	عرض قائمة البيانات الصحفية.
GET	/api/v1/press-releases/{id}	content	بيان صحفي واحد مع فقرته الافتتاحية ونصه.
GET	/api/v1/blog-posts	content	عرض قائمة مقالات المدونة.
GET	/api/v1/blog-posts/{id}	content	مقال مدونة واحد مع نصه.
POST	/api/v1/approvals/press-releases/{id}	approvals	الموافقة على بيان صحفي ينتظر صاحب المفتاح أو رفضه.
POST	/api/v1/approvals/blog-posts/{id}	approvals	الموافقة على مقال مدونة ينتظر صاحب المفتاح أو رفضه.

الموافقة والرفض

أرسل {"decision": "approve"} أو {"decision": "reject", "comment": "..."} إلى العنصر. يتطلب الرفض تعليقًا. يتبع القرار القواعد نفسها المعتمدة في التطبيق وفي Slack، ويُسجَّل باسم صاحب المفتاح. إذا احتوى النص على عبارات تتطلب تأكيدًا، فستتلقى 409 confirmation_required مع التحذيرات، ويمكنك إعادة إرسال الطلب مع "force": true.

curl -X POST https://app.marcomm.works/api/v1/approvals/press-releases/<id> \
  -H "Authorization: Bearer mc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"decision":"reject","comment":"Please fix the headline."}'

حدود المعدل

تُحدَّد الحدود لكل مساحة عمل، في الدقيقة وفي اليوم (UTC). تتضمن الاستجابات الترويسات أدناه. عند تجاوز الحد تتلقى 429 مع Retry-After. لرفع الحد، قدّم طلبًا من الإعدادات، API. يراجعه فريقنا.

X-RateLimit-Limit: عدد الطلبات المسموح بها في الدقيقة.
X-RateLimit-Remaining: عدد الطلبات المتبقية في الدقيقة الحالية.
X-RateLimit-Reset: وقت Unix الذي تُعاد فيه نافذة الدقيقة.
X-RateLimit-Day-Limit: عدد الطلبات المسموح بها في اليوم.
X-RateLimit-Day-Remaining: عدد الطلبات المتبقية اليوم.
Retry-After: عدد الثواني التي يجب انتظارها قبل المحاولة مجددًا. يظهر مع 429 فقط.

الأخطاء

تعيد الأخطاء JSON على الشكل {"error": {"code": ..., "message": ...}}.

الرمز	الحالة	المعنى
invalid_key	401	المفتاح مفقود أو بصيغة غير صحيحة أو تم إبطاله.
expired	401	انتهت صلاحية المفتاح. أنشئ مفتاحًا أو دوّره.
ip_denied	403	المفتاح مقيّد بعناوين IP أخرى.
plan_required	403	مساحة العمل ليست على باقة Team أو أعلى.
access_required	403	لم تتم الموافقة على الوصول إلى API لمساحة العمل هذه.
suspended	403	الوصول إلى API لمساحة العمل هذه معلّق.
scope_denied	403	لا يملك المفتاح النطاق الذي تحتاجه نقطة النهاية هذه.
personal_key_required	403	المفتاح الشخصي وحده يمكنه الموافقة أو الرفض.
denied	403	دور صاحب المفتاح لا يسمح بذلك.
unknown_endpoint	404	نقطة النهاية هذه غير موجودة.
comment_required	400	سبب الرفض مطلوب.
confirmation_required	409	التحذيرات تحتاج إلى تأكيد. أعد الإرسال مع ضبط force على true.
rate_limited	429	تم تجاوز الحد في الدقيقة.
daily_limit	429	تم بلوغ الحد اليومي.

Webhooks

يمكن أيضًا دفع التنبيهات وطلبات الموافقة والموجز الصباحي إلى نظامك. أضف وجهة من الإعدادات، API، Webhooks. كل طلب بصيغة JSON ويحتوي على الحقول event (alert أو approval أو briefing) وworkspace وtitle وtext وurl وdata وsentAt. يحمل طلب الموافقة data.kind (press_release أو blog أو event) وdata.id، ويمكنك استخدامهما للقراءة والبت عبر API.

الطلبات موقّعة. احسب HMAC-SHA256 لجسم الطلب الخام باستخدام سر التوقيع لديك وقارنه بترويسة X-Marcomm-Signature التي تأتي بالصيغة sha256=<hex>. ارفض الطلبات التي لا تتطابق.

التحقق من Webhook في Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

export function isFromMarcomm(rawBody: string, signature: string, secret: string) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && timingSafeEqual(a, b);
}

أدلة الربط

الموافقة من نظام الموافقات لديك

أضف وجهة Webhook عامة وفعّل طلبات الموافقة.
عند وصول Webhook موافقة، تحقق من التوقيع واقرأ data.kind وdata.id.
اعرض الطلب في نظام الموافقات لديك. اقرأ النص عند الحاجة عبر GET press-releases/{id} أو blog-posts/{id}.
أرسل القرار بالمفتاح الشخصي للشخص صاحب القرار. أما الفعاليات وإرسال البريد فيُبَتّ فيها داخل التطبيق عبر الرابط في الرسالة.

تغذية لوحتك بملخص الأخبار

أنشئ مفتاح مساحة عمل بنطاقي news وcrisis.
استدعِ news/digest وفق جدول، مثلًا كل صباح.
استدعِ crisis/incidents بوتيرة أعلى إذا أردت تنبيهات خاصة بك. راقب ترويسات X-RateLimit لتبقى ضمن حدودك.

التنبيهات في محادثتك

لـ Teams وGoogle Chat، أنشئ عنوان URL لـ Webhook الغرفة وأضفه وجهةً من الإعدادات، API، Webhooks.
لـ JANDI وDooray! وChatwork، اربطها من الإعدادات، التكاملات.
اختر ما تستقبله كل وجهة من التنبيهات وطلبات الموافقة والموجز الصباحي، ثم أرسل رسالة اختبار.

هل أنت مستعد للربط؟

يقدّم مالك مساحة العمل أو أحد مشرفيها الطلب من الإعدادات، API. سنخطرك بالبريد الإلكتروني وداخل التطبيق عند اكتمال المراجعة.

فتح إعدادات API