في هذه الصفحة
ما ستفعله#
تنشئ حساباً، وتشترك في منتج، وتضيفه إلى التطبيق الذي يحمل مفتاحك، ثم ترسل أول طلب. تستخدم بيئة Sandbox، فلا يصل شيء مما ترسله إلى بيانات حيّة.
قبل أن تبدأ#
- عميل قادر على إرسال طلبات HTTPS. تستخدم الأمثلة cURL وNode.js وPython.
- بريد إلكتروني تستطيع قراءته: لا يصلح الحساب للاستخدام إلا بعد أن تفتح الرابط المرسَل إليه.
- المنتج الذي تريد استدعاءه. لا ينجح الاستدعاء إلا على منتج اشترك فيه تطبيقك، وتتطلب بعض المنتجات موافقة المزوّد، أو إكمال اعرف عميلك (KYC) أو اعرف منشأتك (KYB)، قبل أن يصبح الاشتراك نشطاً.
لقطات الشاشة مأخوذة من بيئة التطوير الخاصة بالمنصة، فتنتهي عناوين البوابة فيها بـ -dev أو -stgdev. استخدم العنوان الذي تعرضه لك صفحة المنتج.
الخطوة الأولى: أنشئ حساباً#
- افتح انشاء حساب. املأ الاسم الأول واسم العائلة واسم المستخدم والبريد الإلكتروني وكلمة مرور من 8 إلى 42 حرفاً تحوي رقماً وحرفاً صغيراً وحرفاً كبيراً وواحداً من
# ? ! @ $ % ^ & * -. - اختر نوع الحساب: فردي لنفسك. أما شركة فهو للشركات، ويحتاج إلى بريد إلكتروني للشركة: أول من يسجّل شركةً يصبح مسؤول منشأتها، ويبقى طلب تسجيل الزميل التالي بانتظار موافقة هذا المسؤول (الحساب والمنشأة).
- وافق على الشروط واضغط إنشاء حساب.
ينشئ التسجيل لك تطبيقين هما Default App (Testing) لـ Sandbox وDefault App (Prod) لبيئة الإنتاج، ولكلٍّ منهما مفتاح واحد.
الخطوة الثانية: أكّد بريدك الإلكتروني#
افتح الرابط في الرسالة التي أرسلتها لك المنصة. مدّة صلاحيته 24 ساعة، ويفتح صفحة تؤكد العنوان وتنقلك إلى تسجيل الدخول. وإن لم تصل رسالة فحاول تسجيل الدخول: تنقلك المنصة إلى صفحة تفقّد بريدك، حيث تُدخل بريدك وتطلب رابطاً جديداً. وتسمح برسالة واحدة في الدقيقة.
الخطوة الثالثة: سجّل الدخول#
سجّل الدخول باسم المستخدم أو بريدك الإلكتروني وكلمة المرور. تصل إلى السوق.
الخطوة الرابعة: اشترك في منتج#
- افتح منتجاً في السوق ثم علامة تبويب التسعير. تعرض العلامة ما يقدّمه المزوّد: منتجاً مجانياً، أو حزمة، أو خطة تُسعَّر لكل طلب، أو أسعاراً لكل نقطة نهاية.
- اضغط اشتراك واتبع الحوارات. يصبح المنتج المجاني نشطاً في الحال متى كانت لديك خطة منصة نشطة، وإلا فإن اشتراك ينقلك إلى صفحة الأسعار لتختار واحدة (الخطط). والمنتج المدفوع يطلب منك المراجعة والتأكيد ثم الدفع (المدفوعات). والمنتج الذي تتطلب خطته موافقة المزوّد يعرض تم طلب الموافقة إلى أن يقرر المزوّد.
الخطوة الخامسة: أضف المنتج إلى تطبيق الاختبار#
حين يصبح الاشتراك نشطاً تعرض علامة تبويب التسعير العبارة أنت مشترك في هذا المنتج.
- في اختر تطبيق اختر Default App (Testing) واضغط اضف. فإن لم يكن تطبيق الاختبار في القائمة فالمزوّد لم يفعّل Sandbox لهذا المنتج: اختر Default App (Prod) واستخدم عنوان الإنتاج في الخطوة السابعة.
- يظهر المنتج الآن في علامة تبويب المنتجات بذلك التطبيق.
الخطوة السادسة: انسخ المفتاح#
افتح تطبيقاتي ثم التطبيق ثم الصلاحيات. اضغط زر العين لتقرأ المفتاح أو زر النسخ لتنسخه.
الخطوة السابعة: أرسل أول طلب#
احتفظ بالمفتاح في متغيّر بيئة على خادمك، لا في الشيفرة. ثم حدّد عنوان المنتج: عنوان بوابة البيئة، ثم معرّف المنتج (slug)، ثم /v ورقم الإصدار الرئيسي لنقطة النهاية ومسارها. وهو في سطر واحد https://gate-test.api360.sa/<product-slug>/v<n>/<endpoint> لبيئة Sandbox. وتعرض صفحة المنتج هذا كله: رابط الطلب في بيئة التجربة، أو أمثلة الاستدعاء.
export API360_KEY="REPLACE_WITH_YOUR_KEY" export API360_BASE_URL="https://gate-test.api360.sa/<product-slug>" export API360_PATH="/v1/<endpoint>"
أرسل المفتاح في ترويسة api360key:
curl -sS -o /dev/null -w "%{http_code}\n" "$API360_BASE_URL$API360_PATH" \ -H "api360key: $API360_KEY"
تطبع الأمثلة رمز الحالة فقط. احذف -o /dev/null -w "%{http_code}\n" من أمر cURL لترى ردّ المنتج نفسه. وفي بيئة الإنتاج استخدم مفتاح تطبيق الإنتاج مع https://gate.api360.sa/<product-slug> (Sandbox وبيئة الإنتاج).
تحقق من النتيجة#
200وردّ المنتج: قبلت البوابة مفتاحك واشتراكك. ويحمل كل رد ترويسةX-Kong-Request-Id. احتفظ بها، فالدعم يحتاج إليها للعثور على استدعائك.403مع{"message": "No active subscription for this product"}: لم تطابق البوابة مفتاحك مع اشتراك. تحقق بهذا الترتيب من المضيف، واسم الترويسةapi360key، وأن المفتاح تابع لتطبيق تلك البيئة، وأن المنتج في علامة تبويب المنتجات بالتطبيق. ويعود الجواب نفسه للمفتاح المجهول.
# no valid key: the answer of a call the gateway cannot match to a subscription curl -sS -o /dev/null -w "%{http_code}\n" "$API360_BASE_URL$API360_PATH" -H "api360key: not-a-real-key"
- الطلب المرسَل بعد ثوانٍ من إضافتك المنتج، أو من إنشائك مفتاحاً، قد يُرفض: فالبوابة تعلم بالتغيير بعد وقت قصير من إجرائه. انتظر دقيقة وأرسله من جديد.