المصادقة

يجب أن يحمل كل طلب إلى Gurdx مفتاح واجهة، يُرسل إما كمعامل في الرابط أو كرمز Bearer في الترويسة.

طريقتان لإرسال المفتاح#

معامل في الرابط#

curl "https://gurdx.cretip.com/api/lookup/ip?ip=1.1.1.1&key=YOUR_API_KEY"

ترويسة Authorization#

curl "https://gurdx.cretip.com/api/lookup/ip?ip=1.1.1.1" \
  -H "Authorization: Bearer YOUR_API_KEY"

إذا وُجدت الطريقتان معاً فسيُستخدم رمز Bearer. يُفضَّل استخدام الترويسة في الاتصال بين الخوادم، لأن الروابط كثيراً ما تظهر في سجلات الوسطاء وتاريخ المتصفح.

صيغة المفتاح#

تبدأ المفاتيح ببادئة تدل على نوعها:

التفاصيل في مفاتيح الواجهة وبيئة التطوير.

ما الذي تفحصه البوابة#

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

1. صحة الخيارات (format وcallback وlang وmode وuserID): الأخطاء 107 إلى 111 و123.
2. وجود المفتاح: الخطأ 101 invalid_key.
3. أن الحساب فعّال: الخطأ 102 inactive_user.
4. صلاحية الاشتراك: الخطأ 105 plan_expired أو 127 subscription_required.
5. أن الطلب من مضيف مصرّح له: الخطأ 113 domain_not_whitelisted.
6. أن خطتك تشمل الدالة والوحدة المطلوبة: الخطآن 117 و114.
7. عدم تجاوز حد الإغراق: الخطأ 106.
8. عدم تجاوز الحصة: الخطأ 103.

المضيفون المصرّح لهم#

إذا حدّدت مضيفين مصرّحاً لهم لحسابك فلن يُقبل الطلب إلا إذا كان مضيف الترويسة Origin أو Referer، أو عنوان IP للمتصل، ضمن القائمة. القائمة الفارغة تعني عدم وجود قيد. وبما أن طلبات الخوادم لا تحمل عادة ترويسة Origin، أضف عنوان IP للخادم إلى القائمة. راجع مفاتيح الواجهة.

مثال على مفتاح غير صالح#

{
  "status": "error",
  "code": 101,
  "type": "invalid_key",
  "description": "The API Key is missing or invalid."
}

لاحظ أن الرد يصل برمز HTTP 200.

Warning: لا تضع مفتاحاً فعلياً في شيفرة المتصفح أو تطبيقات الجوال أو المستودعات العامة. استدعِ Gurdx من الخادم الخلفي.

CORS والطلبات التمهيدية#

تحمل الاستجابات الترويسة Access-Control-Allow-Origin: * وتُجاب طلبات OPTIONS برمز 204، فيستطيع المتصفح الوصول إلى الواجهة. هذا مخصص للمفاتيح التجريبية أو للواجهات الأمامية التي تمرّ عبر خادمك، وليس مبرراً لكشف مفتاح فعلي.