# API بوابة التحديثات

> URL: https://foura.ai/ar/docs/updates-portal/api
> Updated: 2026-11-05
> Index: https://foura.ai/llms.txt

توفر بوابة التحديثات (Updates Portal) واجهة برمجة تطبيقات JSON عامة ومحدودة لتتمكن من استطلاع الحالة، وجلب إدخالات سجل التغييرات، ومتابعة خارطة الطريق، والتحقق من المشكلات المعروفة من أنظمتك الخاصة. لا يلزم أي مصادقة. تقدم API النصوص باللغة الإنجليزية فقط؛ ويتم تجاهل بادئة اللغة في المسار.

## عنوان URL الأساسي

```
https://updates.foura.ai
```

## حالة الخدمة

`GET /api/v1/status`

تُرجع الحالة التشغيلية المباشرة لكل خدمة من خدمات FourA، بالإضافة إلى الحوادث النشطة والأخيرة. يتم التخزين المؤقت في جانب الخادم لمدة 15 ثانية، لذا فإن الاستقصاء بمعدل أعلى من ذلك يُرجع نفس البيانات.

```bash
curl https://updates.foura.ai/api/v1/status
```

```json
{
  "overall": "operational",
  "updated_at": "2026-05-19T12:00:00.000Z",
  "services": [
    {
      "slug": "api-gateway",
      "name": "API Gateway",
      "description": "...",
      "status": "operational",
      "daily": [
        { "date": "2026-05-19", "status": "operational", "major_outage_minutes": 0, "partial_outage_minutes": 0, "degraded_minutes": 0, "internal_degraded_minutes": 0 }
      ]
    }
  ],
  "active_incidents": [],
  "recent_incidents": [
    { "id": 12, "service_slug": "api-gateway", "service_name": "API Gateway", "impact": "minor", "title": "API Gateway: Degraded Performance", "status": "resolved", "started_at": "...", "resolved_at": "...", "duration_seconds": 30 }
  ]
}
```

| حقل المستوى الأعلى | النوع | الوصف |
|-----------------|------|-------------|
| `overall` | string | `operational` إذا كانت جميع الخدمات سليمة، وإلا فإحدى قيم حالة الخدمة |
| `updated_at` | string | وقت إنشاء بيانات الحالة، بتنسيق ISO 8601 مع لاحقة `Z` |
| `services` | array | إدخال واحد لكل خدمة خاضعة للمراقبة يتضمن `slug`، و`name`، و`description`، و`status` الحالية، وسجل `daily` (حتى 90 يوما) |
| `active_incidents` | array | الحوادث المفتوحة حاليا |
| `recent_incidents` | array | الحوادث التي تم حلها خلال آخر 14 يوما، ويحتوي كل منها على `id`، و`service_slug`، و`service_name`، و`impact`، و`title`، و`status`، و`started_at`، و`resolved_at`، و`duration_seconds` |

قيم `status` للخدمة: `operational`، و`degraded`، و`partial_outage`، و`major_outage`، و`maintenance`. يمكن أن يحمل إدخال `daily` أيضا القيمة `no_data`، وذلك لأي يوم لا توجد به بيانات مسجلة. يحتسب `internal_degraded_minutes` الوقت الذي لم يشهد أي تأثير على العملاء.

قيم `impact` للحادثة: `minor` (أداء منخفض)، و`major` (انقطاع جزئي)، و`critical` (انقطاع في الخدمة).

### نمط الاستقصاء

استخدم هذا الـ endpoint لربط حالة FourA بلوحة التحكم أو نظام التنبيه الخاص بك.

عند تعذر جلب بيانات الحالة، يستجيب الـ endpoint برمز `502` مع `{"error": "Monitor unreachable"}`. تعامل مع ذلك على أنه حالة غير معروفة بدلا من اعتباره عطلا، وأعد المحاولة في دورة الاستقصاء التالية.

```python
import requests

def check_foura():
    r = requests.get("https://updates.foura.ai/api/v1/status", timeout=5)
    r.raise_for_status()   # raises on the 502 "Monitor unreachable" answer: retry next poll
    data = r.json()
    if data["overall"] != "operational":
        # Page on-call, post to Slack, flip a feature flag, etc.
        for svc in data["services"]:
            if svc["status"] != "operational":
                print(f"{svc['name']}: {svc['status']}")
    return data
```

يعيد `GET /api/status` القديم `410 Gone` ويوجه المتصلين إلى هنا.

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

`GET /api/changelog`

يعيد إدخالات سجل التغييرات المنشورة بترتيب زمني عكسي.

```bash
curl "https://updates.foura.ai/api/changelog?limit=20"
```

معلمات الاستعلام:

| المعلمة | النوع | القيمة الافتراضية | الوصف |
|-----------|------|---------|-------------|
| `page` | integer | 1 | رقم الصفحة بفهرسة تبدأ من 1 |
| `limit` | integer | 20 | عدد الإدخالات لكل صفحة (الحد الأقصى 50) |
| `category` | string | - | التصفية حسب `new`، أو `improved`، أو `fixed` |

```json
{
  "entries": [
    {
      "id": 42,
      "title": "...",
      "body": "Markdown body",
      "category": "new",
      "tags": "[\"api\",\"dashboard\"]",
      "published": 1,
      "published_at": "2026-05-19T12:00:00Z",
      "created_at": "2026-05-19 11:42:08",
      "updated_at": "2026-05-19 11:44:31"
    }
  ],
  "total": 137,
  "page": 1,
  "limit": 20
}
```

| الحقل | النوع | الوصف |
|-------|------|-------------|
| `id` | integer | معرف المدخلة |
| `title` | string | عنوان المدخلة |
| `body` | string | نص Markdown |
| `category` | string | `new`، أو `improved`، أو `fixed` |
| `tags` | string | مصفوفة JSON **ترمّز كسلسلة نصية**. قم بتحليلها قبل الاستخدام: `json.loads(entry["tags"])`. |
| `published` | integer | دائمًا `1` هنا. لا يعيد الـ endpoint سوى المدخلات المنشورة. |
| `published_at` | string | بتنسيق ISO 8601 مع لاحقة `Z` |
| `created_at` | string | `YYYY-MM-DD HH:MM:SS`، بتوقيت UTC، بدون محدد للمنطقة الزمنية |
| `updated_at` | string | نفس تنسيق `created_at` |

يختلف تنسيقا الطابع الزمني عن قصد: `published_at` هو تاريخ التحرير ويتضمن منطقة زمنية، بينما `created_at` و `updated_at` هما طابعا التخزين الزمني. كلاهما بتوقيت UTC. إذا افترضت أداة التحليل تنسيقًا واحدًا لجميع الحقول الثلاثة، فستفشل مع الحقلين الآخرين.

### RSS

ينشر أيضًا سجل التغييرات الكامل (أحدث 30 مدخلة) بتنسيق RSS على:

```
https://updates.foura.ai/rss
```

اشترك عبر Feedly أو Miniflux أو Thunderbird أو أي قارئ آخر. يطابق نص الخلاصة محتوى changelog، بما في ذلك markdown المعروض كـ HTML.

## خريطة الطريق

`GET /api/roadmap`

يُرجع كل عنصر منشور في خريطة الطريق، مرتبا حسب عدد الأصوات ثم وقت الإنشاء.

```bash
curl https://updates.foura.ai/api/roadmap
```

```json
{
  "items": [
    {
      "id": 12,
      "title": "...",
      "description": "...",
      "status": "planned",
      "category": "developer-experience",
      "votes": 23,
      "target_date": "Q3 2026",
      "completed_at": null,
      "created_at": "2026-03-30 09:32:47"
    }
  ]
}
```

قيم `status` للعنصر: `planned`، `in_progress`، `done`، `cancelled`. تعرض اللوحة على [updates.foura.ai/roadmap](https://updates.foura.ai/roadmap) ثلاثة أعمدة، لذلك فإن العنصر المضبوط على `cancelled` يصلك عبر هذا الـ endpoint ولا يظهر مطلقًا على الصفحة.

`category` عبارة عن slug بأحرف صغيرة، وليس التسمية التي تعرضها الصفحة. الـ slugs المستخدمة حاليًا: `api`، `infrastructure`، `developer-experience`، `dashboard`، `billing`، `analytics`، `authentication`. تعامل مع القائمة على أنها مفتوحة، حيث يمكن لعنصر جديد تقديم slug جديد.

`target_date` عبارة عن نص حر (`"Q3 2026"`)، وليس تاريخًا. يكون `completed_at` بقيمة `null` حتى يتم إطلاق العنصر، ثم يصبح بتنسيق ISO 8601 مع لاحقة `Z` (`2026-09-01T10:15:30.000Z`)، وهو نفس تنسيق `published_at` الخاص بمدخل سجل التغييرات. يستخدم `created_at` التنسيق `YYYY-MM-DD HH:MM:SS` بتوقيت UTC. يختلف التنسيقان داخل الكائن الواحد، لذا قم بتحليل كل حقل على حدة.

### التصويت

`POST /api/roadmap/:id/vote`

يقوم بتبديل حالة التصويت على عنصر واحد في خارطة الطريق. عمليات التصويت مجهولة ومرتبطة بعنوان IP الخاص بالمتصل بالإضافة إلى أول 50 حرفًا من User-Agent الخاص به. يؤدي الاستدعاء مرة أخرى إلى إزالة التصويت. يستجيب العنصر غير المعروف أو غير المنشور بـ `404 {"error": "Not found"}`.

```bash
curl -X POST https://updates.foura.ai/api/roadmap/12/vote
```

```json
{ "votes": 24, "voted": true }
```

يُبلّغ `voted` عن الحالة بعد الاستدعاء: `true` إذا تمت إضافة تصويتك، و`false` إذا تمت إزالته.

تقتصر نقاط نهاية roadmap، وهي `GET /api/roadmap` وهذه النقطة، على 30 طلبًا في الدقيقة لكل عنوان IP مصدر. عند تجاوز ذلك، تكون الاستجابة HTTP `429` مع `{"error": "Too many votes, slow down"}`. تحمل كل استجابة roadmap الترويسات `X-RateLimit-Limit` و`X-RateLimit-Remaining` و`X-RateLimit-Reset` (طابع زمني بتنسيق Unix بالثواني)، حتى تتمكن من إبطاء المعدل قبل الوصول إلى الحد الأقصى.

## المشكلات المعروفة

`GET /api/issues`

تُرجع المشكلات التي يتتبعها فريق دعم FourA.

```bash
curl "https://updates.foura.ai/api/issues?tab=open"
```

معلمات الاستعلام:

| المعلمة | النوع | القيمة الافتراضية | الوصف |
|-----------|------|---------|-------------|
| `tab` | string | `open` | `open` للمشكلات النشطة، و`resolved` للمحلولة/المغلقة |

```json
{
  "issues": [
    {
      "id": 5,
      "title": "...",
      "body": "Markdown description",
      "severity": "medium",
      "status": "investigating",
      "service_id": 3,
      "resolution": "",
      "opened_at": "2026-05-18T09:00:00Z",
      "resolved_at": null,
      "service_name": "API"
    }
  ]
}
```

| الحقل | النوع | الوصف |
|-------|------|-------------|
| `id` | integer | معرف المشكلة (ID) |
| `title` | string | ملخص موجز |
| `body` | string | وصف بتنسيق Markdown |
| `severity` | string | `low`، أو `medium`، أو `high`، أو `critical` |
| `status` | string | `open`، أو `investigating`، أو `resolved`، أو `closed` |
| `service_id` | integer or null | المعرف الرقمي للخدمة المتأثرة. `null` عندما لا تكون المشكلة مرتبطة بخدمة معينة. |
| `service_name` | string or null | الاسم المعروض للخدمة، تمت معالجته نيابة عنك. اقرأ هذه القيمة بدلا من تعيين `service_id` يدويا. |
| `resolution` | string | كيفية حل المشكلة. سلسلة فارغة طالما أن المشكلة ما تزال مفتوحة. |
| `opened_at` | string | تنسيق ISO 8601 مع لاحقة `Z` |
| `resolved_at` | string or null | تنسيق ISO 8601 مع لاحقة `Z`، وتكون `null` طالما أن المشكلة مفتوحة |

إن `service_id` هو مفتاح أجنبي رقمي، وليس الاسم اللطيف (slug) الذي تراه في صفحة الحالة. طابق المشكلات مع الخدمات باستخدام `service_name`.

حمولة المشكلة عبارة عن قائمة أعمدة ثابتة ولا تتضمن طابعا زمنيا للتعديل. رتب المشكلة أو حدد عمرها الزمني باستخدام `opened_at` و`resolved_at`. من بين المجموعات العامة الثلاث، تعيد إدخالات سجل التغييرات فقط `updated_at`. وتعيد عناصر خارطة الطريق `created_at` أيضا، بينما لا تعيد المشكلات أيا منهما.

تبويب `resolved` يعيد آخر 30 مشكلة تم حلها ويتوقف عندها. تبويب `open` يعيد جميع المشكلات.

## ملاحظات

- جميع نقاط النهاية (endpoints) عامة ولا تتطلب مفتاح API. تقتصر نقاط نهاية خارطة الطريق على 30 طلبا في الدقيقة لكل عنوان IP مصدر، بينما لا تخضع النقاط الأخرى لأي rate limit خاص بها حاليا، لذا تجنب استقصاء الحالة بمعدل يتجاوز ما يبرره التخزين المؤقت ومدته 15 ثانية.
- تأتي الاستجابات بتنسيق JSON عبر HTTPS. لا تقبل خارطة الطريق والمشكلات معاملات تقسيم الصفحات (paging). القيد الوحيد هو `?tab=resolved` على المشكلات، حيث يعيد 30 صفا.
- للحصول على نسخ نصية مجردة أو بتنسيق HTML الأولي من سجل التغييرات، استخدم خلاصة [`/rss`](https://updates.foura.ai/rss) بدلا من `/api/changelog`.

## ذو صلة

- [حالة الخدمة](https://foura.ai/docs/updates-portal/status): قراءة البيانات نفسها في المتصفح
- [سجل التغييرات](https://foura.ai/docs/updates-portal/changelog): تصفح الإدخالات مع عوامل التصفية وتقسيم الصفحات
- [خارطة الطريق](https://foura.ai/docs/updates-portal/roadmap): التصويت على العناصر في واجهة المستخدم
- [المشكلات المعروفة](https://foura.ai/docs/updates-portal/issues): قراءة المشكلات المفتوحة والتي تم حلها
- [بوابة التحديثات](https://foura.ai/docs/updates-portal/overview): نظرة عامة على القسم
