# Bubble

**API Connector** في Bubble يرسل الاستدعاءات من خوادم Bubble، لذا أنت بحاجة إلى مفتاح "الخادم فقط" هنا، وليس مفتاحًا عامًا. الطلب أدناه يتم إرساله إلى بيئة الإنتاج تمامًا كما يتم إنشاؤه بواسطة الاستدعاء؛ الخطوات في Bubble مكتوبة وفقًا لدليل Bubble اعتبارًا من 2026-09-17، وAPI Connector نفسه مذكور في الخطة المجانية.

أولاً، أنشئ مفتاحًا، كما هو موضح في قسم [مفتاح الأتمتة](/integrations/#ключ-для-автоматизації)، بنطاق `chart`.

## 1. أنشئ مجموعة

في إضافة API Connector، اضغط على **+ New** واملأ تفاصيل المجموعة:

- **Collection name**: `AstroWay`. يحذر دليل Bubble من أن اسم المجموعة يظهر في كود التطبيق من جانب العميل، لذا اجعله بسيطًا.
- **Authentication**: **Private key in header**، اسم الرأس `X-Api-Key`، القيمة هي مفتاحك.

إذا تركت **None or self-handled**، أضف المفتاح إلى **Shared headers for all calls** باستخدام الزر **+ Add a shared header** وحدد مربع **Private**. في كلتا الحالتين، يبقى المفتاح على الخادم.

<Aside type="caution" title="لا تضع المفتاح أبدًا في Body">
يوثق Bubble الـ Body على أنه آمن للعميل: يتم إرسال قيمه إلى متصفح الزائر أثناء الاستدعاء. لا يذهب URL إلى هناك، ولا الرأس الذي يحمل علامة **Private**. المفتاح الذي يتم إدخاله في نص JSON هو مفتاح تم نشره بالفعل.
</Aside>

## 2. أضف استدعاءً

أضف استدعاءً داخل المجموعة واملأ تفاصيله:

- **Call name**: `Natal chart`.
- **Use as**: **Action** لسير العمل (workflow)، أو **Data** إذا كانت الصفحة تقرأ البيانات مباشرة.
- **Method**: `POST`.
- **URL**:

  ```
  https://api.astroway.info/v1/chart
  ```

- **Body type**: **JSON**.
- **Body**: JSON أدناه. الأقواس الزاوية هي صيغة المعلمة في Bubble، وكل منها ينشئ إدخالاً أسفل الـ body.

```json
{
  "date": "<date>",
  "time": "<time>",
  "timezone": "<timezone>",
  "latitude": "<latitude>",
  "longitude": "<longitude>"
}
```

أسفل الـ body، **أزل علامة Private** من جميع المعلمات الخمس، حتى يتمكن التطبيق من تعيينها، وحدد القيم من الجدول كقيم افتراضية. ثم اضغط على **Initialize call**.

| المعلمة | قيمة التهيئة |
|---|---|
| `date` | `1990-05-15` |
| `time` | `14:30:00` |
| `timezone` | `Europe/Kyiv` |
| `latitude` | `50.45` |
| `longitude` | `30.52` |

التهيئة هي ما يعلم Bubble شكل الاستجابة، ويطلب الدليل استخدام بيانات نموذجية لها، وهي هذه القيم الخمس. الاستجابة الصحيحة تحتوي على `ok` بقيمة true وكائن `data` مع `planets` و`houses` و`input`.

بعد إضافة أو إعادة تسمية معلمة، يجب تكرار التهيئة: يتم حفظ مخطط الاستجابة في هذه الخطوة تحديدًا.

## 3. اقرأ الاستجابة

بعد التهيئة، يعرض Bubble حقول الاستجابة مع النوع وعلامة التضمين. القيم الثلاث الأكثر شيوعًا هي:

- **الطالع (Ascendant)**: `data > houses > ascendant`.
- **الشمس**: الإدخال الأول `data > planets`، و`longitude` الخاص بها.
- **القمر**: الإدخال الثاني، و`longitude` الخاص به.
- **الإزاحة المستخدمة**: `data > input > timezoneOffset`، للمثال أعلاه هي `4`، لأن كييف في ذلك التاريخ كانت بتوقيت UTC+4.

البرج هو خط الطول مقسومًا على 30 ومقربًا للأسفل، كفهرس في قائمة من اثني عشر اسمًا. في التعبير: اقسم `data's houses's ascendant` على 30، خذ الجزء الصحيح، وابحث عن الرقم في مجموعة الخيارات (option set) أو في قائمة الأبراج الاثني عشر. على سبيل المثال، الطالع `159.26` يعطي `5`، أي برج العذراء.

## الأخطاء

حدد مربع **Include errors in response &amp; allow workflow actions to continue** في الاستدعاء، إذا كنت ترغب في معالجة الأخطاء في سير العمل بدلاً من إيقافه. يشير Bubble إلى أن تبديل هذا الخيار بعد التهيئة يغير تنسيق الاستجابة، لذا يجب تكرار التهيئة.

- **`400 INVALID_FIELD` مع `timezone` في `details`**: المنطقة فارغة، أو هي اختصار مثل `EST`، أو ليست اسم منطقة.
- **`400` مع `date` أو `time` في `details`**: التنسيق ليس `YYYY-MM-DD` / `HH:MM:SS`. عامل التشغيل `:formatted as` على التاريخ يصحح هذا قبل الاستدعاء.
- **`403 ENDPOINT_NOT_IN_SCOPE`**: نطاق المفتاح لا يحتوي على `chart`.
- **`429 KEY_BUDGET_EXHAUSTED`**: المفتاح استنفد ميزانيته الخاصة؛ قم بزيادتها في لوحة التحكم.

<Aside type="note">
يرسل Bubble الاستدعاءات من بنية تحتية مشتركة، لذا فإن عنوانها مشترك مع تطبيقات Bubble الأخرى. يتم احتساب حدودنا على أساس المفتاح، وليس العنوان، لذا فإن هذا لا يستهلك حصتك. لا يقوم API بالترميز الجغرافي (geocoding): يتم أخذ الإحداثيات من حقولك الخاصة أو من خدمة ترميز جغرافي لديك مفتاح لها.
</Aside>