# Bubble

**API Connector** w Bubble wysyła wywołania z serwerów Bubble, więc potrzebny jest tutaj klucz „Tylko serwer”, a nie publiczny. Poniższe zapytanie jest wysyłane do produkcji dokładnie w takiej formie, w jakiej jest tworzone przez wywołanie; kroki w Bubble są napisane zgodnie z przewodnikiem Bubble z dnia 2026-09-17, a sam API Connector jest dostępny w darmowym planie.

Najpierw utwórz klucz, jak opisano w sekcji [Klucz do automatyzacji](/integrations/#ключ-для-автоматизації), z zakresem `chart`.

## 1. Utwórz kolekcję

Wtyczce API Connector kliknij **+ New** i wypełnij kolekcję:

- **Collection name**: `AstroWay`. Przewodnik Bubble ostrzega, że nazwa kolekcji trafia do kodu klienta aplikacji, więc zachowaj ją prostą.
- **Authentication**: **Private key in header**, nazwa nagłówka `X-Api-Key`, wartość to twój klucz.

Jeśli pozostawisz **None or self-handled**, dodaj klucz w **Shared headers for all calls** przyciskiem **+ Add a shared header** i zaznacz na nim pole **Private**. W obu przypadkach klucz pozostaje na serwerze.

<Aside type="caution" title="Nigdy nie umieszczaj klucza w Body">
Bubble dokumentuje Body jako client safe: jego wartości są wysyłane do przeglądarki odwiedzającego podczas wywołania. URL tam nie trafia, podobnie jak nagłówek z zaznaczonym polem **Private**. Klucz wstawiony do ciała JSON to już opublikowany klucz.
</Aside>

## 2. Dodaj wywołanie

Dodaj wywołanie wewnątrz kolekcji i wypełnij je:

- **Call name**: `Natal chart`.
- **Use as**: **Action** dla workflow, **Data**, jeśli strona odczytuje dane bezpośrednio.
- **Method**: `POST`.
- **URL**:

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

- **Body type**: **JSON**.
- **Body**: Poniższy JSON. Nawiasy kątowe to składnia parametru w Bubble, a każdy z nich tworzy wpis pod ciałem.

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

Pod ciałem **odznacz pole Private** dla wszystkich pięciu parametrów, aby aplikacja mogła je ustawiać, i podaj wartości z tabeli jako domyślne. Następnie kliknij **Initialize call**.

| Parametr | Wartość do inicjalizacji |
|---|---|
| `date` | `1990-05-15` |
| `time` | `14:30:00` |
| `timezone` | `Europe/Kyiv` |
| `latitude` | `50.45` |
| `longitude` | `30.52` |

Inicjalizacja to to, co uczy Bubble formy odpowiedzi, a przewodnik prosi o użycie do niej przykładowych danych, którymi są te pięć wartości. Prawidłowa odpowiedź zawiera `ok` z wartością true oraz obiekt `data` z `planets`, `houses` i `input`.

Po dodaniu lub zmianie nazwy parametru inicjalizację należy powtórzyć: schemat odpowiedzi jest zapamiętywany właśnie na tym kroku.

## 3. Odczytaj odpowiedź

Po inicjalizacji Bubble pokazuje pola odpowiedzi z typem i zaznaczeniem włączenia. Trzy najpopularniejsze wartości:

- **Ascendent**: `data > houses > ascendant`.
- **Słońce**: pierwszy wpis `data > planets`, jego `longitude`.
- **Księżyc**: drugi wpis, jego `longitude`.
- **Użyte przesunięcie**: `data > input > timezoneOffset`, dla powyższego przykładu to `4`, ponieważ Kijów w tym dniu miał UTC+4.

Znak to długość geograficzna, podzielona przez 30 i zaokrąglona w dół, jako indeks na liście dwunastu nazw. W wyrażeniu: podziel `data's houses's ascendant` przez 30, weź część całkowitą i znajdź liczbę w option set lub na liście dwunastu znaków. Na przykład Ascendent `159.26` daje `5`, czyli Pannę.

## Błędy

Zaznacz w wywołaniu pole **Include errors in response &amp; allow workflow actions to continue**, jeśli chcesz obsługiwać błędy w workflow, a nie go zatrzymywać. Bubble zaznacza, że przełączenie tej opcji po inicjalizacji zmienia format odpowiedzi, więc inicjalizację należy powtórzyć.

- **`400 INVALID_FIELD` z `timezone` w `details`**: strefa jest pusta, to skrót typu `EST` lub nie jest nazwą strefy.
- **`400` z `date` lub `time` w `details`**: format nie jest `YYYY-MM-DD` / `HH:MM:SS`. Operator `:formatted as` na dacie poprawia to przed wywołaniem.
- **`403 ENDPOINT_NOT_IN_SCOPE`**: w zakresie klucza nie ma `chart`.
- **`429 KEY_BUDGET_EXHAUSTED`**: klucz wyczerpał swój budżet; zwiększ go w panelu sterowania.

<Aside type="note">
Bubble wysyła wywołania ze wspólnej infrastruktury, więc jej adres jest wspólny z innymi aplikacjami Bubble. Nasze limity są liczone na klucz, a nie na adres, więc nie zużywa to twojej kwoty. API nie geokoduje: współrzędne są pobierane z twoich własnych pól lub z usługi geokodowania, do której masz klucz.
</Aside>