# Bubble

**API Connector** in Bubble invia chiamate dai server di Bubble, quindi qui è necessaria una chiave "Solo server", non una pubblica. La richiesta seguente viene inviata in produzione esattamente come la compone la chiamata; i passaggi in Bubble sono scritti secondo la guida di Bubble al 2026-09-17, e l'API Connector stesso è incluso nel piano gratuito.

Per prima cosa, crea una chiave, come descritto nella sezione [Chiave per l'automazione](/integrations/#ключ-для-автоматизації), con lo scope `chart`.

## 1. Crea una collezione

Nel plugin API Connector, clicca su **+ New** e compila la collezione:

- **Collection name**: `AstroWay`. La guida di Bubble avverte che il nome della collezione finisce nel codice client dell'applicazione, quindi mantienilo semplice.
- **Authentication**: **Private key in header**, nome dell'header `X-Api-Key`, il valore è la tua chiave.

Se lasci **None or self-handled**, aggiungi la chiave in **Shared headers for all calls** con il pulsante **+ Add a shared header** e spunta la casella **Private**. In entrambi i casi, la chiave rimane sul server.

<Aside type="caution" title="Non inserire mai la chiave nel Body">
Bubble documenta il Body come client safe: i suoi valori vengono inviati al browser del visitatore durante la chiamata. L'URL non ci va, e nemmeno l'header con la spunta **Private**. Una chiave inserita nel corpo JSON è già una chiave pubblicata.
</Aside>

## 2. Aggiungi una chiamata

Aggiungi una chiamata all'interno della collezione e compilala:

- **Call name**: `Natal chart`.
- **Use as**: **Action** per il workflow, **Data**, se la pagina legge i dati direttamente.
- **Method**: `POST`.
- **URL**:

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

- **Body type**: **JSON**.
- **Body**: il JSON seguente. Le parentesi angolari sono la sintassi del parametro in Bubble, e ognuna di esse crea una voce sotto il corpo.

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

Sotto il corpo, **deseleziona la casella Private** per tutti e cinque i parametri, in modo che l'applicazione possa impostarli, e specifica i valori dalla tabella come predefiniti. Quindi clicca su **Initialize call**.

| Parametro | Valore per l'inizializzazione |
|---|---|
| `date` | `1990-05-15` |
| `time` | `14:30:00` |
| `timezone` | `Europe/Kyiv` |
| `latitude` | `50.45` |
| `longitude` | `30.52` |

L'inizializzazione è ciò che insegna a Bubble la forma della risposta, e la guida chiede di utilizzare dati di esempio per essa, che sono questi cinque valori. Una risposta corretta contiene `ok` con valore true e un oggetto `data` con `planets`, `houses` e `input`.

Dopo aver aggiunto o rinominato un parametro, l'inizializzazione deve essere ripetuta: lo schema della risposta viene memorizzato proprio in questo passaggio.

## 3. Leggi la risposta

Dopo l'inizializzazione, Bubble mostra i campi della risposta con il tipo e la casella di spunta per l'inclusione. I tre valori più popolari:

- **Ascendente**: `data > houses > ascendant`.
- **Sole**: la prima voce di `data > planets`, la sua `longitude`.
- **Luna**: la seconda voce, la sua `longitude`.
- **Offset utilizzato**: `data > input > timezoneOffset`, per l'esempio sopra è `4`, perché Kiev a quella data manteneva UTC+4.

Il segno è la longitudine, divisa per 30 e arrotondata per difetto, come indice in un elenco di dodici nomi. Nell'espressione: dividi `data's houses's ascendant` per 30, prendi la parte intera e trova il numero in un option set o in un elenco di dodici segni. Per esempio, l'Ascendente `159.26` dà `5`, cioè la Vergine.

## Errori

Spunta la casella **Include errors in response &amp; allow workflow actions to continue** sulla chiamata, se vuoi gestire i fallimenti nel workflow anziché fermarlo. Bubble nota che l'attivazione di questa opzione dopo l'inizializzazione cambia il formato della risposta, quindi l'inizializzazione deve essere ripetuta.

- **`400 INVALID_FIELD` con `timezone` in `details`**: il fuso orario è vuoto, è un'abbreviazione come `EST` o non un nome di zona.
- **`400` con `date` o `time` in `details`**: il formato non è `YYYY-MM-DD` / `HH:MM:SS`. L'operatore `:formatted as` sulla data lo corregge prima della chiamata.
- **`403 ENDPOINT_NOT_IN_SCOPE`**: lo scope della chiave non include `chart`.
- **`429 KEY_BUDGET_EXHAUSTED`**: la chiave ha esaurito il proprio budget; aumentalo nella dashboard.

<Aside type="note">
Bubble invia chiamate da un'infrastruttura condivisa, quindi il suo indirizzo è condiviso con altre applicazioni Bubble. I nostri limiti sono calcolati per chiave, non per indirizzo, quindi questo non consuma la tua quota. L'API non geocodifica: le coordinate vengono prese dai tuoi campi o da un servizio di geocodifica per il quale hai una chiave.
</Aside>