بناء تكامل Alkax وتشغيله

تجمع منصة مطوري Alkax كل تكامل في مشروع. يبدأ كل مشروع ببيئتي Sandbox وProduction معزولتين، فلا تتجاوز أنشطة الاختبار وبيانات الاعتماد والحصص والسجلات وخطافات الويب حدود البيئة.

افتح لوحة المطورين على https://alkax.io/developers لإنشاء المشاريع وإدارتها.

نموذج المشروع

يمتلك المشروع حسابك أو مؤسسة. قد تقيّد سياسة المؤسسة إنشاء المشاريع والنطاقات المتاحة والحصة وعمر بيانات الاعتماد والوصول إلى الإنتاج.

أدوار المشروع هي:

الدور	الوصول المعتاد
المالك	دورة حياة المشروع والأعضاء وبيانات الاعتماد والإعدادات بالكامل
المطوّر	بناء التكامل وتشغيله
المحلّل	فحص الاستخدام والسلامة التشغيلية وسجلات الطلبات
مطّلع على الفوترة	مراجعة الاستخدام المرتبط بالفوترة

أنشئ مشروعك الأول

افتح لوحة المطورين.
اختر مشروع جديد (New project) وحدّد حسابًا أو مؤسسة كمالك.
افتح بيانات الاعتماد (Credentials) وأصدر بيانات اعتماد Sandbox بالنطاقات التي تحتاجها فقط.
انسخ السر فورًا. لا تخزّن Alkax إلا تجزئته المشتقة ولا تستطيع عرضه مجددًا.
استدعِ مثال Sandbox ثابتًا أو استخدم ساحة التجربة في اللوحة.
افحص الاستخدام (Usage) والسجلات (Logs) باستخدام معرّف الطلب المُعاد.

بيانات الاعتماد والنطاقات

أرسل بيانات اعتماد الخادم في ترويسة X-Alkax-Key:

X-Alkax-Key: ak_test_<key-id>.<secret>

تبدأ مفاتيح Sandbox بـ ak_test_ ومفاتيح Production بـ ak_live_. تشمل النطاقات المتاحة:

النطاق	ما يسمح به
`places:read`	قراءة بيانات الأماكن
`geocode:read`	البحث والترميز الجغرافي
`delivery:read`	قراءة حالة تأكيد التوصيل
`delivery:write`	إنشاء تأكيدات التوصيل وتعديلها

يتوفر ترميز Grid وفكه كعمليتي API منفصلتين باستخدام X-Alkax-Key والنطاق places:read؛ راجع دليل عناوين Alkax Grid.

ينشئ التدوير بيانات اعتماد بديلة. انشر البديل قبل إلغاء المفتاح السابق. يسري الإلغاء وانتهاء الصلاحية وتعليق المشروع أو البيئة على الطلبات اللاحقة.

استحقاق الاشتراك والاستخدام

يخضع استخدام API للمطورين لاشتراك مالك المشروع ولسياسة المؤسسة المنطبقة.

الخطة	استحقاق API للمطورين
المجانية Free	Sandbox فقط، حتى 1,000 طلب شهريًا
Pro الشهرية أو السنوية	Sandbox وProduction، حتى 50,000 طلب شهريًا
Enterprise	Sandbox وProduction، دون حد افتراضيًا

تُشارك حصة الخطة بين جميع المشاريع والبيئات المفوترة للحساب نفسه. قد تفرض حدود المشروع والمؤسسة والبيئة سقفًا أقل؛ ولا يمكنها زيادة حصة الاشتراك.

عند انتهاء الاشتراك المدفوع أو تعطيله، تتلقى بيانات اعتماد Production الحالية 402 subscription_required. وعند نفاد الحصة الشهرية، تتلقى الطلبات 429 quota_exceeded حتى فترة الفوترة التالية أو ترقية الخطة.

بيئة Sandbox حتمية النتائج

تستخدم بيانات اعتماد Sandbox مسار المصادقة وعقود نقاط النهاية نفسها الخاصة بالإنتاج مع عزل الآثار الجانبية والاستخدام.

export ALKAX_API="https://api.alkax.io"
export ALKAX_KEY="ak_test_<key-id>.<secret>"

curl "$ALKAX_API/api/v1/sandbox/fixtures/valid-high-confidence" \
  --header "X-Alkax-Key: $ALKAX_KEY" \
  --header "Accept: application/json"

تشمل معرّفات الأمثلة الثابتة:

المثال الثابت	النتيجة
`valid-high-confidence`	قابل للتوصيل بثقة عالية
`ambiguous`	يُنصح بطلب توضيح
`weak-access`	عنوان صالح مع ثقة ضعيفة في المدخل أو الوصول
`not-found`	عنوان غير معروف
`conflicting-evidence`	أدلة متعارضة وثقة منخفضة

استخدم سيناريوهات أخطاء Sandbox وهي error-403 وerror-404 وerror-409 وerror-429 وerror-500 لاختبار معالجة الإخفاقات. واستخدم بيانات اعتماد غير صالحة أو ملغاة لاختبار مسار 401 الحقيقي.

معرّفات الطلبات والاستخدام والسجلات

تتضمن كل استجابة API للمطورين X-Request-Id. تربط القيمة نفسها الاستجابة بسجلات الطلبات وتشخيصات الدعم.

تسجّل اللوحة بيانات وصفية تحافظ على الخصوصية، مثل قالب المسار والطريقة والحالة وزمن الاستجابة وأثر الحصة والبيئة واسم بيانات الاعتماد. وتستبعد بيانات الاعتماد وحقول الحمولة الحساسة.

خطافات الويب

افتح خطافات الويب (Webhooks)، واختر بيئة وأدخل وجهة HTTPS عامة وحدّد نوع الحدث من القائمة المنسدلة. تشمل أحداث المشروع المدعومة:

delivery.confirmation.created
delivery.confirmation.cancelled

يُعرض سر التوقيع مرة واحدة. تستخدم Sandbox وProduction قواعد التوقيع نفسها بأسرار مختلفة.

تتضمن طلبات خطاف الويب:

X-Alkax-Event-Id: <UUID>
X-Alkax-Timestamp: <Unix seconds>
X-Alkax-Signature: v1=<lowercase HMAC-SHA256>

احسب التوقيع المتوقع على <timestamp>.<raw-body> وارفض الطوابع الزمنية القديمة وقارن التوقيعات بزمن ثابت وأزل التكرار حسب معرّف الحدث. تستطيع اللوحة إرسال حدث اختبار وعرض محاولات التسليم ومقتطفات استجابة آمنة وإعادة تسليم حدث فاشل يدويًا.

ترفض Alkax وجهات الحلقة المحلية والشبكات الخاصة والروابط المحلية والوجهات التي يحلّها DNS إلى عناوين خاصة. ولا تتبع عمليات إعادة التوجيه.

الجاهزية للإنتاج

قبل إصدار بيانات اعتماد Production:

تأكّد من اشتراكك والوصول إلى Production؛
قلّل نطاقات بيانات الاعتماد؛
أكمل طلب Sandbox ناجحًا؛
اختبر معالجة الإخفاقات واستجابات الحصص؛
تحقّق من إمكانية الوصول إلى خطاف الويب ومن التوقيعات؛
اضبط قيود الوصول المتاحة حيث يلزم؛
تأكّد من عدم وجود مفتاح ak_test_ في إعدادات Production.

تابع مع البدء السريع مع API أو دليل المصادقة أو مرجع API.

نموذج المشروع​

أنشئ مشروعك الأول​

بيانات الاعتماد والنطاقات​

استحقاق الاشتراك والاستخدام​

بيئة Sandbox حتمية النتائج​

معرّفات الطلبات والاستخدام والسجلات​

خطافات الويب​

الجاهزية للإنتاج​