# Bubble

L'**API Connector** dans Bubble envoie des appels depuis les serveurs Bubble, donc une clé « Serveur uniquement » est nécessaire ici, et non une clé publique. La requête ci-dessous est envoyée en production exactement telle qu'elle est construite par l'appel ; les étapes dans Bubble sont écrites selon le manuel de Bubble en date du 2026-09-17, et l'API Connector lui-même est inclus dans le plan gratuit.

Crée d'abord une clé, comme décrit dans la section [Clé pour l'automatisation](/integrations/#ключ-для-автоматизації), avec la portée `chart`.

## 1. Crée une collection

Dans le plugin API Connector, clique sur **+ New** et remplis la collection :

- **Collection name**: `AstroWay`. Le manuel de Bubble avertit que le nom de la collection se retrouve dans le code client de l'application, alors garde-le simple.
- **Authentication**: **Private key in header**, nom de l'en-tête `X-Api-Key`, la valeur est ta clé.

Si tu laisses **None or self-handled**, ajoute la clé dans **Shared headers for all calls** avec le bouton **+ Add a shared header** et coche la case **Private**. Dans les deux cas, la clé reste sur le serveur.

<Aside type="caution" title="Ne mets jamais la clé dans le Body">
Bubble documente le Body comme étant client safe : ses valeurs sont envoyées au navigateur du visiteur lors de l'appel. L'URL n'y va pas, et l'en-tête avec la case **Private** non plus. Une clé insérée dans le corps JSON est une clé déjà publiée.
</Aside>

## 2. Ajoute un appel

Ajoute un appel à l'intérieur de la collection et remplis-le :

- **Call name**: `Natal chart`.
- **Use as**: **Action** pour un workflow, **Data**, si la page lit les données directement.
- **Method**: `POST`.
- **URL**:

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

- **Body type**: **JSON**.
- **Body**: Le JSON ci-dessous. Les crochets sont la syntaxe des paramètres dans Bubble, et chacun d'eux crée une entrée sous le corps.

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

Sous le corps, **décoche la case Private** pour les cinq paramètres afin que l'application puisse les définir, et spécifie les valeurs du tableau comme valeurs par défaut. Ensuite, clique sur **Initialize call**.

| Paramètre | Valeur pour l'initialisation |
|---|---|
| `date` | `1990-05-15` |
| `time` | `14:30:00` |
| `timezone` | `Europe/Kyiv` |
| `latitude` | `50.45` |
| `longitude` | `30.52` |

L'initialisation est ce qui enseigne à Bubble la forme de la réponse, et le manuel demande d'utiliser des données d'exemple pour cela, ce que sont ces cinq valeurs. Une réponse correcte contient `ok` avec la valeur true et un objet `data` avec `planets`, `houses` et `input`.

Après avoir ajouté ou renommé un paramètre, l'initialisation doit être répétée : le schéma de réponse est mémorisé à cette étape.

## 3. Lis la réponse

Après l'initialisation, Bubble affiche les champs de réponse avec leur type et une case à cocher d'inclusion. Les trois valeurs les plus populaires :

- **Ascendant**: `data > houses > ascendant`.
- **Soleil**: la première entrée de `data > planets`, sa `longitude`.
- **Lune**: la deuxième entrée, sa `longitude`.
- **Décalage utilisé**: `data > input > timezoneOffset`, pour l'exemple ci-dessus, c'est `4`, car Kiev à cette date était en UTC+4.

Le signe est la longitude divisée par 30 et arrondie à l'inférieur, comme un index dans une liste de douze noms. Dans l'expression : divise `data's houses's ascendant` par 30, prends la partie entière et trouve le nombre dans un option set ou dans une liste des douze signes. Par exemple, un Ascendant de `159.26` donne `5`, c'est-à-dire la Vierge.

## Erreurs

Coche la case **Include errors in response &amp; allow workflow actions to continue** sur l'appel si tu veux gérer les échecs dans le workflow au lieu de l'arrêter. Bubble indique que la modification de cette option après l'initialisation change le format de la réponse, donc l'initialisation doit être répétée.

- **`400 INVALID_FIELD` avec `timezone` dans `details`**: la zone est vide, c'est une abréviation comme `EST` ou ce n'est pas un nom de zone.
- **`400` avec `date` ou `time` dans `details`**: le format n'est pas `YYYY-MM-DD` / `HH:MM:SS`. L'opérateur `:formatted as` sur la date corrige cela avant l'appel.
- **`403 ENDPOINT_NOT_IN_SCOPE`**: la portée de la clé ne contient pas `chart`.
- **`429 KEY_BUDGET_EXHAUSTED`**: la clé a épuisé son budget ; augmente-le dans le tableau de bord.

<Aside type="note">
Bubble envoie des appels depuis une infrastructure partagée, donc son adresse est partagée avec d'autres applications Bubble. Nos limites sont comptées par clé, et non par adresse, donc cela ne consomme pas ton quota. L'API ne géocode pas : les coordonnées sont prises de tes propres champs ou d'un service de géocodage pour lequel tu as une clé.
</Aside>