# Bubble

**API Connector** no Bubble envia chamadas dos servidores do Bubble, por isso é necessária uma chave 'Apenas servidor', e não uma pública. O pedido abaixo é enviado para produção exatamente como a chamada o compõe; os passos no Bubble são escritos de acordo com o manual do Bubble a partir de 2026-09-17, e o próprio API Connector está incluído no plano gratuito.

Primeiro, cria uma chave, conforme descrito na secção [Chave para automação](/integrations/#ключ-для-автоматизації), com o âmbito `chart`.

## 1. Cria uma coleção

No plugin API Connector, clica em **+ New** e preenche a coleção:

- **Collection name**: `AstroWay`. O manual do Bubble avisa que o nome da coleção entra no código do cliente da aplicação, por isso mantém-no simples.
- **Authentication**: **Private key in header**, nome do cabeçalho `X-Api-Key`, o valor é a tua chave.

Se deixares **None or self-handled**, adiciona a chave em **Shared headers for all calls** com o botão **+ Add a shared header** e marca a caixa **Private**. Em ambos os casos, a chave permanece no servidor.

<Aside type="caution" title="Nunca coloques a chave no Body">
O Bubble documenta o Body como client safe: os seus valores são enviados para o navegador do visitante durante a chamada. O URL não vai para lá, e o cabeçalho com a caixa **Private** também não. Uma chave inserida no corpo JSON é uma chave já publicada.
</Aside>

## 2. Adiciona uma chamada

Adiciona uma chamada dentro da coleção e preenche-a:

- **Call name**: `Natal chart`.
- **Use as**: **Action** para o workflow, **Data**, se a página lê dados diretamente.
- **Method**: `POST`.
- **URL**:

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

- **Body type**: **JSON**.
- **Body**: O JSON abaixo. Os parênteses angulares são a sintaxe do parâmetro no Bubble, e cada um deles cria uma entrada abaixo do corpo.

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

Abaixo do corpo, **desmarca a caixa Private** de todos os cinco parâmetros para que a aplicação possa defini-los, e especifica os valores da tabela como predefinidos. Em seguida, clica em **Initialize call**.

| Parâmetro | Valor para inicialização |
|---|---|
| `date` | `1990-05-15` |
| `time` | `14:30:00` |
| `timezone` | `Europe/Kyiv` |
| `latitude` | `50.45` |
| `longitude` | `30.52` |

A inicialização é o que ensina ao Bubble o formato da resposta, e o manual pede para usar dados de exemplo para ela, que são estes cinco valores. Uma resposta correta contém `ok` com o valor true e um objeto `data` com `planets`, `houses` e `input`.

Após adicionar ou renomear um parâmetro, a inicialização deve ser repetida: o esquema de resposta é memorizado precisamente neste passo.

## 3. Lê a resposta

Após a inicialização, o Bubble mostra os campos de resposta com o tipo e a caixa de seleção de inclusão. Os três valores mais populares:

- **Ascendente**: `data > houses > ascendant`.
- **Sol**: a primeira entrada de `data > planets`, a sua `longitude`.
- **Lua**: a segunda entrada, a sua `longitude`.
- **Desvio usado**: `data > input > timezoneOffset`, para o exemplo acima é `4`, porque Kiev nessa data mantinha UTC+4.

O signo é a longitude, dividida por 30 e arredondada para baixo, como um índice numa lista de doze nomes. Na expressão: divide `data's houses's ascendant` por 30, pega na parte inteira e encontra o número num option set ou numa lista de doze signos. Por exemplo, o Ascendente `159.26` dá `5`, ou seja, Virgem.

## Erros

Marca a caixa **Include errors in response &amp; allow workflow actions to continue** na chamada, se quiseres processar falhas no workflow em vez de o parar. O Bubble observa que alternar esta opção após a inicialização altera o formato da resposta, por isso a inicialização deve ser repetida.

- **`400 INVALID_FIELD` com `timezone` em `details`**: a zona está vazia, é uma abreviatura como `EST` ou não é um nome de zona.
- **`400` com `date` ou `time` em `details`**: o formato não é `YYYY-MM-DD` / `HH:MM:SS`. O operador `:formatted as` na data corrige isto antes da chamada.
- **`403 ENDPOINT_NOT_IN_SCOPE`**: o âmbito da chave não contém `chart`.
- **`429 KEY_BUDGET_EXHAUSTED`**: a chave esgotou o seu próprio orçamento; aumenta-o no dashboard.

<Aside type="note">
O Bubble envia chamadas de uma infraestrutura partilhada, por isso o seu endereço é partilhado com outras aplicações Bubble. Os nossos limites são contados por chave, e não por endereço, por isso isto não consome a tua quota. A API não geocodifica: as coordenadas são retiradas dos teus próprios campos ou de um serviço de geocodificação para o qual tens uma chave.
</Aside>