# Bubble

**API Connector** v Bubble odesílá volání ze serverů Bubble, proto zde potřebuješ klíč „Pouze server“, nikoli veřejný. Níže uvedený požadavek je odeslán do produkce přesně v té podobě, v jaké ho volání sestavuje; kroky v Bubble jsou napsány podle manuálu Bubble k 2026-09-17 a samotný API Connector je uveden v bezplatném tarifu.

Nejprve si vytvoř klíč, jak je popsáno v sekci [Klíč pro automatizaci](/integrations/#ключ-для-автоматизації), s rozsahem `chart`.

## 1. Vytvoř kolekci

V pluginu API Connector klikni na **+ New** a vyplň kolekci:

- **Collection name**: `AstroWay`. Manuál Bubble varuje, že název kolekce se dostane do klientského kódu aplikace, takže ho udržuj jednoduchý.
- **Authentication**: **Private key in header**, název hlavičky `X-Api-Key`, hodnota je tvůj klíč.

Pokud ponecháš **None or self-handled**, přidej klíč do **Shared headers for all calls** tlačítkem **+ Add a shared header** a zaškrtni u něj **Private**. V obou případech klíč zůstává na serveru.

<Aside type="caution" title="Nikdy nevkládej klíč do Body">
Bubble dokumentuje Body jako client safe: jeho hodnoty jsou odesílány do prohlížeče návštěvníka během volání. URL tam nejde, a hlavička se zaškrtnutím **Private** také ne. Klíč vložený do JSON těla je již publikovaný klíč.
</Aside>

## 2. Přidej volání

Přidej volání uvnitř kolekce a vyplň ho:

- **Call name**: `Natal chart`.
- **Use as**: **Action** pro workflow, **Data**, pokud stránka čte data přímo.
- **Method**: `POST`.
- **URL**:

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

- **Body type**: **JSON**.
- **Body**: Níže uvedený JSON. Hranaté závorky jsou syntaxe parametru v Bubble, a každá z nich vytváří záznam pod tělem.

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

Pod tělem **zruš zaškrtnutí Private** u všech pěti parametrů, aby je aplikace mohla zadávat, a uveď hodnoty z tabulky jako výchozí. Dále klikni na **Initialize call**.

| Parametr | Hodnota pro inicializaci |
|---|---|
| `date` | `1990-05-15` |
| `time` | `14:30:00` |
| `timezone` | `Europe/Kyiv` |
| `latitude` | `50.45` |
| `longitude` | `30.52` |

Inicializace je to, co učí Bubble formu odpovědi, a manuál žádá, abys pro ni použil vzorová data, kterými je těchto pět hodnot. Správná odpověď obsahuje `ok` s hodnotou true a objekt `data` s `planets`, `houses` a `input`.

Po přidání nebo přejmenování parametru je třeba inicializaci zopakovat: schéma odpovědi se zapamatuje právě v tomto kroku.

## 3. Přečti si odpověď

Po inicializaci Bubble zobrazuje pole odpovědi s typem a zaškrtnutím pro zahrnutí. Tři nejoblíbenější hodnoty:

- **Ascendent**: `data > houses > ascendant`.
- **Slunce**: první záznam `data > planets`, jeho `longitude`.
- **Měsíc**: druhý záznam, jeho `longitude`.
- **Použitý posun**: `data > input > timezoneOffset`, pro výše uvedený příklad je to `4`, protože Kyjev v ten den držel UTC+4.

Znamení je zeměpisná délka, dělená 30 a zaokrouhlená dolů, jako index v seznamu dvanácti názvů. Ve výrazu: vyděl `data's houses's ascendant` 30, vezmi celou část a najdi číslo v option setu nebo v seznamu dvanácti znamení. Pro příklad Ascendent `159.26` dává `5`, tedy Pannu.

## Chyby

Zaškrtni u volání **Include errors in response &amp; allow workflow actions to continue**, pokud chceš zpracovávat selhání ve workflow, a ne ho zastavovat. Bubble uvádí, že přepnutí této možnosti po inicializaci mění formát odpovědi, takže je třeba inicializaci zopakovat.

- **`400 INVALID_FIELD` s `timezone` v `details`**: zóna je prázdná, je to zkratka jako `EST` nebo ne název zóny.
- **`400` s `date` či `time` v `details`**: formát není `YYYY-MM-DD` / `HH:MM:SS`. Operátor `:formatted as` na datu to opraví před voláním.
- **`403 ENDPOINT_NOT_IN_SCOPE`**: v rozsahu klíče není `chart`.
- **`429 KEY_BUDGET_EXHAUSTED`**: klíč vyčerpal svůj rozpočet; zvyšte ho v dashboardu.

<Aside type="note">
Bubble odesílá volání ze sdílené infrastruktury, takže její adresa je sdílená s ostatními aplikacemi Bubble. Naše limity se počítají na klíč, nikoli na adresu, takže tvou kvótu to nespotřebuje. API negeokóduje: souřadnice se berou z tvých vlastních polí nebo ze služby geokódování, ke které máš klíč.
</Aside>