# 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 як client safe: його значення надсилаються в браузер відвідувача під час виклику. URL туди не йде, і заголовок із галочкою **Private** теж. Ключ, вставлений у JSON-тіло, це вже опублікований ключ.
</Aside>

## 2. Додайте виклик

Додайте виклик усередині колекції та заповніть його:

- **Call name**: `Natal chart`.
- **Use as**: **Action** для воркфлоу, **Data**, якщо сторінка читає дані напряму.
- **Method**: `POST`.
- **URL**:

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

- **Body type**: **JSON**.
- **Body**: JSON нижче. Кутові дужки це синтаксис параметра в Bubble, і кожна з них створює запис під тілом.

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

Під тілом **зніміть галочку 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 показує поля відповіді з типом і галочкою включення. Три найпопулярніші значення:

- **Асцендент**: `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 не геокодує: координати беруться з ваших власних полів або із сервісу геокодування, до якого у вас є ключ.
</Aside>