نظرة عامة والبدء السريع

اختر REST أو MCP

تستخدم كلتا الواجهتين محرك الحساب نفسه ونموذج الصلاحيات نفسه. استخدم REST مع مفتاح API للتطبيقات والبرامج النصية حيث تتحكم في كل طلب. استخدم MCP عندما ينبغي لمساعد أو وكيل ذكاء اصطناعي اكتشاف الأدوات المتاحة وفهم مخططاتها واختيار الحساب الصحيح بنفسه.

المصادقة

تصل طريقتا تسجيل الدخول إلى محرك الحساب نفسه. تتصل عملاء الذكاء الاصطناعي التفاعلية بخادم MCP وتفوّض الوصول في المتصفح باستخدام OAuth. أما التطبيقات والخدمات والبرامج النصية وعمليات التكامل اليدوية فتستخدم مفتاح Road User Tools API يُرسل كرمز Bearer. إنشاء المفاتيح مجاني ويمكن تدويرها أو إبطالها في أي وقت.

Authorization: Bearer rut_live_...

بداية سريعة REST

أرسل طلب JSON إلى أي نقطة نهاية REST تم إصدارها باستخدام مفتاح API. تستخدم الردود متسقةok, data, وerrorهيكل عبر جميع أدوات الحساب.

curl -X POST https://roaduser.tools/api/v1/journey-time \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "distance": { "value": 250, "unit": "km" },
    "speed": { "value": 100, "unit": "kmh" }
  }'

بداية سريعة MCP

أضف عنوان URL للخادم إلى عميل ذكاء اصطناعي متوافق ووافق على الوصول في متصفحك عندما تُفتح صفحة التفويض الخاصة بـ Road User Tools. يكتشف العميل إعداد تسجيل الدخول والأدوات المتاحة تلقائياً، دون مفاتيح أو رموز للنسخ.

https://roaduser.tools/mcp

بديل: تكوين يدوي بمفتاح API

يمكن للعملاء الذين لا يدعمون التفويض عبر المتصفح، ولعمليات التكامل البرمجية، إرسال مفتاح API بدلاً من ذلك:

{
  "mcpServers": {
    "roaduser-tools": {
      "url": "https://roaduser.tools/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

تنسيق الاستجابة REST

تقوم استجابات REST الناجحة بإرجاع النتيجة المحسوبةdata. يؤدي فشل التحقق من الصحة والطلب إلى إرجاع رمز خطأ مستقر يمكن قراءته بواسطة الآلة إلى جانب رسالة يمكن قراءتها بواسطة الإنسان.

{
  "ok": true,
  "data": {
    "totalHours": 2.5,
    "formatted": "2:30:00"
  }
}

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid journey time input."
  }
}