أدوات API

يأخذك هذا الدليل عبر إنشاء أداة API يقدر وكلاؤك الأذكياء استخدامها للتفاعل مع أنظمة خارجية.

ما هي أدوات API؟

تتيح أدوات API لوكيلك الذكي الاتصال بأنظمة خارجية وتنفيذ إجراءات نيابة عن العملاء:

• الاستعلامات: التحقق من حالة الطلب، عرض رصيد الحساب، إيجاد توفر المنتج
• الإجراءات: إنشاء طلبات، تحديث معلومات العميل، تشغيل سيناريوهات
• التكاملات: الاتصال بـ CRMs، ERPs، أنظمة الدفع، واجهات API للشحن

لما يسأل العميل شيئاً يتطلب بيانات خارجية، يستدعي وكيل الذكاء الاصطناعي تلقائياً أداة API المضبوطة، يحصل على الرد، ويستخدم تلك المعلومات للرد.

---

الوصول إلى أدوات API

1. اذهب إلى التكاملات في الشريط الجانبي
2. اضغط على واجهات API — تفتح صفحة My APIs
3. اضغط على Create New API لإنشاء أداة جديدة

---

أقسام النموذج

المعلومات الأساسية

الحقل	الوصف	المتطلبات
عنوان الأداة	اسم داخلي للأداة (يُعرَض للذكاء الاصطناعي)	3 إلى 55 حرفاً، يبدأ بحرف، أحرف وأرقام وشرطات سفلية فقط
الوصف	يشرح ما تفعله هذه الأداة — يستخدمه الذكاء الاصطناعي ليقرر متى يستدعيها	10 إلى 5000 حرف

أمثلة على عناوين أدوات جيدة:

• get_order_status
• create_support_ticket
• check_inventory

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

وصف جيد:

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

غامض جداً:

"احصل على معلومات الطلب"

---

ضبط الـ API

الحقل	الوصف	مثال
الرابط الأساسي	الرابط الجذر للواجهة (يجب أن يكون عاماً بـ HTTPS/HTTP)	https://api.yourcrm.com
الطريقة	طريقة HTTP: GET, POST, PUT, DELETE	GET للاسترداد، POST للإنشاء
قالب نقطة النهاية	مسار الـ API (يقدر يتضمن متغيرات)	/orders/{{order_id}}

مهم: يجب أن يكون الرابط الأساسي قابلاً للوصول من الإنترنت. عناوين IP الخاصة (192.168.x.x، 10.x.x.x)، localhost، و127.0.0.1 غير مسموح بها.

القائمة البيضاء للنطاقات

استدعاءات الوكيل لا تخرج إلا إلى النطاقات المعتمدة. إذا كان نطاق رابطك الأساسي غير معتمد في القائمة البيضاء بعد، يعرض النموذج تحذيراً مع زر طلب مراجعة — قدّم النطاق (مع سبب اختياري) وسيوافق عليه مشرف Orki أو يرفضه. تقدر تتابع طلباتك تحت الإعدادات ← القائمة البيضاء للنطاقات.

تقدر تحفظ الأداة وتضبطها والطلب ما زال معلّقاً، لكن الاستدعاءات الفعلية إلى النطاق ستفشل حتى يتم اعتماده.

---

المتغيرات — تماماً مثل Postman!

تعمل المتغيرات تماماً مثل متغيرات بيئة Postman. استخدم القوسَين المتعرّجَين المزدوجَين {{variable_name}} لإدراج قيم ديناميكية.

نوعان من المتغيرات

1. المكوّنات — متغيرات مخصصة مستخرَجة من المحادثة

الصيغة: {{component_name}}
أمثلة: {{order_id}}, {{product_sku}}, {{search_query}}

يستخرج وكيل الذكاء الاصطناعي هذه القيم من رسائل العميل. مثلاً، لما يقول العميل "وش حالة الطلب رقم 12345؟"، يستخرج الذكاء الاصطناعي 12345 كمكوّن order_id.

2. سمات المستخدم — مُعَبَّأة مسبقاً من ملف العميل

الصيغة: {{$attribute_name}}
المتاحة: {{$name}}, {{$email}}, {{$phone}}, {{$location}}, {{$language}}, {{$whatsapp_number}}, {{$whatsapp_name}}, {{$instagram_username}}

تُعَبَّأ هذه تلقائياً من بيانات ملف العميل.

أين تقدر تستخدم المتغيرات؟

المكان	مثال
نقطة النهاية	/users/{{user_id}}/orders
معاملات الاستعلام	email={{$email}}&status={{order_status}}
الترويسات	Authorization: Bearer {{api_token}}
متن الطلب (JSON)	{"customer_id": "{{customer_id}}", "email": "{{$email}}"}
متن الطلب (نموذج)	name={{$name}}&order={{order_id}}

---

معاملات الاستعلام

أضف معاملات استعلام URL كأزواج مفتاح-قيمة. تُلحَق هذه بالرابط كـ ?key=value&key2=value2.

المفتاح	القيمة	النتيجة
order_id	{{order_id}}	?order_id=12345
email	{{$email}}	?email=customer@example.com
limit	10	?limit=10 (قيمة ثابتة)

---

الترويسات

أضف ترويسات HTTP مخصصة. الاستخدامات الشائعة:

الترويسة	القيمة	الغرض
Authorization	Bearer {{api_token}}	مصادقة API
X-API-Key	{{api_key}}	طريقة مصادقة بديلة
X-Customer-ID	{{$email}}	تمرير سياق العميل

ملاحظة

يُضبَط Content-Type تلقائياً بناءً على اختيار نوع المتن — ما تقدر تضبطه يدوياً.

استخدم موفّر مصادقة لبيانات الاعتماد

بدل لصق مفاتيح API في الترويسات، أنشئ بيانات اعتماد قابلة لإعادة الاستخدام تحت التكاملات ← المصادقة وأرفقها في قسم المصادقة الخاص بالأداة. السر يُشفَّر، ويُحقن من جهة الخادم في كل استدعاء، والوكيل الذكي لا يراه أبداً. راجع المصادقة لأدوات API.

---

متن الطلب

لطرق POST/PUT، تقدر ترسل بيانات في متن الطلب.

أنواع المتن:

• JSON (application/json) — الأكثر شيوعاً للواجهات الحديثة
• Form URL Encoded (application/x-www-form-urlencoded) — تقديم نموذج تقليدي
• Multipart Form (multipart/form-data) — لرفع الملفات

مثال لمتن JSON:

{
  "customer_email": "{{$email}}",
  "customer_name": "{{$name}}",
  "order_id": "{{order_id}}",
  "quantity": {{quantity}},
  "notes": "{{special_instructions}}"
}

مهم لـ JSON

للقيم العددية والمنطقية، لا تضع علامات اقتباس حول المتغير:

• سلسلة: "name": "{{$name}}" (مع علامات اقتباس)
• رقم: "quantity": {{quantity}} (بدون علامات اقتباس)
• منطقية: "active": {{is_active}} (بدون علامات اقتباس)

---

مواصفات JOLT (اختيارية لكنها قوية)

ما هي JOLT؟

JOLT (لغة تحويل JSON إلى JSON) تحوّل استجابة الـ API إلى صيغة أبسط قبل أن يستلمها وكيل الذكاء الاصطناعي.

متى تستخدم JOLT:

• ترجع الـ API بيانات معقدة متداخلة تُربك الذكاء الاصطناعي
• تبي تستخرج حقولاً محددة فقط
• تحتاج إعادة تسمية الحقول لتكون أكثر وصفاً
• الاستجابة كبيرة جداً وتبي تقلّصها

ليش تستخدم JOLT؟

1. ردود ذكاء اصطناعي أنظف — يعمل الذكاء الاصطناعي بشكل أفضل مع بيانات بسيطة ومسطَّحة
2. تقليل استخدام التوكنز — استجابات أصغر = معالجة ذكاء اصطناعي أسرع وأرخص
3. إخفاء البيانات الحساسة — تمرير الحقول ذات الصلة فقط للذكاء الاصطناعي
4. توحيد الصيغ — جعل واجهات API المختلفة ترجع هياكل متسقة

مثال JOLT

ترجع الـ API:

{
  "data": {
    "order": {
      "id": "ORD-123",
      "customer": {
        "name": "John",
        "contact": { "email": "john@example.com" }
      },
      "status": "shipped",
      "items": [...]
    }
  }
}

مواصفات JOLT للتسطيح:

[
  {
    "operation": "shift",
    "spec": {
      "data": {
        "order": {
          "id": "order_id",
          "status": "order_status",
          "customer": {
            "name": "customer_name"
          }
        }
      }
    }
  }
]

النتيجة المحوَّلة:

{
  "order_id": "ORD-123",
  "order_status": "shipped",
  "customer_name": "John"
}

عمليات JOLT الشائعة:

• shift — نقل/إعادة تسمية الحقول (الأكثر شيوعاً)
• default — إضافة قيم افتراضية للحقول المفقودة
• remove — حذف الحقول غير المرغوبة

بناء JOLT عبر درج الاختبار

لا تحتاج لكتابة JOLT دون رؤية النتيجة. يحتوي نموذج الأداة على درج اختبار (Test) مدمج ينفّذ الطلب الحقيقي على واجهة API عندك ويعرض الاستجابة الفعلية. يتضمن ساحة تجربة JOLT حيث يمكنك تجربة المواصفات على تلك الاستجابة الحية وتطبيقها على الأداة مباشرة عندما يصبح الناتج صحيحاً.

يمكنك أيضاً فتح AI View (معاينة "What does the AI see?" على بطاقة الأداة) في أي وقت لترى بالضبط المخطط والوصف اللذين يستلمهما وكيل الذكاء الاصطناعي لأداتك.

إعادة التسمية للوضوح

JOLT مفيدة بشكل خاص لإعادة تسمية أسماء حقول غامضة إلى شيء يفهمه الذكاء الاصطناعي بشكل أفضل:

الحقل الأصلي	تم إعادة التسمية إلى	السبب
ord_sts	order_status	معنى أوضح
cust_nm	customer_name	الذكاء الاصطناعي يفهم "name"
dlvry_dt	delivery_date	إزالة الاختصارات

---

قسم المتغيرات المشار إليها

يُعَبَّأ هذا القسم تلقائياً بناءً على المتغيرات المستخدمة في ضبطك.

مربع الاختيار "مطلوب":

• مفعّل — إذا كانت هذه القيمة مفقودة، راح يسأل الذكاء الاصطناعي العميل لتوفيرها قبل استدعاء الـ API
• معطّل — المتغير اختياري؛ يُستَدعَى الـ API حتى لو كانت القيمة مفقودة

ترميز الألوان:

• شريحة زرقاء — مكوّن صحيح (موجود في قائمة مكوّناتك)
• شريحة بنفسجية — سمة مستخدم صحيحة
• شريحة حمراء — مرجع غير صحيح (المكوّن غير موجود أو خطأ في اسم السمة)

---

الأمان

يتيح لك هذا القسم حماية الأدوات الحساسة بطلب تحقق العملاء من رقم هاتفهم قبل استخدام الأداة.

الحقل	الوصف	الافتراضي
يتطلب رقم هاتف متحقَّق	عند التفعيل، يجب على العملاء إكمال تحقق OTP قبل تنفيذ هذه الأداة	معطّل
مدة صلاحية التحقق (أيام)	كم تبقى عملية التحقق الناجحة صالحة قبل أن يحتاج العميل للتحقق مرة أخرى	14 يوماً

متى تفعّل التحقق من الهاتف:

• الأدوات اللي تنفّذ إجراءات حساسة (مثل تقديم الطلبات، إجراء المدفوعات)
• الأدوات اللي تصل إلى معلومات حساب شخصية
• الأدوات اللي تعدّل بيانات العميل عبر أنظمة خارجية

كيف يعمل:

1. يبدأ العميل محادثة تحتاج هذه الأداة
2. يرسل وكيل الذكاء الاصطناعي تلقائياً رمز OTP إلى رقم هاتف العميل
3. يردّ العميل بالرمز
4. يتحقق الوكيل من الرمز ويتابع لاستدعاء الأداة
5. الاستخدامات اللاحقة خلال مدة الصلاحية تتخطى التحقق

ملاحظة

تُعاد مدة الصلاحية (1 إلى 365 يوماً) من كل تحقق ناجح. راجع التحقق من الهاتف (OTP) للتفاصيل عن كيفية عمل تدفق التحقق.

---

إنشاء المكوّنات

قبل استخدام متغيرات {{component_name}}, تحتاج تنشئ المكوّن. تحدد المكوّنات نوع البيانات اللي يجب أن يستخرجها الذكاء الاصطناعي من المحادثات.

أنواع المكوّنات

النوع	الوصف	مثال للاستخدام
سلسلة	قيم نصية	order_id, product_name, search_query
رقم	قيم عددية	quantity, price, age
منطقية	صح/خطأ	is_urgent, wants_notification
Enum	خيارات محددة مسبقاً	order_status (pending/shipped/delivered)
كائن	بيانات متداخلة معقدة	shipping_address مع street, city, zip
مصفوفة	قائمة من القيم	product_ids, selected_options

إنشاء مكوّن

1. اضغط على شريحة مكوّن في قسم المتغيرات المشار إليها
2. أو اذهب إلى قسم المكوّنات واضغط على "إضافة مكوّن"
3. عبّئ:
   • الاسم — معرّف بصيغة snake_case (مثل order_id)
   • الوصف — اشرح ماذا تمثّل هذه البيانات (يساعد الذكاء الاصطناعي على الاستخراج بشكل صحيح)
   • النوع — اختر النوع المناسب
   • قيمة مثال — بيانات نموذجية للتوثيق

---

مثال كامل: أداة استعلام عن الطلب

السيناريو: أنشئ أداة تستعلم عن حالة الطلب من واجهة برمجة متجر التجارة الإلكترونية.

المعلومات الأساسية

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

ضبط الـ API

• الرابط الأساسي: https://api.mystore.com
• الطريقة: GET
• نقطة النهاية: /v1/orders/{{order_id}}

الترويسات

الترويسة	القيمة
Authorization	Bearer sk_live_xxxxxxxxxxxxx
X-Customer-Email	{{$email}}

معاملات الاستعلام

المفتاح	القيمة
include	shipping,items

مواصفات JOLT

[
  {
    "operation": "shift",
    "spec": {
      "order_number": "order_number",
      "status": "status",
      "created_at": "order_date",
      "shipping": {
        "carrier": "shipping_carrier",
        "tracking_number": "tracking_number",
        "estimated_delivery": "delivery_date"
      },
      "total": "total_amount"
    }
  }
]

المتغيرات المشار إليها

• order_id — مطلوب (مفعّل) — راح يسأل الذكاء الاصطناعي العميل عن رقم الطلب إذا ما قُدِّم
• $email — اختياري — يُستخدم للتحقق

---

تعيين الأدوات للوكلاء

الأداة لا تفعل شيئاً حتى تعيّنها

إنشاء الأداة يحفظها في مساحة العمل فقط — ولا يقدر أي وكيل يراها أو يستدعيها بعد. إذا "تجاهل" الوكيل أداتك الجديدة، فأول شيء تتحقق منه هو التعيين أدناه.

بعد إنشاء أداة، تحتاج تعيّنها لوكيل:

1. اذهب إلى الوكلاء
2. اضغط على الوكيل اللي تبي تضبطه
3. اذهب إلى تبويب الأدوات
4. ابحث عن أداتك في قسم المتاحة
5. اقلب المفتاح إلى مفعّل لتعيينها

سوف تنتقل أداتك الجديدة إلى قسم المعيَّنة ويقدر الوكيل يبدأ باستخدامها فوراً.

أدوات مسارات العمل فقط لا تحتاج تعييناً

إذا كانت الأداة مخصصة للتشغيل داخل مسار عمل فقط، فلا تعيّنها للوكيل — عيّن مسار العمل فقط. خطوات مسار العمل تنفّذ أدواتها من جهة الخادم بغض النظر عن تعيين الوكيل، وإبقاء الأداة الخام غير معيَّنة يمنع الوكيل من استدعائها مباشرة خارج المسار.

راجع أدوات الوكيل لمزيد من التفاصيل.

---

نصائح لاستخدام أفضل للأدوات

اكتب الأوصاف بالنتائج المتوقعة

ضمّن ما ترجعه الأداة في وصفك. هذا يساعد الذكاء الاصطناعي على فهم متى يستخدمها:

وصف جيد:

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

أقل فائدة:

"يحصل على معلومات الطلب."

الذكاء الاصطناعي الآن يعرف أن هذه الأداة ترجع أرقام تتبع، فراح يستخدمها لما يسأل العملاء "وين رقم التتبع؟"

إدارة الأدوات الكثيرة

إذا عندك أدوات كثيرة، قد يلتبس على الذكاء الاصطناعي أيها يستخدم. ساعده بتحديث شخصية الوكيل عندك بتعليمات مخصصة تشرح متى يستخدم كل أداة:

مثال للتعليمات المخصصة:

إرشادات استخدام الأدوات:
- استخدم `get_order_status` لما يسأل العميل عن حالة الطلب، التتبع، أو التوصيل
- استخدم `check_inventory` لما يسأل العميل إذا كان المنتج متوفراً
- استخدم `create_support_ticket` فقط لما لا يمكن حل المشكلة وتحتاج متابعة بشرية
- جرّب دائماً `get_order_status` قبل `create_support_ticket` للمشاكل المتعلقة بالطلبات

هذا الإرشاد في التعليمات المخصصة يساعد الذكاء الاصطناعي على اتخاذ قرارات أفضل بشأن أي أداة يستدعي.

---

المشكلة	الحل
خطأ "مكوّن غير صحيح" (شريحة حمراء)	أنشئ المكوّن أولاً، أو افحص الأخطاء في الاسم
"يجب أن يكون الرابط الأساسي نطاقاً عاماً"	استخدم رابط API الإنتاج عندك، وليس localhost أو IPs داخلية
"JSON غير صحيح" في متن الطلب	افحص الفواصل المفقودة، المفاتيح غير المقتبَسة، أو الفواصل النهائية
ترجع الـ API لكن الذكاء الاصطناعي يعطي إجابة خاطئة	أضف مواصفات JOLT لتبسيط/تسطيح الاستجابة
"لا يمكن ضبط Content-Type"	أزِل Content-Type من الترويسات؛ يُضبَط تلقائياً بناءً على نوع المتن

---

حدود الأدوات

عدد الأدوات اللي تقدر تنشئها يعتمد على باقتك. تحقق من حدودك في الإعدادات > الفوترة.

---

الخطوات التالية

• أدوات الوكيل - تعيين الأدوات لوكلائك
• نظرة عامة على الوكلاء الأذكياء - ضبط سلوك الوكيل