بوابة مطوري إيجاز
كل ما يحتاجه فريق التقنية لديكم ليقرأ بيانات إيجاز من أنظمتكم: واجهة REST، وموصّل Power BI، وخادم MCP، وWebhooks موقّعة، ودليل للربط عبر Zapier وMake وPower Automate.
الربط كله للقراءة فقط: لا يستطيع أي مفتاح أن يغيّر شيئًا في إيجاز، وكل مفتاح يقرأ ما أُعطي من مجموعات البيانات فقط.
الواجهة البرمجية وخادم MCP وWebhooks في إيجاز المؤسسي، وموصّل Power BI في إيجاز الشامل وإيجاز المؤسسي. تنزيل CSV وExcel متاح في كل الباقات.
البداية السريعة
- من حساب إيجاز: الإعدادات ← ربط البيانات ← المفاتيح، أنشئوا مفتاحًا واختاروا المجموعات التي يقرؤها. يظهر المفتاح مرة واحدة، فاحفظوه في مكان آمن.
- أرسلوا أول طلب بالأمر أدناه، وستصلكم أحدث الإشارات بصيغة JSON.
- لاستقبال التنبيهات فور حدوثها، أضيفوا عنوانكم في الإعدادات ← ربط البيانات ← 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
| الحقل | النوع |
|---|---|
| id | string |
| posted_at | datetime |
| platform | string |
| url | string |
| author_handle | string |
| author_name | string |
| author_followers | int |
| text | string |
| lang | string |
| subject | string |
| section | string |
| tone | string |
| tone_by | string |
| sarcasm | bool |
| aspects | json |
| likes | int |
| replies | int |
| shares | int |
| views | int |
| parent_text | string |
| own_account | bool |
/api/v1/articles · الأخبار
الأخبار التي ذكرت الشركة أو منافسيها، بمستوى المصدر ونبرتها. OData: Articles
| الحقل | النوع |
|---|---|
| id | string |
| published_at | datetime |
| title | string |
| url | string |
| outlet | string |
| domain | string |
| lang | string |
| tier | int |
| tone | string |
| topic | string |
| subject | string |
| section | string |
/api/v1/stories · القصص ومستواها
القصص التي تتابعها التنبيهات: مستواها الآن وأعلى مستوى بلغته وحجمها. OData: Stories
| الحقل | النوع |
|---|---|
| id | string |
| last_item_at | datetime |
| first_at | datetime |
| title_ar | string |
| title_en | string |
| kind | string |
| level | string |
| peak | string |
| status | string |
| items | int |
| negative | int |
| accounts | int |
| tier1_press | int |
| closed_at | datetime |
/api/v1/alerts · التنبيهات
سجل التنبيهات: فُتح، ارتفع، انخفض، أُغلق، أُبلغ. OData: AlertEvents
| الحقل | النوع |
|---|---|
| id | string |
| at | datetime |
| story_id | string |
| title_ar | string |
| title_en | string |
| event | string |
| from_level | string |
| to_level | string |
/api/v1/reviews · المراجعات
مراجعات خرائط قوقل للفروع التي تتابعونها، بالتقييم والنبرة. OData: Reviews
| الحقل | النوع |
|---|---|
| id | string |
| posted_at | datetime |
| branch | string |
| owner | string |
| competitor | string |
| rating | int |
| text | string |
| tone | string |
| url | string |
/api/v1/followers · المتابعون يومًا بيوم
عدد متابعي كل حساب تتابعونه، كما قُرئ كل يوم. OData: FollowersDaily
| الحقل | النوع |
|---|---|
| id | string |
| day | date |
| platform | string |
| handle | string |
| owner | string |
| competitor | string |
| label | string |
| followers | int |
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_mentions | Every 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_articles | News 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_stories | The 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_events | The alerts' log: opened, raised, lowered, closed, notified. Fields: id, at, story_id, title_ar, title_en, event, from_level, to_level. Newest first. |
| list_reviews | Google 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_daily | Each followed account's follower count, as read each day. Fields: id, day, platform, handle, owner, competitor, label, followers. Newest first. |
| summary | Counts 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
استقبال الأحداث لحظة وقوعها
- أنشئوا Zap جديدًا، واختاروا المشغّل Webhooks by Zapier ثم Catch Hook، وانسخوا العنوان الذي يعطيكم إياه.
- في إيجاز: الإعدادات ← ربط البيانات ← Webhooks، الصقوا العنوان واختاروا الأحداث، ثم أرسلوا حدثًا تجريبيًا.
- أضيفوا الخطوة التالية في Zapier: مهمة في Salesforce، أو ملاحظة على شركة في HubSpot، أو رسالة في قناة Teams.
قراءة البيانات على جدول
- المشغّل Schedule by Zapier بالتكرار الذي تريدونه.
- ثم Webhooks by Zapier ← GET على عنوان المجموعة، مثل
/api/v1/articles، مع الترويسةAuthorization: Bearerومفتاحكم. - ثم الخطوة في نظامكم لكل سطر.
Make
استقبال الأحداث لحظة وقوعها
- أنشئوا Scenario، واختاروا الوحدة Webhooks ثم Custom webhook، وانسخوا العنوان.
- الصقوه في إيجاز في Webhooks واختاروا الأحداث، وأرسلوا حدثًا تجريبيًا ليتعرّف Make على شكله.
- أضيفوا وحدة Salesforce أو HubSpot أو Microsoft Dynamics 365 أو Teams بعده.
قراءة البيانات على جدول
- اجعلوا الجدولة على الفترة التي تريدونها.
- الوحدة HTTP ثم Make a request، بالطريقة GET والترويسة
Authorization: Bearerومفتاحكم. - ثم Iterator على
dataلكل سطر، فوحدة نظامكم.
Power Automate
استقبال الأحداث لحظة وقوعها
- أنشئوا Flow بالمشغّل When a HTTP request is received، واحفظوه لتحصلوا على العنوان.
- الصقوه في إيجاز في Webhooks واختاروا الأحداث.
- أضيفوا الإجراء في Dynamics 365 أو Teams أو SharePoint.
قراءة البيانات على جدول
- المشغّل Recurrence.
- الإجراء HTTP بالطريقة GET والترويسة
Authorization: Bearerومفتاحكم. - ثم 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 لا يتغيّر بما يكسر ما بنيتموه، وأي تغيير كاسر يأتي بإصدار جديد ومهلة كافية. تحديثات إيجاز
سؤال لم تجدوا جوابه؟ تواصلوا معنا