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

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

## كيفية التفاعل مع واجهات برمجة التطبيقات التابعة لجهات خارجية باستخدام Dadata كمثال

لنأخذ واجهة برمجة تطبيقات لاقتراح العناوين كمثال: <https://dadata.ru/api/suggest/address/> <mark style="color:red;">**سيكون الرابط مختلفًا**</mark>

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

{% hint style="warning" %}
يرجى الانتباه! تتطلب واجهات برمجة التطبيقات التابعة لجهات خارجية عناوين IP التي ستُرسل منها الطلبات: 158.160.49.208 – الموقع الإلكتروني.
{% endhint %}

في حقل "Request URL"، أدخل `https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address`.

في **حقل "Request header"** ، أدخل الترويسة بصيغة JSON: `{"Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token}`.

في **حقل "JSON parameters"** ، أدخل الطلب نفسه: `{"query": "#{CurrencyType}"}`.

للحصول على نتيجة الطلب، املأ **"Saved values"** .

يظهر مثال على الطلب في الرسم التوضيحي أدناه.

![](/files/e8b15e3eeb2c9d2112e1a196da44b83e3fe5de27)

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

قد لا يكون الأمر واضحًا تمامًا من المرة الأولى — ستحتاج حقًا إلى تجربته بنفسك.

أولًا، أدخل #{custom\_answer} في حقل "Answer". (المتغير #{custom\_answer} يحتوي على الاستجابة المستلمة من الخادم المحدد في حقل "Response URL".)

شغّل كتلة الطلب لإرسال الطلب والحصول على الاستجابة. يجب تحليل الاستجابة المستلمة، وتحديد المتغيرات التي يجب استخراجها منها. لهذا الغرض، استخدم حقل "Saved Values".

لنمرّ على المثال الموضح أعلاه.

أفضل طريقة لفهم كيفية الوصول إلى البيانات في JSON هي من خلال مثال. ونتيجة لطلبنا، تبدو الاستجابة المستلمة في #{custom\_answer} كما يلي:

`{
"suggestions": [
{
"value": "US Dollar",
"unrestricted_value": "US Dollar",
"data": {
"code": "840",
"strcode": "USD",
"name": "US Dollar",
"country": "United States"
}
}
]
}`

في حقل "Saved values"، أدخل VALUE -> VARIABLE:

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

**suggestions -** مفتاح المصفوفة \[{"value": "US Dollar", "unrestricted\_value": "US Dollar", "data": {"code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States"}}]

**suggestions|0** - مفتاح العنصر الأول في المصفوفة {"value": "US Dollar", "unrestricted\_value": "US Dollar", "data": {"code": "840", "strcode": "USD", "name": "US Dollar", "country": "United States"}}

**suggestions|0|value** - مفتاح القيمة "US Dollar"

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

**suggestions|0|data|strcode** - مفتاح القيمة "USD"

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

{% hint style="info" %}
تحتاج إلى تكرار كامل التداخل. وللتسهيل، يمكنك عرض JSON بصريًا باستخدام تطبيق JSON viewer.
{% endhint %}

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

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

افصل التعابير الخاصة بالحصول على متغيراتنا بفاصلة منقوطة ;.

يتكوّن كل تعبير من مسار البيانات في الاستجابة واسم المتغير المراد حفظه فيه، ويفصل بينهما ->.

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

### تطوير واجهات برمجة التطبيقات للروبوتات

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

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

صيغة تمرير المعلمات: بعد عنوان URL ضع علامة استفهام ?، ثم افصل كل معلمة بعلامة &. تتكوّن كل معلمة من اسم يتبعه = ثم قيمتها.

مثال على عنوان URL يحتوي على معلمة:

![الشكل 3](/files/daa797f843082553051dd1e7d1b33d19eafa317f)

هنا، يتم تمرير معلمة واحدة q بالقيمة "good music". وتمثل %20 مسافة.

عند العمل مع المنشئ، يمكنك ببساطة استخدام مسافة — وسيستبدلها الروبوت تلقائيًا.

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

**رأس الطلب** - يمكنك إضافة ترويسة إلى كل طلب. وغالبًا ما تحدد تنسيق البيانات ومفاتيح الوصول. عادةً ما يُترك هذا الحقل فارغًا، ولكن في حالات نادرة تحتاج إلى تضمين رمز API أو نوع الطلب، مثل "Content-Type": "application/json".

**JSON** (JavaScript Object Notation، وتُلفظ عادةً /ˈdʒeɪsən/ JAY-sən) هو تنسيق تبادل بيانات نصي قائم على JavaScript. وكثير من التنسيقات النصية الأخرى، فإن JSON سهل القراءة للبشر. وللعمل مع واجهات برمجة التطبيقات في الروبوت، تحتاج إلى فهم هذا التنسيق، لأنه أساس جميع التفاعلات.

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

<https://www.json.org/json-ru.html>\
<https://developer.mozilla.org/ru/docs/Learn/JavaScript/%D0%9E%D0%B1%D1%8A%D0%B5%D0%BA%D1%82%D1%8B/JSON>

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

<https://jsoneditoronline.org/>

**تدريب**&#x20;

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

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

![](/files/650c39e726097ea0a1db1e833dde3726a9ee83ec)

يختلف POST-data وPOST-JSON في كيفية إرسال المعلمات، كما ذُكر سابقًا (إما بصيغة JSON أو على شكل أزواج مفتاح-قيمة). إذا اخترت JSON، فلا يمكن إرسال المعلمات إلا في جسم الطلب. وسيظهر حقل إضافي لمعلمات JSON الخاصة بـ POST.

**مهم!** يجب كتابة المعلمات بصيغة JSON فقط، لأن الروبوت يعمل معها حصريًا. لقد تدربت بالفعل على كتابة JSON.

يمكن تحليل الاستجابة من الخادم وحفظها في متغيرات.&#x20;

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

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

يمكنك أيضًا رؤية ما سجّله الروبوت في المتغيرات ضمن قسم "Leads".

![الشكل 8](/files/bacdac411ad1c8b665126c5a3b61b4cb4c656bf4)

### تمرير المتغيرات ليس كنص

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

<figure><img src="/files/95073a6ec9f6590d009a6f11e861999d3f56c3c3" alt=""><figcaption></figcaption></figure>

بعد ذلك يمكنك ببساطة استخدام اسم المتغير، على سبيل المثال: `{"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/alaml-ma-api/altkaml-ma-wajhat-api-altabah-ljhat-kharjyh.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.