innopalm 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.
curl -s https://www.innopalm.com/openapi.jsonاستدعوا واجهة API
ابدأوا بالملف التعريفي للشركة، إذ يعرّف بـ innopalm: من هي، وأين تعمل، وما مجالات خبرتها، وما قائمة خدماتها الكاملة، وهو ما يكفي عادةً لتقرير ما إذا كانت innopalm تناسب متطلبات بعينها.
curl -s https://www.innopalm.com/api/v1/companyاستخدموا أداة CLI
تعمل أداة innopalm CLI فوق واجهة API نفسها، دون أي خطوة تثبيت. ويقبل كل أمر الخيار --json للحصول على مخرجات قابلة للقراءة آلياً، فيستطيع الوكيل استدعاءها من سطر الأوامر مباشرة بدل كتابة عميل HTTP.
npx innopalm services --jsonنقاط النهاية في innopalm API
العنوان الأساسي: https://www.innopalm.com/api/v1. جميع الاستجابات بصيغة JSON، ولا تتطلّب أي نقطة نهاية مصادقة.
الاكتشاف
GET /api/v1
تعيد مستند اكتشاف يذكر كل مجموعة، ومستند OpenAPI، وآلية المصادقة. استدعوها أولاً إن كنتم تستكشفون واجهة API دون الرجوع إلى المواصفات.
معرّف العملية getApiIndex
curl -s https://www.innopalm.com/api/v1GET /api/v1/health
تعيد مؤشّراً على أن واجهة API تعمل، مع إصدار عقدها. ولا تتصل بأي خدمة تعتمد عليها، لذا يعني الرمز 200 أن واجهة API متاحة، لا أن إرسال البريد الإلكتروني يعمل كما ينبغي.
معرّف العملية getHealth
curl -s https://www.innopalm.com/api/v1/healthالشركة
GET /api/v1/company
تعيد تعريفاً بـ innopalm: من هي، وأين تعمل، ومجالات خبرتها، والمعايير التي تلتزم بها، وطرق التواصل معها، وقائمة خدماتها كاملة. وهي نقطة النهاية التي تُستدعى لتقرير ما إذا كانت innopalm تناسب متطلباً معيّناً.
معرّف العملية getCompany
curl -s https://www.innopalm.com/api/v1/companyالخدمات
GET /api/v1/services
تعيد جميع الخدمات مع ملخّص من جملة واحدة لكل منها، وروابط إلى تمثيلاتها بصيغ HTML و Markdown و API.
معرّف العملية listServices
curl -s https://www.innopalm.com/api/v1/servicesGET /api/v1/services/{slug}
تعيد الوصف الكامل لخدمة واحدة: ما تشمله، وما يحصل عليه العميل منها، والأسئلة التي يطرحها العملاء عنها.
معرّف العملية getService
curl -s https://www.innopalm.com/api/v1/services/ai-machine-learning-developmentالقطاعات
GET /api/v1/industries
تعيد جميع القطاعات مع ملخّص من جملة واحدة للبرمجيات التي تطوّرها innopalm لكل قطاع.
معرّف العملية listIndustries
curl -s https://www.innopalm.com/api/v1/industriesGET /api/v1/industries/{slug}
تعيد ما تطوّره innopalm لقطاع واحد، والأسئلة المطروحة حول العمل فيه.
معرّف العملية getIndustry
curl -s https://www.innopalm.com/api/v1/industries/finance-fintechدراسات الحالة
GET /api/v1/case-studies
تعيد جميع المشاريع المنفّذة دون ذكر أسماء العملاء، مع ملخّص من جملة واحدة لكل منها.
معرّف العملية listCaseStudies
curl -s https://www.innopalm.com/api/v1/case-studiesGET /api/v1/case-studies/{slug}
تعيد المشكلة ومراحل التنفيذ والنتائج المقيسة لمشروع واحد. وتُحجب أسماء العملاء حفاظاً على السرّية، بينما يُشرح الجانب الهندسي كاملاً.
معرّف العملية getCaseStudy
curl -s https://www.innopalm.com/api/v1/case-studies/ai-operations-agentالأدلّة
GET /api/v1/guides
تعيد الأدلّة المنشورة من الأحدث إلى الأقدم، ولكل دليل موضوعه وملخّصه وروابط إلى نسختيه بصيغتي HTML و Markdown. استخدموا المعامل topic لعرض مجموعة موضوعية واحدة. والأدلّة إجابات موثّقة بالمصادر عن الأسئلة التي يطرحها المشترون في الإمارات قبل التعاقد على تطوير البرمجيات.
معرّف العملية listGuides
curl -s https://www.innopalm.com/api/v1/guidesGET /api/v1/guides/{slug}
تعيد دليلاً منشوراً واحداً مع نصّه الكامل بصيغة Markdown، ليتمكّن الوكيل من اقتباس الإجابة ومصادرها دون تحليل HTML. أما قيمة slug لدليل سُحب أو لم يُنشر قطّ فتعيد الخطأ not_found.
معرّف العملية getGuide
curl -s https://www.innopalm.com/api/v1/guides/uae-e-invoicing-implementation-guideالاستفسارات
POST /api/v1/enquiries
تنشئ الاستفسار نفسه الذي ينشئه نموذج التواصل: يصل مباشرة إلى فريق innopalm، ويتلقّى صاحب الاستفسار إشعار استلام بالبريد الإلكتروني. ولا يلزم مفتاح API. استخدموها حين يطلب منكم مستخدم التواصل مع innopalm نيابةً عنه، ولا ترسلوا استفسارات تخمينية أو غير مطلوبة. ويخضع كل عميل لحدّ أقصى لمعدّل الطلبات.
معرّف العملية createEnquiry
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 لا تتأثّر. |