مفاتيح API

تفتح مفاتيح API الوصول البرمجي إلى dAio Business. فهي تتيح لتطبيقاتك وبرامجك النصية وأنظمتك الخاصة الاستعلام من المنصة مباشرةً — بيانات الطقس، وجودة الهواء، وحبوب اللقاح، والأحوال البحرية، والذكاء القطاعي — دون المرور عبر الواجهة الإلكترونية. إنها نقطة الانطلاق لتصنيع تكاملاتك: تغذية نظام ERP، أو تشغيل معالجة تجارية، أو عرض التوقعات في لوحة المعلومات الخاصة بك.

يصادق كل مفتاح على الطلبات نيابةً عن مؤسستك ويرث صلاحياتها. وبالاقتران مع الخطافات الإلكترونية، يمنحك قناةً متكاملة: فأنت تستعلم من dAio عند الطلب عبر API، وdAio يُنبّهك في الوقت الفعلي عبر الخطافات الإلكترونية.

نصيحة: أنشئ مفتاحًا منفصلًا لكل استخدام (خدمة، أو بيئة، أو شريك). سيمكّنك ذلك من إبطال أحدها دون تعطيل الأخرى، ومن تتبّع أي تكامل يستهلك ماذا بدقة.

فائدة مفتاح API

الحاجة	يتيح مفتاح API…
التكامل	ربط dAio بنظام معلوماتك (ERP، GMAO، BI) دون تدخّل بشري.
الأتمتة	إطلاق عمليات معالجة مجدولة (الجلب اليومي للتوقعات، تسجيل نقاط المخاطر).
النشر	عرض بيانات dAio في تطبيقاتك أو بواباتك الخاصة.
مشاركة مُحكمة	منح شريك وصولًا محدودًا وقابلًا للإبطال، دون إنشاء حساب مستخدم.

معلومة: الوصول إلى API مقصور على الخطط المدفوعة. تتلقى المؤسسة التي ليس لديها اشتراك نشط استجابة 403 (« API access requires a paid plan ») على كل طلب.

إنشاء مفتاح

إنشاء مفتاح مقصور على المالك (owner) والمسؤولين (admin) في المؤسسة. ولا يمكن للأدوار الأخرى إنشاء مفتاح أو إبطاله.

1. انتقل إلى الإعدادات > مفاتيح API.
2. انقر على مفتاح جديد في أعلى اليمين.
3. أدخل اسمًا وصفيًا يحدد استخدام المفتاح (مثل « Backend production »، « موصّل Power BI »، « تكامل الشريك X »).
4. انقر على إنشاء.
5. يظهر المفتاح الكامل في شريط أخضر: انسخه فورًا باستخدام زر النسخ.

تنبيه: يُعرض المفتاح الكامل مرة واحدة فقط، لحظة إنشائه. ولا يُعاد عرضه بعد ذلك أبدًا — إذ لا تحتفظ المنصة إلا ببصمة مشفّرة منه. وإذا فقدته، فسيتعيّن عليك توليد مفتاح جديد. خزّنه دون تأخير في مدير أسرار (Vault، AWS Secrets Manager، متغيرات بيئة مشفّرة).

بمجرد إنشائه، يظهر المفتاح في القائمة مع اسمه، وبادئته (الأحرف الأولى، لتمييزه دون كشفه)، ومؤشر حالة (أخضر = نشط، أحمر = مُبطَل)، وتاريخ آخر استخدام له.

استخدام مفتاح

يجب أن تتضمّن جميع الطلبات الموجهة إلى dAio API مفتاحك في ترويسة HTTP X-API-Key. عنوان API الأساسي هو https://api-dev.daio.app، وتُسبَق نقاط الوصول B2B بالبادئة /api/v1/.

curl -H "X-API-Key: VOTRE_CLE_API" \
  "https://api-dev.daio.app/api/v1/weather/current?lat=48.8566&lon=2.3522"

تنبيه: الترويسة المتوقعة هي فعلًا X-API-Key، وليست Authorization: Bearer. أي مفتاح غير صالح أو مُبطَل أو مُرسَل في ترويسة أخرى يُعيد استجابة 401 (« Invalid API key »).

راجع الوثائق التقنية لـ API للاطلاع على القائمة الكاملة لنقاط الوصول (الطقس، التوقعات الساعية، جودة الهواء، حبوب اللقاح، الأحوال البحرية، المعالجة الدفعية) وعلى تنسيق الاستجابات.

حدود معدل الطلبات

لضمان استقرار الخدمة، يخضع كل مفتاح لـ حد ساعي لمعدل الطلبات. والعدّاد خاص بكل مفتاح ويُعاد ضبطه كل ساعة.

الخطة	الطلبات في الساعة
Free / no subscription	لا يوجد وصول إلى API
Solo · Team · Enterprise (dAio Business)	20 000

عند بلوغ الحد، يُعيد API استجابة 429 (« Rate limit exceeded ») مصحوبة بترويسة Retry-After تشير إلى المهلة قبل إعادة المحاولة.

معلومة: يختلف هذا الحد الساعي عن الحصة الشهرية من الطلبات المتضمنة في باقتك. اطّلع على تفاصيل الحصص حسب الخطة في قسم الاشتراك.

تدوير مفتاح

يعيد التدوير توليد مفتاح مع الحفاظ على اسمه وموضعه في القائمة. استخدمه لتجديد أسرارك دوريًا دون إعادة تهيئة تكاملك بالكامل.

1. في القائمة، انقر على أيقونة التدوير (سهم دائري) أمام المفتاح.
2. أكّد العملية.
3. تظهر القيمة الجديدة مرة واحدة فقط — انسخها فورًا.
4. حدّث تطبيقاتك بهذه القيمة الجديدة.

نصيحة: خطّط لتدوير كل 90 يومًا، وبشكل منهجي بعد مغادرة موظف كان يملك وصولًا إلى الأسرار أو عند الاشتباه في حدوث تسريب.

إبطال مفتاح

لقطع وصول مفتاح مخترَق أو غير مستخدم:

1. في القائمة، انقر على أيقونة الحذف (سلة المهملات) أمام المفتاح.
2. أكّد الإبطال.

الإبطال فوري ولا رجعة فيه. أي طلب يستخدم المفتاح المُبطَل سيتلقى على الفور استجابة 401. ويبقى المفتاح ظاهرًا في القائمة، مُعلَّمًا بـ مُبطَل، لأغراض السجلّ التاريخي.

أمان المفاتيح

يعادل مفتاح API كلمة مرور: فأي شخص يحوزه يمكنه الاستعلام من API بصلاحيات مؤسستك.

تنبيه: لا تودِع مطلقًا مفتاحًا في شيفرتك المصدرية أو في مستودع Git، حتى وإن كان خاصًا. ويُعدّ أي مفتاح يُدفَع عن طريق الخطأ إلى مستودع مخترَقًا — أبطِله ودوّره دون انتظار. ولا ترسله أبدًا عبر البريد الإلكتروني أو المراسلة أو تذكرة الدعم بنص صريح.

• خزّن المفاتيح في مدير أسرار أو في متغيرات بيئة، وليس أبدًا بشكل ثابت داخل الشيفرة.
• لا تكشفها من جهة العميل (تطبيق ويب، أو محمول، أو JavaScript المتصفح): يجب أن ينطلق أي استدعاء لـ API من خادمك.
• افصِل: مفتاح لكل بيئة (الإنتاج، الاختبار) ولكل استخدام.
• راقب تاريخ آخر استخدام: المفتاح الخامل منذ مدة طويلة مفتاح يجب إبطاله.

أفضل الممارسات

• سمِّ بوضوح كل مفتاح وفق استخدامه وبيئته لتعرف بنظرة واحدة ما الذي يغذّيه.
• طبّق مبدأ الحد الأدنى من الامتيازات: أنشئ مفاتيح مخصصة وقابلة للإبطال بدلًا من مفتاح واحد مشترك بين جميع تكاملاتك.
• أتمت التدوير كل 90 يومًا وأدرجه في إجراءات مغادرة الموظفين.
• عالج رموز 429 من جهة العميل: التزم بترويسة Retry-After وزِّع استدعاءاتك بدلًا من تتالي الطلبات.
• أبطِل فورًا أي مفتاح يُشتبَه في اختراقه — يسري الإبطال دون تأخير.
• وثّق داخليًا أي مفتاح يخدم ماذا ومن المسؤول عنه، لتكون عمليات تدقيق الأمان ميسّرة.

نصيحة: اربط مفاتيح API الخاصة بك بـالخطافات الإلكترونية لتكامل متكامل — استعلم من dAio عند الطلب، ودع dAio يُنبّهك بالأحداث في الوقت الفعلي.