# التكامل مع واجهات API التابعة لجهات خارجية

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

## كيفية التعامل مع واجهة برمجة تطبيقات جهة خارجية على مثال DaData

لنأخذ نصائح API من [https://dadata.ru/api/suggest/address ](https://dadata.ru/api/suggest/address)كمثال

{% hint style="info" %}
اقرأ بعناية وثائق واجهات برمجة التطبيقات التابعة لجهات خارجية
{% endhint %}

افتح مشروعك في Salebot وافتح الإعدادات المتقدمة في إعدادات الكتلة؛ هناك تحتاج إلى تغيير نوع الطلب إلى POST-json.

في الحقل “**طلب URL**” أدخل عنوان URL التالي: h<ttps://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address>

في الحقل “**رأس الطلب**” اكتب الرأس بصيغة JSON:

{ "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token }

في حقل “**معاملات JSON**” ضع في الطلب نفسه - { "query": "#{CurrencyType}" }

للحصول على النتائج ستحتاج أيضًا إلى تعبئة تبويب “**القيم المخزنة**”.

يوجد مثال على الطلب أدناه:

![](https://lh3.googleusercontent.com/QV4ldVY9n1AFFCr2jn1NQU_hZe7Iug-Xh5d4KLWtAZNQEyQ9WPLu1mV7mPcFjfjAKaPGO2Wi148J4AAF3kmU0wmhLYwBy6LgDXbFRgteh0Nrtu29LhqSgTg6d14Ts8pvanwWUJQAVTUThYp6Lg)

### كيفية حفظ القيم من المتغيرات

ليس الجميع يفهمه فورًا، حتى تحاول القيام به بنفسك.

ابدأ بكتابة #{custom\_answer} في حقل الإجابة. (المتغير #{custom\_answer} يحتوي على الإجابة التي تم الحصول عليها من الخادم والمذكورة في حقل “URL لإجابة من الخادم”)

شغّل الكتلة التي تحتوي على الطلب لإرساله وللحصول على إجابة له. تحتاج إلى تحليل الرد وإعداد الوصول إلى المتغيرات فيه. لهذا، تحتاج إلى العمل مع تبويب “القيم المخزنة”.

لننظر في مثال لفهم العملية بشكل أفضل.

نتيجة لطلبنا #{custom\_answer} جاءت إجابة بالشكل التالي:

`{"suggestions": [{"value": "الجنيه الإسترليني", "unrestricted_value": "الجنيه الإسترليني", "data": {"code": "826", "strcode": "GBP", "name": "الجنيه الإسترليني", "country": "المملكة المتحدة"}}]}`

الآن لنكتب في حقل “القيم المخزنة” الصيغة VALUE->VARIABLE الخاصة بنا

`suggestions|0|value->CurrencyType;` \
`suggestions|0|data|code->CurrencyDigCode;` \
`suggestions|0|data|strcode->CurrencyStrCode;` \
`suggestions|0|data|country->CurrencyCountry`

**suggestions** - مفتاح المصفوفة \[{"value": "الجنيه الإسترليني", "unrestricted\_value": "الجنيه الإسترليني", "data": {"code": "826", "strcode": "GBP", "name": "الجنيه الإسترليني", "country": "المملكة المتحدة"}}]

**suggestions|0** - مفتاح أول عنصر في المصفوفة {"value": "الجنيه الإسترليني", "unrestricted\_value": "الجنيه الإسترليني", "data": {"code": "826", "strcode": "GBP", "name": "الجنيه الإسترليني", "country": "المملكة المتحدة"}}

**suggestions|0|value** - المفتاح إلى القيمة “الجنيه الإسترليني”

أطول مفتاح في هذا JSON:

**suggestions|0|data|strcode** - المفتاح إلى القيمة “GBP”

{% hint style="success" %}
تُفصل المفاتيح بواسطة الخط العمودي (|). إذا كانت هناك مصفوفة في JSON، فإن الوصول إلى عنصرها يكون مرقّمًا، بدءًا من الرقم 0، ويُكتب أيضًا بواسطة الخط العمودي.
{% endhint %}

{% hint style="info" %}
من الضروري تكرار كامل التداخل. وللراحة يمكنك تصور JSON في تطبيق JSON-viewer.
{% endhint %}

تُفصل مستويات التداخل بواسطة الخطوط العمودية. لذا تحتاج إلى سرد جميع المفاتيح مفصولة بالخط للوصول إلى القيمة.

{% hint style="info" %}
إذا كانت هناك مصفوفة في JSON، فبدلًا من المفتاح تحتاج إلى ذكر رقم العنصر ابتداءً من 0.
{% endhint %}

افصل العبارات الخاصة بالحصول على المتغيرات برمز الفاصلة المنقوطة (;). تتكون العبارات من الرابط إلى البيانات في الإجابة واسم المتغير الذي سيتم حفظها فيه، وهما مفصولان بالرمزين -> (الشرطة + علامة الزاوية).

استعلام البحث هو، بطريقة ما، مسار داخل JSON إلى القيمة المطلوبة.

### تطوير API للروبوتات

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

#### لكن الآن قليل من النظرية.

يدعم الروبوت **GET** و **POST** طلبات، وهذه هي الأنواع الرئيسية المستخدمة في معظم واجهات API العامة.

**GET** هو طلب يحدث عند النقر على الرابط أو عند فتح الرابط في المتصفح. تُنقل المعلمات في مثل هذا الطلب إلى طلبات URL.

صياغة المعلمات المنقولة: بعد الرابط يوجد علامة استفهام (?) ثم يُفصل كل معلم بعلامة العطف (&). يتكون المعلم من الاسم وقيمته بعد علامة يساوي (=). مثال على URL يحتوي على معلم:

![](https://lh6.googleusercontent.com/c4xJMMuFKVsFJW_3nDTzUmhvejIUtIKsg-kEA8_PT05vlmmAfDgritAtxwh_5sq3-YwOuy8dw4LVYbesWa4Yy-QjUx3gIbF-54_omadX1SFFaa8K6HirvD-qycd4D6tjSBpkRLAB)

هنا يمكنك أن ترى أنه يتم تمرير معلم واحد باسم “search\_query” وأن قيمته هي “queen live aid”. علامة ‘+’ هنا تمثل المسافة بين الكلمات؛ وعند العمل باستخدام برنامج التحرير يمكنك ببساطة ترك المسافات - وسيقوم الروبوت بتغييرها بنفسه.

**POST** هو نوع من الطلبات يُرسل غالبًا عند ملء نموذج على موقع إلكتروني. ينقل الطلب المعلمات في الجسم؛ وبالطبع يمكن تمريرها بالطريقة نفسها مثل GET، لكن هذا نادرًا ما يُفعل. يمكن أن تكون المعلمة في الجسم بصيغة JSON أو كزوج مفتاح-قيمة. كقيم مفتاح-قيمة، تكون المعلمات على شكل حقول، أما صيغة JSON فهي الأكثر استخدامًا لواجهة API.

**رأس الطلب.** يمكن لكل طلب أن يحتوي على رأس/عنوان مضاف. يُكتب فيه غالبًا تنسيق البيانات المنقولة ومفاتيح الوصول. عادةً نترك هذا التبويب فارغًا، لكنه مطلوب لإدخال API Token أو نوع الطلب “Content-type”: “application/json” في بعض الحالات النادرة.

**JSON** - (JavaScript Object Notation) هو تنسيق ملف قياسي مفتوح وتنسيق لتبادل البيانات يستخدم نصًا مقروءًا للبشر لتخزين ونقل كائنات البيانات المكوّنة من أزواج سمة–قيمة ومصفوفات. للعمل مع API في الروبوتات يجب أن تعرف هذا التنسيق، فكل شيء يعتمد عليه.

قبل المتابعة، اقرأ المقالات التالية:

[https://www.json.org/json-en.html ](<https://www.json.org/json-en.html >)\
<https://developer.mozilla.org/en-US/docs/learn/javascript/objects/json>

وحاول أيضًا إنشاء ملف JSON خاص بك على هذا الموقع:

<https://jsoneditoronline.org>

#### تدريب

يمكن للكتل والشروط التعامل مع الطلبات. تُنشأ طلبات الشروط لفهم ما إذا كان الحوار يمكن أن يتبع مسارًا معينًا أم لا. في هذه الحالة يحدث الطلب في كل مرة يتم فيها التحقق من شرط المسار. أما طلبات الكتل، فعلى العكس، فلا تُنفّذ إلا عند الانتقال إلى الكتلة.

قبل إنشاء طلب، تحتاج إلى اختيار نوعه:

![](https://lh5.googleusercontent.com/jDLVxBLwNSrmSb9t6LTuwuuifA3X-U9PNhLi7YvCrLj36uyDjiP-FymTpUXg1fhSewb63UslJbHhndLsefusieLdYSe4oNWMBGWuceHWWNg5VrRddIHXbGVwqhDMFFUR5Xk4YZLYXfM2hcNP9w)

يتم التمييز بين POST-data وPOST-json من خلال طريقة نقل المعلمات كما ذُكر أعلاه (صيغة JSON أو كزوج مفتاح-قيمة). إذا اخترت JSON، فيمكن نقل المعلمات في الطلب فقط. ويُفتح حقل إضافي لـ post: JSON POST-parameters. **مهم!** يجب كتابة المعلمات بصيغة JSON فقط، فالبوت يعمل بهذه الطريقة فقط.

يمكن تحليل الرد من الخادم وحفظه في المتغيرات.

{% hint style="info" %}
لا يمكنك تحليل الرد إلا إذا كان بصيغة JSON.
{% endhint %}

تُكتب المتغيرات المحفوظة في آخر إرسال غير مُعبّأ؛ وإذا تم تمرير الإرسال عبر كتلة حمراء، تُلغى المتغيرات. لذا إذا كنت بحاجة إلى حفظ البيانات، فيجب تمرير المتغيرات عبر الكتلة الصفراء.

وبالمناسبة، يمكنك رؤية ما سجله الروبوت في المتغيرات في قسم Leads:

![](https://lh3.googleusercontent.com/e6mzwKUgxl22YqWNmN3HI0afQKM8gcU2OR_E_7Q3NSEzx0n45QLGXI4_UsaWaK52z7-QnULWmfSqCeZhfStALhung9LpFoK2i9EGhNccUcgo-E-7ONrkb7Aj2GEzd0DMDTxLsviV)

### نقل البيانات ليس كسطر

افتراضيًا تأتي قيمة المتغير بصيغة #{} ولكن بعد ذلك تأتي كسطر. ولكي يتم نقل المتغير كرقم، تحتاج إلى إيقاف التحقق من صيغة معاملات post-json.

![](https://lh4.googleusercontent.com/KDDSAYd7NeXu0c7jL45ktnPPeWy7G_YJS-xrf1jvAXf1aKYKGh781E1oGmnS8fw0PbpynqG0lXyqZwK_RfuCC3ezal4-Iu0lo7y5zsNQUT6i21J4C2hb9xw6DF30wReKLorcLliS)

بعد ذلك يمكنك فقط ذكر اسم المتغير، مثل {"key": #{variable\_name}}، وvariable\_name هو المتغير، أي من دون استخدام الأقواس.

{% hint style="warning" %}
بعد إعداد المعلمات يُنصح بإعادة تشغيل التحقق.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mavibot.ai/doc/ar/integrations/api/request.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.