للمطورين

بوابة مطوري إيجاز

كل ما يحتاجه فريق التقنية لديكم ليقرأ بيانات إيجاز من أنظمتكم: واجهة REST، وموصّل Power BI، وخادم MCP، وWebhooks موقّعة، ودليل للربط عبر Zapier وMake وPower Automate.

الربط كله للقراءة فقط: لا يستطيع أي مفتاح أن يغيّر شيئًا في إيجاز، وكل مفتاح يقرأ ما أُعطي من مجموعات البيانات فقط.

الواجهة البرمجية وخادم MCP وWebhooks في إيجاز المؤسسي، وموصّل Power BI في إيجاز الشامل وإيجاز المؤسسي. تنزيل CSV وExcel متاح في كل الباقات.

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

  1. من حساب إيجاز: الإعدادات ← ربط البيانات ← المفاتيح، أنشئوا مفتاحًا واختاروا المجموعات التي يقرؤها. يظهر المفتاح مرة واحدة، فاحفظوه في مكان آمن.
  2. أرسلوا أول طلب بالأمر أدناه، وستصلكم أحدث الإشارات بصيغة JSON.
  3. لاستقبال التنبيهات فور حدوثها، أضيفوا عنوانكم في الإعدادات ← ربط البيانات ← Webhooks، واختاروا الأحداث.
curl -H "Authorization: Bearer $IJAZ_KEY" \
  "https://ijaz.ai/api/v1/mentions?limit=20"

إنشاء مفتاح من حسابكم

المصادقة

أرسلوا المفتاح في الترويسة Authorization: Bearer <المفتاح>. يقبل موجز OData المصادقة الأساسية أيضًا (المفتاح كلمةً للمرور). لا تضعوا المفتاح في رابط ولا في صفحة ويب.

curl -H "Authorization: Bearer $IJAZ_KEY" \
  "https://ijaz.ai/api/v1/mentions?from=2026-10-01&to=2026-10-31&limit=100"

الحدود

60 طلبًا في الدقيقة و10,000 طلب في اليوم لكل مفتاح. ترويسات x-ratelimit-* في كل رد، وretry-after مع الرد 429.

REST

كل مجموعة في /api/v1/<المجموعة>، الأحدث أولًا. المعاملات: from وto (YYYY-MM-DD بتوقيت الرياض، أو ISO 8601)، وlimit (1 إلى 500، الافتراضي 100)، وcursor من next_cursor للصفحة التالية. الافتراضي آخر 90 يومًا.

مثال

GET https://ijaz.ai/api/v1/articles?from=2026-10-01&limit=2

{
  "dataset": "articles",
  "from": "2026-09-30T21:00:00.000Z",
  "to": "2026-11-05T12:00:00.000Z",
  "count": 2,
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0xMS0wNFQwOTowMDowMC4wMDBaIiwiaWQiOiIuLi4ifQ",
  "data": [{ "id": "…", "published_at": "2026-11-04T09:00:00.000Z", "title": "…", "tier": 1, "tone": "negative", … }]
}

المجموعات وحقولها

/api/v1/mentions · المنشورات بنبرتها

كل منشور على المنصات ذكر الشركة أو منافسيها، مع النبرة كما قرأها إيجاز أو صحّحها فريقكم. own_account يميّز منشورات الحسابات الرسمية، ولا تُحسب في الإشارات ولا في حصة الصوت على اللوحات. OData: Mentions

الحقلالنوع
idstring
posted_atdatetime
platformstring
urlstring
author_handlestring
author_namestring
author_followersint
textstring
langstring
subjectstring
sectionstring
tonestring
tone_bystring
sarcasmbool
aspectsjson
likesint
repliesint
sharesint
viewsint
parent_textstring
own_accountbool

/api/v1/articles · الأخبار

الأخبار التي ذكرت الشركة أو منافسيها، بمستوى المصدر ونبرتها. OData: Articles

الحقلالنوع
idstring
published_atdatetime
titlestring
urlstring
outletstring
domainstring
langstring
tierint
tonestring
topicstring
subjectstring
sectionstring

/api/v1/stories · القصص ومستواها

القصص التي تتابعها التنبيهات: مستواها الآن وأعلى مستوى بلغته وحجمها. OData: Stories

الحقلالنوع
idstring
last_item_atdatetime
first_atdatetime
title_arstring
title_enstring
kindstring
levelstring
peakstring
statusstring
itemsint
negativeint
accountsint
tier1_pressint
closed_atdatetime

/api/v1/alerts · التنبيهات

سجل التنبيهات: فُتح، ارتفع، انخفض، أُغلق، أُبلغ. OData: AlertEvents

الحقلالنوع
idstring
atdatetime
story_idstring
title_arstring
title_enstring
eventstring
from_levelstring
to_levelstring

/api/v1/reviews · المراجعات

مراجعات خرائط قوقل للفروع التي تتابعونها، بالتقييم والنبرة. OData: Reviews

الحقلالنوع
idstring
posted_atdatetime
branchstring
ownerstring
competitorstring
ratingint
textstring
tonestring
urlstring

/api/v1/followers · المتابعون يومًا بيوم

عدد متابعي كل حساب تتابعونه، كما قُرئ كل يوم. OData: FollowersDaily

الحقلالنوع
idstring
daydate
platformstring
handlestring
ownerstring
competitorstring
labelstring
followersint

OData (Power BI)

/api/v1/odata قائمة الجداول، و/api/v1/odata/$metadata وصفها. لكل جدول $top و$skip و$filter على حقل الوقت (ge وgt وle وlt). الافتراضي آخر سنة.

https://ijaz.ai/api/v1/odata
https://ijaz.ai/api/v1/odata/$metadata
https://ijaz.ai/api/v1/odata/Articles?$top=200&$filter=published_at ge 2026-10-01

MCP

POST /api/mcp بصيغة JSON-RPC. الأدوات: قراءة كل مجموعة بفترة وعدد ومؤشر صفحة، وأداة summary تلخص النبرة والمستويات.

الأداةما تقرؤه
list_mentionsEvery platform post that named the company or its competitors, with its tone as Ijaz read it or your team corrected it. own_account marks the official accounts' posts, which the dashboards do not count as mentions or in share of voice. Fields: id, posted_at, platform, url, author_handle, author_name, author_followers, text, lang, subject, section, tone, tone_by, sarcasm, aspects, likes, replies, shares, views, parent_text, own_account. Newest first.
list_articlesNews stories that named the company or its competitors, with the outlet's tier and the tone. Fields: id, published_at, title, url, outlet, domain, lang, tier, tone, topic, subject, section. Newest first.
list_storiesThe stories the alerts follow: their level now, the highest they reached, and their size. Fields: id, last_item_at, first_at, title_ar, title_en, kind, level, peak, status, items, negative, accounts, tier1_press, closed_at. Newest first.
list_alert_eventsThe alerts' log: opened, raised, lowered, closed, notified. Fields: id, at, story_id, title_ar, title_en, event, from_level, to_level. Newest first.
list_reviewsGoogle Maps reviews of the branches you follow, with the rating and the tone. Fields: id, posted_at, branch, owner, competitor, rating, text, tone, url. Newest first.
list_followers_dailyEach followed account's follower count, as read each day. Fields: id, day, platform, handle, owner, competitor, label, followers. Newest first.
summaryCounts for the period: posts by tone, news by tier, open stories by level. Uses only the datasets the key may read.

الإضافة في أدوات الذكاء الاصطناعي

خادم MCP يعمل مع الأدوات التي تقبل خادمًا بعنوان وترويسة Authorization، مثل Claude Code وCursor وVS Code، وغيرها من أدوات المطورين.

URL:     https://ijaz.ai/api/mcp
Header:  Authorization: Bearer $IJAZ_KEY

curl -X POST "https://ijaz.ai/api/mcp" \
  -H "Authorization: Bearer $IJAZ_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_stories","arguments":{"limit":20}}}'

Webhooks

طلب POST بصيغة JSON مع الترويسات ijaz-event وijaz-delivery وijaz-signature (t=<ثوانٍ>,v1=<HMAC-SHA256>). احسبوا HMAC للنص «t.الجسم» بمفتاحكم السري وقارنوه، وارفضوا ما مضى عليه أكثر من 5 دقائق. نعيد المحاولة بعد دقيقة ثم 5 ثم 30 دقيقة ثم ساعتين ثم 6 ثم 24 ساعة.

أحداث Webhooks

alert.openedفُتح تنبيه جديد على قصة
alert.escalatedارتفع مستوى تنبيه قائم
alert.notifiedأُبلغ المستلمون بتنبيه حسب مستواه
report.readyصار تقرير جاهزًا
audit.logسطر جديد في سجل نشاط الحساب

شكل الحدث

POST https://your-system.example.com/ijaz
ijaz-event: alert.opened
ijaz-delivery: 3f0c…
ijaz-signature: t=1763380800,v1=5d2a…

{
  "id": "…",
  "type": "alert.opened",
  "created_at": "2026-11-17T12:00:00.000Z",
  "org_id": "…",
  "company_id": "…",
  "company": "…",
  "data": { "company_id": "…", "company": "…", … }
}

التحقق من التوقيع (Node.js)

import crypto from "node:crypto";

// header: the ijaz-signature value, body: the raw request body (a string)
function verify(secret, header, body) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const want = crypto.createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
  const got = Buffer.from(parts.v1 ?? "");
  return got.length === want.length && crypto.timingSafeEqual(Buffer.from(want), got);
}

الربط بأنظمتكم عبر Zapier وMake وPower Automate

لا تحتاجون إلى برمجة لربط إيجاز بنظام إدارة علاقات العملاء (Salesforce أو HubSpot أو Dynamics 365) أو بـ Teams وSlack. أدوات الربط هذه تستقبل أحداث إيجاز أو تقرأ واجهته، ثم تكمل الخطوة في النظام الذي تختارونه.

Zapier

استقبال الأحداث لحظة وقوعها

  1. أنشئوا Zap جديدًا، واختاروا المشغّل Webhooks by Zapier ثم Catch Hook، وانسخوا العنوان الذي يعطيكم إياه.
  2. في إيجاز: الإعدادات ← ربط البيانات ← Webhooks، الصقوا العنوان واختاروا الأحداث، ثم أرسلوا حدثًا تجريبيًا.
  3. أضيفوا الخطوة التالية في Zapier: مهمة في Salesforce، أو ملاحظة على شركة في HubSpot، أو رسالة في قناة Teams.

قراءة البيانات على جدول

  1. المشغّل Schedule by Zapier بالتكرار الذي تريدونه.
  2. ثم Webhooks by Zapier ← GET على عنوان المجموعة، مثل /api/v1/articles، مع الترويسة Authorization: Bearer ومفتاحكم.
  3. ثم الخطوة في نظامكم لكل سطر.

Make

استقبال الأحداث لحظة وقوعها

  1. أنشئوا Scenario، واختاروا الوحدة Webhooks ثم Custom webhook، وانسخوا العنوان.
  2. الصقوه في إيجاز في Webhooks واختاروا الأحداث، وأرسلوا حدثًا تجريبيًا ليتعرّف Make على شكله.
  3. أضيفوا وحدة Salesforce أو HubSpot أو Microsoft Dynamics 365 أو Teams بعده.

قراءة البيانات على جدول

  1. اجعلوا الجدولة على الفترة التي تريدونها.
  2. الوحدة HTTP ثم Make a request، بالطريقة GET والترويسة Authorization: Bearer ومفتاحكم.
  3. ثم Iterator على data لكل سطر، فوحدة نظامكم.

Power Automate

استقبال الأحداث لحظة وقوعها

  1. أنشئوا Flow بالمشغّل When a HTTP request is received، واحفظوه لتحصلوا على العنوان.
  2. الصقوه في إيجاز في Webhooks واختاروا الأحداث.
  3. أضيفوا الإجراء في Dynamics 365 أو Teams أو SharePoint.

قراءة البيانات على جدول

  1. المشغّل Recurrence.
  2. الإجراء HTTP بالطريقة GET والترويسة Authorization: Bearer ومفتاحكم.
  3. ثم Apply to each على data.
  • احفظوا المفتاح في مكان الأسرار في الأداة، لا في نص الخطوة.
  • يحمل كل حدث الترويسة ijaz-signature. التحقق منها اختياري في هذه الأدوات، ويمكن بخطوة كود في Zapier أو Power Automate.
  • قد تحتاج خطوات Webhooks وHTTP إلى باقة مدفوعة في الأداة نفسها، حسب شروطها.
  • ما يصل إلى أنظمتكم من نصوص وأسماء مسؤوليتكم بعدها، فاحصروه في من يحتاجه.

الأخطاء

401 مفتاح غير صالح، 402 الحساب غير نشط (أُلغي أو أُوقف أو انتهت تجربته أو فترته المدفوعة)، 403 خارج الباقة أو صلاحية المفتاح، 404 مجموعة غير موجودة، 400 معامل غير صالح، 429 تجاوز الحد. الجسم: {"error":{"code","message"}}.

المفاتيح وحالة الحساب

يعمل المفتاح ما دام الحساب نشطًا. إذا أُلغي الحساب أو أُوقف، أو انتهت تجربته أو فترته المدفوعة، توقفت مفاتيحه كلها (REST، OData، MCP) بالرد 402 ورمز billing، وتعود حين يُجدَّد. ومفتاح المجموعة يتبع عقد المجموعة.

مفاتيح المجموعة

مفتاح المجموعة يقرأ إما شركة واحدة يُخصَّص لها عند إنشائه، وإما كل شركات المجموعة: الحالية والتي تُضاف لاحقًا، ويؤكّد مدير حساب المجموعة ذلك عند الإنشاء. كل سطر يحمل company_id وcompany، ويحصر المعامل ?company=<المعرّف> الطلب في شركة واحدة. حين تُضاف شركة يُسجَّل في سجل نشاطها أي مفاتيح المجموعة صارت تقرأ بياناتها، وحين تخرج تُلغى مفاتيح المجموعة المخصصة لها. وWebhooks المجموعة تصلها أحداث كل شركاتها، وفي كل حدث company_id وcompany.

الإصدارات

ما تغيّر في الواجهة يُكتب في «تحديثات إيجاز» بتصنيف «للمطورين». الإصدار v1 لا يتغيّر بما يكسر ما بنيتموه، وأي تغيير كاسر يأتي بإصدار جديد ومهلة كافية. تحديثات إيجاز

سؤال لم تجدوا جوابه؟ تواصلوا معنا