# Bubble

**API Connector** en Bubble envía llamadas desde los servidores de Bubble, por lo que aquí se necesita una clave «Solo servidor», no pública. La solicitud a continuación se envía a producción tal como la compone la llamada; los pasos en Bubble están escritos según la guía de Bubble al 2026-09-17, y el propio API Connector está incluido en el plan gratuito.

Primero crea una clave, como se describe en la sección [Clave para automatización](/integrations/#ключ-для-автоматизації), con el ámbito `chart`.

## 1. Crea una colección

En el plugin API Connector haz clic en **+ New** y completa la colección:

- **Collection name**: `AstroWay`. La guía de Bubble advierte que el nombre de la colección termina en el código cliente de la aplicación, así que mantenlo simple.
- **Authentication**: **Private key in header**, el nombre del encabezado `X-Api-Key`, el valor es tu clave.

Si dejas **None or self-handled**, añade la clave en **Shared headers for all calls** con el botón **+ Add a shared header** y marca la casilla **Private**. En ambos casos la clave permanece en el servidor.

<Aside type="caution" title="Ніколи не кладіть ключ у Body">
Bubble documenta Body como client safe: su valor se envía al navegador del visitante durante la llamada. La URL no va allí, y el encabezado con la casilla **Private** tampoco. Una clave insertada en el cuerpo JSON ya es una clave publicada.
</Aside>

## 2. Añade la llamada

Añade la llamada dentro de la colección y complétala:

- **Call name**: `Natal chart`.
- **Use as**: **Action** para el flujo de trabajo, **Data**, si la página lee los datos directamente.
- **Method**: `POST`.
- **URL**:

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

- **Body type**: **JSON**.
- **Body**: JSON a continuación. Los corchetes angulares son la sintaxis del parámetro en Bubble, y cada uno crea una entrada bajo el cuerpo.

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

Bajo el cuerpo **desmarca Private** de los cinco parámetros, para que la aplicación pueda establecerlos, y especifica los valores de la tabla como predeterminados. Luego haz clic en **Initialize call**.

| Parámetro | Valor para inicialización |
|---|---|
| `date` | `1990-05-15` |
| `time` | `14:30:00` |
| `timezone` | `Europe/Kyiv` |
| `latitude` | `50.45` |
| `longitude` | `30.52` |

La inicialización es lo que enseña a Bubble la forma de la respuesta, y la guía pide usar datos de ejemplo, que son estos cinco valores. La respuesta correcta contiene `ok` con valor true y un objeto `data` con `planets`, `houses` y `input`.

Después de añadir o renombrar un parámetro, la inicialización debe repetirse: el esquema de respuesta se guarda en este paso.

## 3. Lee la respuesta

Después de la inicialización, Bubble muestra los campos de respuesta con tipo y casilla de inclusión. Los tres valores más populares:

- **Ascendente**: `data > houses > ascendant`.
- **Sol**: el primer registro `data > planets`, su `longitude`.
- **Luna**: el segundo registro, su `longitude`.
- **Desplazamiento usado**: `data > input > timezoneOffset`, en el ejemplo anterior es `4`, porque Kyiv en esa fecha tenía UTC+4.

El signo es la longitud dividida por 30 y redondeada hacia abajo, como índice en una lista de doce nombres. En la expresión: divide `data's houses's ascendant` por 30, toma la parte entera y busca el número en el conjunto de opciones o en la lista de los doce signos. Por ejemplo, Ascendente `159.26` da `5`, es decir, Virgo.

## Errores

Marca en la llamada la casilla **Include errors in response &amp; allow workflow actions to continue**, si deseas manejar fallos en el flujo de trabajo en lugar de detenerlo. Bubble indica que cambiar esta opción después de la inicialización altera el formato de la respuesta, por lo que la inicialización debe repetirse.

- **`400 INVALID_FIELD` con `timezone` en `details`**: zona vacía, es una abreviatura como `EST` o no es un nombre de zona.
- **`400` con `date` o `time` en `details`**: formato no `YYYY-MM-DD` / `HH:MM:SS`. El operador `:formatted as` en la fecha corrige esto para la llamada.
- **`403 ENDPOINT_NOT_IN_SCOPE`**: el ámbito de la clave no incluye `chart`.
- **`429 KEY_BUDGET_EXHAUSTED`**: la clave agotó su presupuesto; elévala en el dashboard.

<Aside type="note">
Bubble envía llamadas desde la infraestructura compartida, por lo que su dirección es la misma que la de otras aplicaciones Bubble. Nuestros límites se contabilizan por clave, no por dirección, así que no consume tu cuota. La API no geocodifica: las coordenadas se toman de tus propios campos o del servicio de geocodificación al que tienes clave.
</Aside>