# Bubble

**API Connector** în Bubble trimite apeluri de pe serverele Bubble, așa că aici este necesară o cheie „Doar server”, nu una publică. Cererea de mai jos este trimisă în producție exact așa cum este compusă de apel; pașii din Bubble sunt scriși conform ghidului Bubble la data de 2026-09-17, iar API Connector în sine este inclus în planul gratuit.

Mai întâi, creează o cheie, așa cum este descris în secțiunea [Cheie pentru automatizare](/integrations/#ключ-для-автоматизації), cu domeniul `chart`.

## 1. Creează o colecție

În pluginul API Connector, apasă **+ New** și completează colecția:

- **Collection name**: `AstroWay`. Ghidul Bubble avertizează că numele colecției ajunge în codul client al aplicației, așa că menține-l simplu.
- **Authentication**: **Private key in header**, numele antetului `X-Api-Key`, valoarea este cheia ta.

Dacă lași **None or self-handled**, adaugă cheia în **Shared headers for all calls** cu butonul **+ Add a shared header** și bifează **Private**. În ambele cazuri, cheia rămâne pe server.

<Aside type="caution" title="Nu pune niciodată cheia în Body">
Bubble documentează Body ca fiind client safe: valorile sale sunt trimise în browserul vizitatorului în timpul apelului. URL-ul nu merge acolo, și nici antetul cu bifa **Private**. O cheie inserată în corpul JSON este deja o cheie publicată.
</Aside>

## 2. Adaugă un apel

Adaugă un apel în interiorul colecției și completează-l:

- **Call name**: `Natal chart`.
- **Use as**: **Action** pentru un workflow, **Data**, dacă pagina citește date direct.
- **Method**: `POST`.
- **URL**:

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

- **Body type**: **JSON**.
- **Body**: JSON-ul de mai jos. Parantezele unghiulare sunt sintaxa unui parametru în Bubble, și fiecare dintre ele creează o intrare sub corp.

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

Sub corp, **debifează Private** de la toți cei cinci parametri, astfel încât aplicația să-i poată seta, și specifică valorile din tabel ca fiind implicite. Apoi apasă **Initialize call**.

| Parametru | Valoare pentru inițializare |
|---|---|
| `date` | `1990-05-15` |
| `time` | `14:30:00` |
| `timezone` | `Europe/Kyiv` |
| `latitude` | `50.45` |
| `longitude` | `30.52` |

Inițializarea este ceea ce învață Bubble forma răspunsului, iar ghidul cere să folosești date eșantion pentru aceasta, care sunt aceste cinci valori. Un răspuns corect conține `ok` cu valoarea true și un obiect `data` cu `planets`, `houses` și `input`.

După adăugarea sau redenumirea unui parametru, inițializarea trebuie repetată: schema răspunsului este memorată exact la acest pas.

## 3. Citește răspunsul

După inițializare, Bubble afișează câmpurile răspunsului cu tipul și bifa de includere. Trei dintre cele mai populare valori:

- **Ascendent**: `data > houses > ascendant`.
- **Soare**: prima înregistrare `data > planets`, `longitude`-ul său.
- **Lună**: a doua înregistrare, `longitude`-ul său.
- **Decalaj folosit**: `data > input > timezoneOffset`, pentru exemplul de mai sus este `4`, deoarece Kievul la acea dată a avut UTC+4.

Semnul este longitudinea, împărțită la 30 și rotunjită în jos, ca un index într-o listă de douăsprezece nume. În expresie: împarte `data's houses's ascendant` la 30, ia partea întreagă și găsește numărul într-un option set sau într-o listă de douăsprezece semne. De exemplu, Ascendentul `159.26` dă `5`, adică Fecioara.

## Erori

Bifează **Include errors in response &amp; allow workflow actions to continue** la apel, dacă vrei să gestionezi erorile în workflow, în loc să-l oprești. Bubble menționează că schimbarea acestei opțiuni după inițializare modifică formatul răspunsului, așa că inițializarea trebuie repetată.

- **`400 INVALID_FIELD` cu `timezone` în `details`**: zona este goală, este o abreviere precum `EST` sau nu este un nume de zonă.
- **`400` cu `date` sau `time` în `details`**: formatul nu este `YYYY-MM-DD` / `HH:MM:SS`. Operatorul `:formatted as` pe dată corectează acest lucru înainte de apel.
- **`403 ENDPOINT_NOT_IN_SCOPE`**: domeniul cheii nu conține `chart`.
- **`429 KEY_BUDGET_EXHAUSTED`**: cheia și-a epuizat bugetul; mărește-l în dashboard.

<Aside type="note">
Bubble trimite apeluri dintr-o infrastructură partajată, așa că adresa sa este comună cu alte aplicații Bubble. Limitele noastre sunt contorizate pe cheie, nu pe adresă, așa că acest lucru nu îți consumă cota. API-ul nu geocodifică: coordonatele sunt preluate din propriile tale câmpuri sau dintr-un serviciu de geocodificare pentru care ai o cheie.
</Aside>