# Bubble

Ο **API Connector** στο Bubble στέλνει κλήσεις από τους διακομιστές του Bubble, οπότε εδώ χρειάζεται ένα κλειδί «Μόνο για διακομιστή» και όχι δημόσιο. Το παρακάτω αίτημα στάλθηκε στην παραγωγή ακριβώς όπως το συνθέτει η κλήση· τα βήματα στο Bubble είναι γραμμένα σύμφωνα με τον οδηγό του Bubble από 2026-09-17, και ο ίδιος ο API Connector αναφέρεται στο δωρεάν πρόγραμμα.

Αρχικά, δημιούργησε ένα κλειδί, όπως περιγράφεται στην ενότητα [Κλειδί για αυτοματοποίηση](/integrations/#κλειδί-για-αυτοματοποίηση), με πεδίο `chart`.

## 1. Δημιούργησε μια συλλογή

Στο plugin API Connector πάτησε **+ New** και συμπλήρωσε τη συλλογή:

- **Collection name**: `AstroWay`. Ο οδηγός του Bubble προειδοποιεί ότι το όνομα της συλλογής καταλήγει στον κώδικα πελάτη της εφαρμογής, γι' αυτό κράτησέ το απλό.
- **Authentication**: **Private key in header**, όνομα κεφαλίδας `X-Api-Key`, η τιμή είναι το κλειδί σου.

Αν αφήσεις **None or self-handled**, πρόσθεσε το κλειδί στα **Shared headers for all calls** με το κουμπί **+ Add a shared header** και τσέκαρε το **Private**. Και στις δύο περιπτώσεις, το κλειδί παραμένει στον διακομιστή.

<Aside type="caution" title="Ποτέ μην βάζεις το κλειδί στο Body">
Το Bubble τεκμηριώνει το Body ως client safe: οι τιμές του αποστέλλονται στον browser του επισκέπτη κατά την κλήση. Το URL δεν πηγαίνει εκεί, και η κεφαλίδα με το τσεκαρισμένο **Private** επίσης. Ένα κλειδί που εισάγεται στο JSON-body είναι ήδη ένα δημοσιευμένο κλειδί.
</Aside>

## 2. Πρόσθεσε μια κλήση

Πρόσθεσε μια κλήση μέσα στη συλλογή και συμπλήρωσέ την:

- **Call name**: `Natal chart`.
- **Use as**: **Action** για workflow, **Data**, αν η σελίδα διαβάζει δεδομένα απευθείας.
- **Method**: `POST`.
- **URL**:

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

- **Body type**: **JSON**.
- **Body**: Το JSON παρακάτω. Οι αγκύλες είναι η σύνταξη παραμέτρου στο Bubble, και κάθε μία δημιουργεί μια καταχώριση κάτω από το body.

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

Κάτω από το body **αποεπιλογή Private** από όλες τις πέντε παραμέτρους, ώστε η εφαρμογή να μπορεί να τις ορίζει, και όρισε τις τιμές από τον πίνακα ως προεπιλεγμένες. Στη συνέχεια, πάτησε **Initialize call**.

| Παράμετρος | Τιμή για αρχικοποίηση |
|---|---|
| `date` | `1990-05-15` |
| `time` | `14:30:00` |
| `timezone` | `Europe/Kyiv` |
| `latitude` | `50.45` |
| `longitude` | `30.52` |

Η αρχικοποίηση είναι αυτό που διδάσκει στο Bubble τη μορφή της απάντησης, και ο οδηγός ζητά να χρησιμοποιήσεις για αυτήν δείγματα δεδομένων, τα οποία είναι αυτές οι πέντε τιμές. Η σωστή απάντηση περιέχει `ok` με τιμή true και ένα αντικείμενο `data` με `planets`, `houses` και `input`.

Μετά την προσθήκη ή μετονομασία μιας παραμέτρου, η αρχικοποίηση πρέπει να επαναληφθεί: το σχήμα της απάντησης απομνημονεύεται ακριβώς σε αυτό το βήμα.

## 3. Διάβασε την απάντηση

Μετά την αρχικοποίηση, το Bubble εμφανίζει τα πεδία απάντησης με τον τύπο και το πλαίσιο επιλογής συμπερίληψης. Οι τρεις πιο δημοφιλείς τιμές:

- **Ωροσκόπος**: `data > houses > ascendant`.
- **Ήλιος**: η πρώτη καταχώριση `data > planets`, το `longitude` του.
- **Σελήνη**: η δεύτερη καταχώριση, το `longitude` του.
- **Χρησιμοποιημένη μετατόπιση**: `data > input > timezoneOffset`, για το παραπάνω παράδειγμα είναι `4`, γιατί το Κίεβο εκείνη την ημερομηνία είχε UTC+4.

Το ζώδιο είναι το γεωγραφικό μήκος, διαιρεμένο με το 30 και στρογγυλοποιημένο προς τα κάτω, ως δείκτης σε μια λίστα με δώδεκα ονόματα. Στην έκφραση: διαίρεσε το `data's houses's ascendant` με το 30, πάρε το ακέραιο μέρος και βρες τον αριθμό σε ένα option set ή σε μια λίστα με τα δώδεκα ζώδια. Για παράδειγμα, ο Ωροσκόπος `159.26` δίνει `5`, δηλαδή την Παρθένο.

## Σφάλματα

Τσέκαρε στην κλήση το **Include errors in response &amp; allow workflow actions to continue**, αν θέλεις να χειρίζεσαι τις αποτυχίες στο workflow, αντί να το σταματάς. Το Bubble σημειώνει ότι η εναλλαγή αυτής της επιλογής μετά την αρχικοποίηση αλλάζει τη μορφή της απάντησης, γι' αυτό η αρχικοποίηση πρέπει να επαναληφθεί.

- **`400 INVALID_FIELD` με `timezone` στο `details`**: η ζώνη είναι κενή, είναι μια συντομογραφία όπως `EST` ή δεν είναι όνομα ζώνης.
- **`400` με `date` ή `time` στο `details`**: η μορφή δεν είναι `YYYY-MM-DD` / `HH:MM:SS`. Ο τελεστής `:formatted as` στην ημερομηνία το διορθώνει πριν την κλήση.
- **`403 ENDPOINT_NOT_IN_SCOPE`**: στο πεδίο του κλειδιού δεν υπάρχει `chart`.
- **`429 KEY_BUDGET_EXHAUSTED`**: το κλειδί εξάντλησε τον προϋπολογισμό του· αύξησέ τον στον πίνακα ελέγχου.

<Aside type="note">
Το Bubble στέλνει κλήσεις από κοινή υποδομή, γι' αυτό η διεύθυνσή της είναι κοινή με άλλες εφαρμογές Bubble. Τα όριά μας υπολογίζονται ανά κλειδί, όχι ανά διεύθυνση, γι' αυτό δεν καταναλώνει την ποσόστωσή σου. Το API δεν γεωκωδικοποιεί: οι συντεταγμένες λαμβάνονται από τα δικά σου πεδία ή από μια υπηρεσία γεωκωδικοποίησης για την οποία έχεις κλειδί.
</Aside>