# Bubble

**API Connector** trong Bubble gửi các lệnh gọi từ máy chủ Bubble, vì vậy bạn cần một khóa "Chỉ dành cho máy chủ" ở đây, không phải khóa công khai. Yêu cầu dưới đây được gửi đến môi trường sản xuất chính xác như cách lệnh gọi được tạo; các bước trong Bubble được viết theo hướng dẫn của Bubble tính đến ngày 2026-09-17, và bản thân API Connector được liệt kê trong gói miễn phí.

Trước tiên, hãy tạo một khóa như mô tả trong phần [Khóa tự động hóa](/integrations/#ключ-для-автоматизації), với phạm vi `chart`.

## 1. Tạo một bộ sưu tập

Trong plugin API Connector, nhấp vào **+ New** và điền vào bộ sưu tập:

- **Collection name**: `AstroWay`. Hướng dẫn của Bubble cảnh báo rằng tên bộ sưu tập sẽ xuất hiện trong mã phía máy khách của ứng dụng, vì vậy hãy giữ nó đơn giản.
- **Authentication**: **Private key in header**, tên tiêu đề `X-Api-Key`, giá trị là khóa của bạn.

Nếu bạn để **None or self-handled**, hãy thêm khóa vào **Shared headers for all calls** bằng nút **+ Add a shared header** và đánh dấu vào ô **Private**. Trong cả hai trường hợp, khóa vẫn nằm trên máy chủ.

<Aside type="caution" title="Không bao giờ đặt khóa vào Body">
Bubble tài liệu hóa Body là an toàn cho máy khách: các giá trị của nó được gửi đến trình duyệt của khách truy cập trong quá trình gọi. URL không đi vào đó, và tiêu đề có dấu kiểm **Private** cũng vậy. Khóa được chèn vào phần thân JSON đã là một khóa được công bố.
</Aside>

## 2. Thêm một lệnh gọi

Thêm một lệnh gọi bên trong bộ sưu tập và điền vào đó:

- **Call name**: `Natal chart`.
- **Use as**: **Action** cho quy trình làm việc, **Data**, nếu trang đọc dữ liệu trực tiếp.
- **Method**: `POST`.
- **URL**:

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

- **Body type**: **JSON**.
- **Body**: JSON dưới đây. Dấu ngoặc nhọn là cú pháp tham số trong Bubble, và mỗi dấu ngoặc nhọn tạo một mục nhập dưới phần thân.

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

Dưới phần thân, **bỏ chọn Private** khỏi tất cả năm tham số để ứng dụng có thể đặt chúng, và chỉ định các giá trị từ bảng làm giá trị mặc định. Sau đó, nhấp vào **Initialize call**.

| Tham số | Giá trị để khởi tạo |
|---|---|
| `date` | `1990-05-15` |
| `time` | `14:30:00` |
| `timezone` | `Europe/Kyiv` |
| `latitude` | `50.45` |
| `longitude` | `30.52` |

Khởi tạo là cách Bubble học về định dạng phản hồi, và hướng dẫn yêu cầu sử dụng dữ liệu mẫu cho nó, đó chính là năm giá trị này. Phản hồi đúng sẽ chứa `ok` với giá trị true và một đối tượng `data` với `planets`, `houses` và `input`.

Sau khi thêm hoặc đổi tên một tham số, bạn cần lặp lại quá trình khởi tạo: lược đồ phản hồi được ghi nhớ chính xác ở bước này.

## 3. Đọc phản hồi

Sau khi khởi tạo, Bubble hiển thị các trường phản hồi với kiểu và dấu kiểm bao gồm. Ba giá trị phổ biến nhất:

- **Cung Mọc**: `data > houses > ascendant`.
- **Mặt Trời**: mục nhập đầu tiên `data > planets`, `longitude` của nó.
- **Mặt Trăng**: mục nhập thứ hai, `longitude` của nó.
- **Độ lệch múi giờ đã sử dụng**: `data > input > timezoneOffset`, đối với ví dụ trên là `4`, vì Kyiv vào ngày đó là UTC+4.

Cung là kinh độ, chia cho 30 và làm tròn xuống, như một chỉ mục trong danh sách mười hai tên. Trong biểu thức: chia `data's houses's ascendant` cho 30, lấy phần nguyên và tìm số trong tập hợp tùy chọn hoặc trong danh sách mười hai cung. Ví dụ, Cung Mọc `159.26` cho ra `5`, tức là Xử Nữ.

## Lỗi

Đánh dấu vào ô **Include errors in response &amp; allow workflow actions to continue** trong lệnh gọi nếu bạn muốn xử lý các lỗi trong quy trình làm việc thay vì dừng nó. Bubble lưu ý rằng việc chuyển đổi tùy chọn này sau khi khởi tạo sẽ thay đổi định dạng phản hồi, vì vậy bạn cần lặp lại quá trình khởi tạo.

- **`400 INVALID_FIELD` với `timezone` trong `details`**: múi giờ trống, là một từ viết tắt như `EST` hoặc không phải tên múi giờ.
- **`400` với `date` hoặc `time` trong `details`**: định dạng không phải `YYYY-MM-DD` / `HH:MM:SS`. Toán tử `:formatted as` trên ngày sẽ sửa lỗi này trước khi gọi.
- **`403 ENDPOINT_NOT_IN_SCOPE`**: phạm vi khóa không có `chart`.
- **`429 KEY_BUDGET_EXHAUSTED`**: khóa đã hết ngân sách; hãy tăng nó trong bảng điều khiển.

<Aside type="note">
Bubble gửi các lệnh gọi từ một cơ sở hạ tầng chung, vì vậy địa chỉ của nó được chia sẻ với các ứng dụng Bubble khác. Giới hạn của chúng tôi được tính theo khóa, không phải theo địa chỉ, vì vậy điều này không làm cạn kiệt hạn mức của bạn. API không mã hóa địa lý: tọa độ được lấy từ các trường riêng của bạn hoặc từ dịch vụ mã hóa địa lý mà bạn có khóa.
</Aside>