إنتقل إلى المحتوى الرئيسي

نفّذ أول طلب إلى API

يستخدم هذا الدليل مشروعًا في منصة المطورين وبيئة Sandbox ذات النتائج الحتمية. وهو يختبر مسار المصادقة نفسه المستخدم في Production دون إحداث آثار في الإنتاج.

قبل البدء​

تحتاج إلى:

  • حساب Alkax لديه وصول إلى لوحة المطورين؛
  • مشروع وبيئة Sandbox التابعة له؛
  • بيانات اعتماد Sandbox بالنطاق delivery:read للمثال الثابت الأول؛
  • بيئة خلفية أو خادم آمن؛
  • عنوان API الأساسي: https://api.alkax.io.

احفظ بيانات الاعتماد في مدير أسرار واحجبها من سجلات التطبيق.

افتح https://alkax.io/developers وأنشئ مشروعًا وأصدر بيانات اعتماد Sandbox من بيانات الاعتماد (Credentials). انسخ السر عند عرضه؛ فلا يمكن استرجاعه لاحقًا.

اضبط متغيرات الطلب​

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

نفّذ طلب Sandbox بنتيجة حتمية​

استدعِ مثالًا ثابتًا ذا إصدار يمكن تشغيله بأمان في التطوير المحلي والتكامل المستمر:

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

تتضمن الاستجابة نتيجة ثابتة وترويسة X-Request-Id. استخدم معرّف الطلب للعثور عليه في تبويب السجلات (Logs) في لوحة المطورين.

الأمثلة الثابتة الأخرى هي ambiguous وweak-access وnot-found وconflicting-evidence. تستطيع ساحة التجربة في اللوحة تشغيل الأمثلة نفسها وتوليد أمثلة curl وTypeScript وPython وC#.

انتقل إلى نقطة نهاية أعمال​

أصدر بيانات اعتماد بالنطاق المطلوب فقط، ثم استدعِ نقطة النهاية باستخدام ترويسة X-Alkax-Key نفسها. لتأكيد المستلم قبل الإرسال، اتبع دليل Delivery Intelligence.

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

عالج الاستجابة​

  • اعتبر حالة HTTP النتيجة الأساسية.
  • احفظ المعرّفات الثابتة ورموز الأخطاء المقروءة آليًا ومعرّف الطلب.
  • استخدم معرّفات آمنة لإعادة المحاولة حيث يطلب الدليل ذلك.
  • طبّق التراجع عند استجابات 429 و5xx المؤقتة.
  • لا تُعد طلبًا غير صالح دون تعديل.

راجع الأخطاء وإعادة المحاولة لنموذج الاستجابة الشائع.

تابع​

أكمل تكاملًا يعمل​

بعد طلب Sandbox الأول، تابع مع تكامل التوصيل والإرجاع ودليل وصفات خطافات الويب. المثال الثابت مثال عنوان؛ ولا ينشئ شحنة. استخدم واجهات API ذات الإصدارات ومسارات Sandbox الموثّقة لاختبار دورة حياة اصطناعية كاملة قبل الانتقال إلى Production.