> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução à API

> Autenticação, URL base, códigos de erro, paginação, limites de taxa e chaves de idempotência para a API REST v1 do Flowella — tudo o que precisa antes da primeira chamada.

A API REST do Flowella permite-lhe enviar mensagens WhatsApp, gerir contactos e opt-outs, modelos de listas e de envio em massa e obter análises - de forma programática. Esta página cobre tudo o que precisa de saber antes de chamar um endpoint.

A referência completa do ponto final encontra-se na barra lateral **Referência API** (gerada automaticamente a partir da [OpenAPI spec](/api-reference/openapi.json)).

## URL base

```
https://app.flowella.io
```

Todos os pontos finais v1 estão sob `/api/v1`.

## Autenticação

Cada pedido necessita de uma chave API no cabeçalho `Authorization`:

```http theme={null}
Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx
```

As chaves têm um âmbito organizacional - actuam numa única organização Flowella e herdam as permissões de um Administrador nessa organização.

<Warning>
  Trate as chaves como senhas. Nunca as submeta ao controlo da fonte, nunca as cole no chat ou em documentos partilhados, e rode-as quando os colegas de equipa deixam a organização. Veja [Settings → API keys](/pt/settings/api-keys) para os passos de rotação.
</Warning>

### Criar uma chave

É necessário o papel de **Proprietário** ou **Administrador** para gerir as chaves da API.

1. Ir para **Configurações → Chaves API** na aplicação Flowella.
2. Clique em **Criar chave** e dê-lhe um nome memorável.
3. Copie a chave uma vez - ela é mostrada apenas no momento da criação.

Trate as chaves como palavras-passe: nunca as submeta ao controlo da fonte, nunca as cole no chat e rode-as quando os colegas de equipa deixarem a organização.

### Verificando uma chave

Clique no endpoint ping para confirmar que uma chave é válida:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://app.flowella.io/api/v1/ping \
    -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```js Node.js theme={null}
  await fetch("https://app.flowella.io/api/v1/ping", {
    headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://app.flowella.io/api/v1/ping",
      headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
  )
  ```
</CodeGroup>

Um `200 OK` com `{ "ok": true, "organizationId": "…" }` significa que está autenticado.

## Erros

Todos os erros são devolvidos num envelope consistente:

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
```

| Status HTTP | Quando você o verá                                                                  |
| ----------- | ----------------------------------------------------------------------------------- |
| `400`       | Falha na validação, corpo malformado ou rejeição Meta do upstream                   |
| `401`       | Chave de API em falta ou inválida                                                   |
| `402`       | Pagamento necessário - a sua subscrição não cobre a ação                            |
| `403`       | Proibido - por exemplo, enviar para um contacto excluído, ou o Meta não está ligado |
| `404`       | O canal ou recurso solicitado não existe                                            |
| `429`       | Taxa limitada - abrandar                                                            |

O campo `error.code` é estável e seguro para ser ativado programaticamente. O `error.message` é legível por humanos e pode mudar.

## Limites de taxa

As chaves de API têm um limite de taxa por organização. Se exceder o limite, receberá um `429` com o código `RATE_LIMITED` e a mensagem `Too many requests`. Recue e tente novamente com um atraso exponencial.

Se estiver a executar grandes envios em massa, prefira **`POST /api/v1/templates/send`** com o parâmetro `throttlePerHour` - o Flowella impõe o estrangulamento do lado do servidor, pelo que não precisa de acelerar os pedidos.

## Paginação

Os endpoints de lista (`/conversations`, `/contacts`, `/templates`) utilizam **paginação de cursor**:

* Passar `limit` (1-100, predefinição 25) e um `cursor` opcional.
* A resposta contém `items` e, quando há mais resultados, um `nextCursor`.
* Passar `nextCursor` de volta como o parâmetro `cursor` para buscar a próxima página.
* Quando o `nextCursor` estiver ausente, o utilizador chegou ao fim.

```bash theme={null}
curl "https://app.flowella.io/api/v1/conversations?limit=50" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
```

## Data e hora

Todos os carimbos de data/hora são cadeias de caracteres ISO 8601 em UTC (por exemplo, `2025-01-15T14:30:00.000Z`). Nos casos em que a API aceita datas, tanto a data apenas (`2025-01-15`) como o ISO 8601 completo são coagidos do lado do servidor.

## Números de telefone

Passe números de telefone no formato **E.164** (`+15551234567`) sempre que possível. O Flowella normalizará as variações comuns do lado do servidor, mas o E.164 é mais seguro.

## Canais

Muitos endpoints aceitam um `whatsappChannelId`. Se a sua organização tiver um único canal e o omitir, o Flowella utiliza o seu canal predefinido. Se tiver vários canais, passe o ID explicitamente para evitar enviar do remetente errado.

Para o padrão URL completo e troca de canal, veja [Multi-channel](/pt/essentials/multi-channel).

## OpenAPI spec

A especificação legível por máquina está em:

```
/api-reference/openapi.json
```

Coloque-a no Postman, Insomnia, ou no seu gerador de código de eleição.

<Tip>
  Construindo uma integração? Emparelhe esta página com [Webhooks](/pt/api-reference/webhooks) para reagir a eventos em vez de sondar o estado.
</Tip>