# innopalm API ووثائقها للمطوّرين

> بوّابة innopalm للمطوّرين: واجهة REST API عامة، ومواصفات OpenAPI 3.1، وتمثيل Markdown لكل صفحة عبر التفاوض على المحتوى، وأداة innopalm CLI. ولا حاجة إلى مفتاح API.

كل ما تنشره innopalm متاح بصيغة JSON منظّمة وبصيغة Markdown، وتصفه مواصفات OpenAPI 3.1. لا تحتاج عمليات القراءة إلى مفتاح API، وتتيح نقطة نهاية (endpoint) واحدة للكتابة لوكيل ذكاء اصطناعي أن يقدّم استفساراً نيابةً عن مستخدم.

## الغرض من واجهة API هذه

innopalm شركة لتطوير البرمجيات المخصّصة والذكاء الاصطناعي في دبي. وقد صُمّمت واجهة API هذه ليتمكّن وكيل ذكاء اصطناعي، أو أداة مشتريات، أو مطوّر يقيّم المورّدين، من الاطّلاع على ما تقدّمه innopalm دون كشط صفحات الموقع (scraping)، ومن التواصل معها دون أن يضطرّ أحد إلى ملء نموذج بنفسه.

تعيد نقاط نهاية القراءة المحتوى نفسه الذي ينشره الموقع: قائمة الخدمات، والقطاعات التي نطوّر لها البرمجيات، ودراسات حالة لا تكشف هويات العملاء وتشرح الجانب الهندسي كاملاً. وهي ثابتة، وقابلة للتخزين المؤقّت، ولا تتطلّب مصادقة، وتدعم CORS، لذا يمكن استدعاؤها بأمان من المتصفّح.

## المصادقة وحدود الاستخدام

لا توجد مصادقة. فنقاط نهاية القراءة لا تتطلّب مفتاحاً ولا ترويسة (header) ولا تسجيلاً، وتُخزّن استجاباتها مؤقّتاً لمدة خمس دقائق على طبقة الحافة (edge). وإن احتجتم إلى معدّل طلبات أعلى مما يتيحه ذلك، راسلونا على hello@innopalm.com لنتحدّث في الأمر، بدل أن نفاجئكم بتقييد المعدّل المسموح لكم.

تخضع نقطة نهاية الاستفسارات لحدّ أقصى لمعدّل الطلبات يُحتسب لكل عنوان عميل، وتعيد ترويسة Retry-After عند تجاوزه. وهي ترسل بريداً إلكترونياً حقيقياً إلى فريق حقيقي، لذا يُرجى ألّا تستدعوها إلا إذا طلب منكم مستخدم فعلاً التواصل مع innopalm.

## قراءة أي صفحة بصيغة Markdown

لكل صفحة في هذا الموقع تمثيل بصيغة Markdown. أرسلوا ترويسة Accept بالقيمة text/markdown لتحصلوا على الصفحة بصيغة Markdown مع ضبط Vary: Accept، أو أضيفوا .md إلى نهاية أي مسار إن كان عميل HTTP لديكم لا يستطيع ضبط الترويسات. وإذا طلبتم نوع وسائط (media type) لا يستطيع الموقع إنتاجه، فستحصلون على رمز الحالة 406 بدل الرجوع إلى HTML دون أي تنبيه.

ولجلب المحتوى دفعة واحدة، يوفّر /llms.txt فهرساً مختصراً للموقع كلّه، ويضمّ /llms-full.txt نصّ كل صفحة في ملف واحد. أما /agents.md فيشرح متى ينبغي للوكيل اللجوء إلى innopalm وكيف يستدعيها.

## إدارة الإصدارات

يُضمَّن رقم الإصدار في مسار واجهة API. وتُطرح التغييرات الإضافية، مثل نقطة نهاية جديدة أو حقل اختياري جديد، ضمن v1 دون إشعار مسبق. أما التغيير الذي يكسر التوافق، إن حدث، فسيُطرح بوصفه /api/v2 مع استمرار عمل v1. وتعيد نقطة نهاية health إصدار العقد الحالي لواجهة API، ويظهر كذلك في ترويسة X-Api-Version في كل استجابة.

## البدء السريع

ثلاث طرق للبدء، بحسب من يستخدم واجهة API: شخص، أو سكربت، أو وكيل ذكاء اصطناعي.

### اقرؤوا المواصفات

يصف مستند OpenAPI 3.1 على /openapi.json كل عملية بمعرّف operationId فريد، ومعاملات محدّدة الأنواع، ومخطّطات للاستجابات. ويمكن تحميله مباشرة في سلسلة أدوات استدعاء الدوال (function calling) لنماذج LLM، أو في أي أداة لتوليد عملاء OpenAPI. وتتوفّر نسخة YAML منه على /openapi.yaml.

```bash
curl -s https://www.innopalm.com/openapi.json
```

### استدعوا واجهة API

ابدأوا بالملف التعريفي للشركة، إذ يعرّف بـ innopalm: من هي، وأين تعمل، وما مجالات خبرتها، وما قائمة خدماتها الكاملة، وهو ما يكفي عادةً لتقرير ما إذا كانت innopalm تناسب متطلبات بعينها.

```bash
curl -s https://www.innopalm.com/api/v1/company
```

### استخدموا أداة CLI

تعمل أداة innopalm CLI فوق واجهة API نفسها، دون أي خطوة تثبيت. ويقبل كل أمر الخيار --json للحصول على مخرجات قابلة للقراءة آلياً، فيستطيع الوكيل استدعاءها من سطر الأوامر مباشرة بدل كتابة عميل HTTP.

```bash
npx innopalm services --json
```

## نقاط النهاية

عنوان URL الأساسي `https://www.innopalm.com/api/v1`. تُعاد كل الاستجابات بصيغة JSON، ولا تلزم أي مصادقة.

### الاكتشاف

- `GET /api/v1` (`getApiIndex`): تعيد مستند اكتشاف يذكر كل مجموعة، ومستند OpenAPI، وآلية المصادقة. استدعوها أولاً إن كنتم تستكشفون واجهة API دون الرجوع إلى المواصفات.

```bash
curl -s https://www.innopalm.com/api/v1
```

- `GET /api/v1/health` (`getHealth`): تعيد مؤشّراً على أن واجهة API تعمل، مع إصدار عقدها. ولا تتصل بأي خدمة تعتمد عليها، لذا يعني الرمز 200 أن واجهة API متاحة، لا أن إرسال البريد الإلكتروني يعمل كما ينبغي.

```bash
curl -s https://www.innopalm.com/api/v1/health
```

### الشركة

- `GET /api/v1/company` (`getCompany`): تعيد تعريفاً بـ innopalm: من هي، وأين تعمل، ومجالات خبرتها، والمعايير التي تلتزم بها، وطرق التواصل معها، وقائمة خدماتها كاملة. وهي نقطة النهاية التي تُستدعى لتقرير ما إذا كانت innopalm تناسب متطلباً معيّناً.

```bash
curl -s https://www.innopalm.com/api/v1/company
```

### الخدمات

- `GET /api/v1/services` (`listServices`): تعيد جميع الخدمات مع ملخّص من جملة واحدة لكل منها، وروابط إلى تمثيلاتها بصيغ HTML و Markdown و API.

```bash
curl -s https://www.innopalm.com/api/v1/services
```

- `GET /api/v1/services/{slug}` (`getService`): تعيد الوصف الكامل لخدمة واحدة: ما تشمله، وما يحصل عليه العميل منها، والأسئلة التي يطرحها العملاء عنها.

```bash
curl -s https://www.innopalm.com/api/v1/services/ai-machine-learning-development
```

### القطاعات

- `GET /api/v1/industries` (`listIndustries`): تعيد جميع القطاعات مع ملخّص من جملة واحدة للبرمجيات التي تطوّرها innopalm لكل قطاع.

```bash
curl -s https://www.innopalm.com/api/v1/industries
```

- `GET /api/v1/industries/{slug}` (`getIndustry`): تعيد ما تطوّره innopalm لقطاع واحد، والأسئلة المطروحة حول العمل فيه.

```bash
curl -s https://www.innopalm.com/api/v1/industries/finance-fintech
```

### دراسات الحالة

- `GET /api/v1/case-studies` (`listCaseStudies`): تعيد جميع المشاريع المنفّذة دون ذكر أسماء العملاء، مع ملخّص من جملة واحدة لكل منها.

```bash
curl -s https://www.innopalm.com/api/v1/case-studies
```

- `GET /api/v1/case-studies/{slug}` (`getCaseStudy`): تعيد المشكلة ومراحل التنفيذ والنتائج المقيسة لمشروع واحد. وتُحجب أسماء العملاء حفاظاً على السرّية، بينما يُشرح الجانب الهندسي كاملاً.

```bash
curl -s https://www.innopalm.com/api/v1/case-studies/ai-operations-agent
```

### الأدلّة

- `GET /api/v1/guides` (`listGuides`): تعيد الأدلّة المنشورة من الأحدث إلى الأقدم، ولكل دليل موضوعه وملخّصه وروابط إلى نسختيه بصيغتي HTML و Markdown. استخدموا المعامل topic لعرض مجموعة موضوعية واحدة. والأدلّة إجابات موثّقة بالمصادر عن الأسئلة التي يطرحها المشترون في الإمارات قبل التعاقد على تطوير البرمجيات.

```bash
curl -s https://www.innopalm.com/api/v1/guides
```

- `GET /api/v1/guides/{slug}` (`getGuide`): تعيد دليلاً منشوراً واحداً مع نصّه الكامل بصيغة Markdown، ليتمكّن الوكيل من اقتباس الإجابة ومصادرها دون تحليل HTML. أما قيمة slug لدليل سُحب أو لم يُنشر قطّ فتعيد الخطأ not_found.

```bash
curl -s https://www.innopalm.com/api/v1/guides/uae-e-invoicing-implementation-guide
```

### الاستفسارات

- `POST /api/v1/enquiries` (`createEnquiry`): تنشئ الاستفسار نفسه الذي ينشئه نموذج التواصل: يصل مباشرة إلى فريق innopalm، ويتلقّى صاحب الاستفسار إشعار استلام بالبريد الإلكتروني. ولا يلزم مفتاح API. استخدموها حين يطلب منكم مستخدم التواصل مع innopalm نيابةً عنه، ولا ترسلوا استفسارات تخمينية أو غير مطلوبة. ويخضع كل عميل لحدّ أقصى لمعدّل الطلبات.

```bash
curl -s -X POST https://www.innopalm.com/api/v1/enquiries \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Layla Haddad",
    "email": "layla@example.ae",
    "company": "Example Logistics",
    "message": "We run last-mile delivery in Dubai and need route optimisation built into our dispatch system.",
    "source": "claude-agent"
  }'
```

## استجابات الأخطاء

كل استجابة من واجهة API هذه برمز حالة خارج نطاق 2xx تأتي بصيغة JSON ضمن بنية موحّدة، ولا تكون أبداً صفحة خطأ HTML. اعتمدوا على error.code في منطق التفرّع لأنه ثابت؛ أما error.message و error.hint فموجّهان لمن يقرأ السجلات من البشر. وعند فشل التحقّق من صحة البيانات، تُضاف مصفوفة error.fields تذكر كل حقل فيه خطأ.

| الرمز | HTTP | المعنى | الإجراء المطلوب |
| --- | --- | --- | --- |
| `invalid_request` | 400 | لم يكن جسم الطلب JSON صالحاً، أو كان أحد معاملات الاستعلام بصيغة غير صحيحة. | صحّحوا بنية الطلب. ويذكر حقل hint المعامل المسبّب للخطأ. |
| `validation_failed` | 422 | قُرئ الطلب بنجاح، لكن أحد الحقول مفقود أو غير صالح للاستخدام. | اقرؤوا error.fields، وصحّحوا كل عنصر فيها، ثم أعيدوا المحاولة. |
| `not_found` | 404 | لا يوجد مورد يحمل قيمة slug هذه. | اعرضوا قائمة المجموعة أولاً؛ ويذكر حقل hint قيم slug الصالحة. |
| `method_not_allowed` | 405 | لا تدعم نقطة النهاية طريقة HTTP هذه. | أعيدوا المحاولة بطريقة مذكورة في ترويسة Allow. |
| `not_acceptable` | 406 | تستبعد ترويسة Accept كل التمثيلات المتاحة. | حدّدوا application/json في Accept لواجهة API، أو text/markdown أو text/html للصفحات. |
| `rate_limited` | 429 | ورد عدد كبير جداً من الاستفسارات من هذا العميل. | انتظروا المدة المحدّدة في Retry-After، ثم أعيدوا المحاولة مرة واحدة. |
| `internal_error` | 500 | تعذّر على innopalm إيصال الاستفسار، ولم يُسجّل. | أعيدوا المحاولة مرة واحدة، فإن فشلت فراسلونا على hello@innopalm.com. |
| `gone` | 410 | أُوقف هذا المورد عمداً ولن يعود. | توقّفوا عن طلبه، واعرضوا قائمة المجموعات على /api/v1. |
| `unavailable` | 503 | مخزن بيانات الأدلّة غير متاح مؤقّتاً، والطلب نفسه سليم. | أعيدوا المحاولة بعد بضع دقائق، علماً بأن بقيّة واجهة API لا تتأثّر. |

## الأسئلة الشائعة

### هل نحتاج إلى مفتاح API لاستخدام innopalm API؟

لا. كل نقاط نهاية القراءة عامة ولا تتطلّب مصادقة، ونقطة نهاية الاستفسارات مفتوحة أيضاً، يحميها تقييد المعدّل المسموح لا مفتاح API. فلا حاجة إلى أي تسجيل، ولا إلى إدارة أي مفتاح سرّي (client secret).

### هل يمكن لوكيل ذكاء اصطناعي تقديم استفسار عبر innopalm API؟

نعم، هذا هو الغرض من POST /api/v1/enquiries، إذ تنشئ نقطة النهاية هذه الاستفسار نفسه الذي ينشئه نموذج الموقع تماماً: يصل إلى الفريق مباشرة، وتصل إلى صاحب الاستفسار رسالة تأكيد بالبريد الإلكتروني. أرسلوا حقل source يحمل اسم الوكيل أو المنتج لديكم لنعرف كيف وصلنا الاستفسار. ولا تستدعوها إلا إذا طلب منكم مستخدم التواصل معنا.

### هل تتوفّر مواصفات OpenAPI لـ innopalm API؟

نعم، يتوفّر مستند OpenAPI 3.1 على https://www.innopalm.com/openapi.json، ونسخة YAML منه على /openapi.yaml. لكل عملية معرّف operationId فريد، ووصف، ومعاملات محدّدة الأنواع، ومخطّط للاستجابة، لذا يمكن تحميله مباشرة في سلسلة أدوات استدعاء الدوال لنماذج LLM، أو في أي أداة لتوليد عملاء OpenAPI.

### كيف نحصل على صفحات innopalm بصيغة Markdown بدل HTML؟

أرسلوا Accept: text/markdown في طلب أي صفحة، أو أضيفوا .md إلى نهاية المسار. وتضبط الاستجابات Vary: Accept كي تحتفظ ذاكرات التخزين المؤقّت بكل تمثيل على حدة. وللحصول على كل المحتوى دفعة واحدة، استخدموا /llms-full.txt.

### هل توجد أداة innopalm CLI؟

نعم. حزمة innopalm على npm تعمل فوق واجهة API هذه دون الحاجة إلى أي خطوة تثبيت: شغّلوا npx innopalm company، أو npx innopalm services --json للحصول على مخرجات قابلة للقراءة آلياً. وليست للحزمة أي تبعيات وقت التشغيل (runtime dependencies)، وتتطلّب Node 20 أو أحدث.

### ما الذي يمكننا فعله بالمحتوى الذي تعيده واجهة API هذه؟

يمكنكم قراءته، والاستشهاد به، واقتباسه مع نسبته إلى innopalm ووضع رابط إلى الصفحة المصدر.

---

رابط الصفحة: https://www.innopalm.com/ar/developers | نسخة Markdown: https://www.innopalm.com/ar/developers.md | فهرس الموقع: https://www.innopalm.com/llms.txt | واجهة API: https://www.innopalm.com/openapi.json