كتلة API - استدعاء واجهات برمجة التطبيقات الخارجية من تدفق روبوت المحادثة

نظرة عامة

تتيح كتلة API لروبوت المحادثة الخاص بك استدعاء أي واجهة برمجة تطبيقات REST خارجية في منتصف المحادثة، والتقاط الاستجابة، وتوجيه التدفق بناءً على النجاح أو الفشل. استخدمها للبحث عن الطلبات في قاعدة بياناتك، أو التحقق من كلمات المرور لمرة واحدة، أو جلب حالة الشحن، أو التحقق من أرصدة الحسابات، أو دمج أي نظام يعرض نقطة نهاية HTTP.

عندما يصل الروبوت إلى كتلة API، يرسل طلب HTTP المهيّأ، وينتظر الاستجابة، ويستخرج الحقول من محتوى JSON أو XML إلى متغيرات، ثم يتبع فرع النجاح (HTTP 2xx/3xx) أو فرع الفشل (HTTP 4xx/5xx). يمكن للكتل التالية في التدفق استخدام المتغيرات المستخرجة في الرسائل أو الشروط أو استدعاءات API اللاحقة.

أين تجدها

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

تحتوي كتلة API على اتصالي إخراج: النجاح (الأعلى/الافتراضي) لاستجابات 2xx و3xx، والفشل (الثانوي) لاستجابات 4xx و5xx.

التهيئة

الخطوة 1: ضبط رابط الطلب والطريقة

الحقل	الوصف
الرابط	نقطة النهاية الكاملة، على سبيل المثال https://api.example.com/orders/{order_id}
الطريقة	فعل HTTP: GET أو POST أو PUT أو PATCH أو DELETE

يمكنك إدراج أي متغير ملتقط سابقاً في التدفق باستخدام صيغة {variable_name} (قوسان معقوفان مفردان). تُحلّ المتغيرات أثناء التشغيل قبل إرسال الطلب.

الخطوة 2: إضافة معلمات الاستعلام (اختياري)

لطلبات GET، استخدم معلمات الاستعلام لإلحاق أزواج مفتاح-قيمة بالرابط. يأخذ كل صف مفتاحاً وقيمة. يعمل استبدال المتغيرات في كلا الحقلين.

Key: customer_email       Value: {email}
Key: include_archived     Value: false

الخطوة 3: تهيئة الترويسات

أضف ترويسات HTTP مخصصة ضمن قسم الترويسات. يأخذ كل صف مفتاحاً وقيمة.

Key: Content-Type         Value: application/json
Key: Accept               Value: application/json
Key: X-Custom-Header      Value: {tenant_id}

يُكتشف Content-Type تلقائياً عند اختيارك تنسيق محتوى، لكن يمكنك تجاوزه.

الخطوة 4: إضافة المصادقة

تدعم كتلة API ثلاثة أوضاع مصادقة. اختر وضعاً يتناسب مع واجهة برمجة التطبيقات المستهدفة.

نوع المصادقة	الحقول	كيفية إرسالها
المصادقة الأساسية	اسم المستخدم، كلمة المرور	تُرسل كـ Authorization: Basic <base64>
رمز Bearer	رمز Bearer	يُرسل كـ Authorization: Bearer <token>
ترويسة مخصصة	اسم الترويسة، قيمة الترويسة	تُرسل كـ <Name>: <Value> (لمفاتيح API والأنظمة المخصصة)

ملاحظة: بالنسبة لواجهات برمجة التطبيقات التي تستخدم x-api-key أو ما شابه، اختر ترويسة مخصصة واضبط الاسم على x-api-key والقيمة على مفتاحك. يمكنك أيضاً تخزين المفتاح في متغير والإشارة إليه بـ {api_key}.

الخطوة 5: بناء محتوى الطلب

لطلبات POST وPUT وPATCH، هيّئ المحتوى في قسم المحتوى. اختر التنسيق:

التنسيق	استخدمه عندما
JSON	معظم واجهات REST الحديثة
XML	نقاط نهاية SOAP أو XML القديمة
بلا	لا حاجة لمحتوى (نموذجي لـ GET وDELETE)

اكتب JSON أو XML الخام في محرر المحتوى. يمكن إدراج المتغيرات بشكل مضمّن:

{
  "order_id": "{order_id}",
  "customer": {
    "name": "{name}",
    "email": "{email}"
  },
  "total": {amount}
}

الخطوة 6: ربط الاستجابة بالمتغيرات

ضمن حفظ الاستجابة في المتغيرات، حدّد كيفية استخراج الحقول من استجابة JSON إلى متغيرات التدفق.

مسار JSON	اسم المتغير
result.user.name	user_name
data.orders[0].status	order_status
items[*].id	item_ids

صيغة المسار المدعومة:

• العلامة النقطية للكائنات المتداخلة: result.user.email
• فهرس المصفوفة: items[0].name
• استخراج المصفوفة بأحرف البدل: items[*].id يعيد جميع المعرّفات كمصفوفة
• الحقل الجذري: status أو message

تتوفر القيم المستخرجة في جميع الكتل اللاحقة كـ {variable_name}.

الخطوة 7: الإرسال والحفظ

انقر على إرسال في نافذة الكتلة، ثم احفظ التدفق باستخدام حفظ التغييرات في الشريط العلوي.

كيفية التعامل مع الاستجابة

مسار النجاح (HTTP 2xx / 3xx)

1. تُملأ المتغيرات من حفظ الاستجابة في المتغيرات
2. يتبع التدفق اتصال إخراج النجاح

مسار الفشل (HTTP 4xx / 5xx)

1. قد تُملأ متغيرات الاستجابة أو لا تُملأ اعتماداً على محتوى الخطأ
2. يتبع التدفق اتصال إخراج الفشل
3. استخدم هذا الفرع لإرسال رسالة خطأ ودية أو إعادة المحاولة

المهلة

تنتهي مهلة الطلبات بعد 30 ثانية. إذا كانت واجهة برمجة التطبيقات الخاصة بك بطيئة، فكّر في تقسيم العمل إلى خطوتين أو استخدام نمط غير متزامن مدفوع بالويب هوك.

الاختبار في API Playground

يُسجَّل كل استدعاء لكتلة API ويتوفر في API Playground داخل Studio. لكل تشغيل اختبار يمكنك رؤية:

• الرابط والطريقة والترويسات المحلولة بالكامل
• محتوى الطلب الذي أُرسل
• رمز حالة HTTP المستلم
• محتوى الاستجابة الكامل
• المتغيرات التي استُخرجت

استخدم Playground لتصحيح متغيرات القالب والمصادقة وعمليات ربط مسار JSON قبل شحن التدفق.

أفضل الممارسات

• خزّن الأسرار في المتغيرات، وليس في تهيئة الكتلة. التقط مفاتيح API من الإعدادات الخاصة بكل بيئة ومرّرها عبر المتغيرات بحيث يعمل التدفق نفسه في بيئة الاختبار والإنتاج
• هيّئ فرع الفشل دائماً. لا تفترض أبداً نجاح استدعاء API. أرسل رسالة احتياطية مثل "تعذّر علينا استرجاع طلبك الآن. يرجى المحاولة لاحقاً."
• أبقِ محتوى الطلب صغيراً. لا ترسل سجلات محادثات كاملة أو حمولات كبيرة إلا إذا كانت واجهة برمجة التطبيقات تحتاجها
• تحقق من حقول الاستجابة قبل استخدامها. إذا كان order_status قد يكون مفقوداً، أضف كتلة شرط بعد استدعاء API للتحقق من {order_status} قبل استخدامه في رسالة
• استخدم أسماء متغيرات وصفية. user_email أفضل من val1 لأنه أسهل في التصحيح في Playground وسجل المحادثة
• اضبط Content-Type صراحةً عند إرسال JSON، حتى تقبل واجهات برمجة التطبيقات الصارمة الطلب

حالات الاستخدام الشائعة

البحث عن طلب

يقدّم العميل معرّف طلب، ويجلب الروبوت الحالة من الواجهة الخلفية للتجارة الإلكترونية الخاصة بك.

• الطريقة: GET
• الرابط: https://api.myshop.com/orders/{order_id}
• المصادقة: رمز Bearer
• ربط الاستجابة: data.status إلى order_status، وdata.tracking_url إلى tracking_url

التحقق من كلمة المرور لمرة واحدة

يجمع الروبوت رمزاً مكوّناً من 6 أرقام، ويستدعي نقطة نهاية التحقق الخاصة بك، ويتفرّع بناءً على النتيجة.

• الطريقة: POST
• الرابط: https://api.myapp.com/verify-otp/
• المحتوى: {"phone": "{phone}", "code": "{otp_code}"}
• ربط الاستجابة: verified إلى otp_verified
• استخدم كتلة شرط تالياً: إذا كان {otp_verified} == true تابع، وإلا اسأل مرة أخرى

مزامنة جهات اتصال CRM

ادفع تفاصيل جهة الاتصال المجمّعة إلى نظام إدارة علاقات العملاء الخاص بك عند إكمال المستخدم للتأهيل.

• الطريقة: POST
• الرابط: https://api.crm.com/v1/contacts/
• المصادقة: ترويسة مخصصة (x-api-key: {crm_key})
• المحتوى: {"name": "{name}", "email": "{email}", "source": "chatbot"}

استكشاف الأخطاء وإصلاحها

يفشل الطلب بـ 401 غير مصرّح

1. تحقق من أن نوع المصادقة يطابق ما تتوقعه واجهة برمجة التطبيقات
2. لرموز Bearer، لا تضمّن كلمة Bearer في حقل الرمز. تضيفها الكتلة تلقائياً
3. لمصادقة الترويسة المخصصة، تحقق من أن اسم الترويسة يطابق وثائق واجهة برمجة التطبيقات تماماً (حساس لحالة الأحرف لبعض واجهات برمجة التطبيقات)
4. افحص الطلب في API Playground للتأكد من إرسال الترويسة

المتغيرات لا تُملأ من الاستجابة

1. افتح API Playground وافحص محتوى الاستجابة الفعلي
2. تأكد من أن مسار JSON يطابق بنية الاستجابة. المسارات حساسة لحالة الأحرف
3. للمصفوفات، استخدم items[0].field لقيمة واحدة أو items[*].field لجميع القيم
4. إذا كانت الاستجابة XML، تأكد من ضبط تنسيق المحتوى بشكل صحيح. تعمل مسارات JSON على XML المُحلَّل أيضاً

يتبع التدفق فرع الفشل حتى عندما تعمل واجهة برمجة التطبيقات

1. تحقق من رمز حالة HTTP في API Playground. تعيد بعض واجهات برمجة التطبيقات 201 (تم الإنشاء) عند POST وهو لا يزال نجاحاً
2. إذا أعادت واجهة برمجة التطبيقات 200 لكن مع خطأ في المحتوى، استخدم كتلة شرط بعد فرع النجاح لفحص حقل الاستجابة

انتهت مهلة الطلب

1. المهلة ثابتة عند 30 ثانية. إذا كانت واجهة برمجة التطبيقات الخاصة بك تستغرق وقتاً أطول بانتظام، فقد لا تكون مناسبة للدردشة الفورية
2. فكّر في نقل العمل البطيء إلى مهمة في الخلفية واستطلاع النتيجة، أو استخدم ويب هوك ليتم إعلامك عند الجاهزية

تظهر متغيرات القالب كـ {variable} خام في الطلب

1. تأكد من ضبط المتغير بواسطة كتلة سابقة في التدفق
2. تحقق من تهجئة اسم المتغير (حساس لحالة الأحرف)
3. استخدم سجل المحادثة لفحص المتغيرات المُملأة فعلياً عند تلك النقطة

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

• كتلة الويب هوك - استقبال استدعاءات HTTP واردة لتشغيل تدفق أو استئنافه
• كتلة إنهاء المحادثة - إنهاء المحادثات بزر إعادة التشغيل
• نظرة عامة على Studio - استكشف جميع أنواع الكتل وميزات مُنشئ التدفق