> ## 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, listar e enviar modelos 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 dos endpoints encontra-se na barra lateral **Referência API** (gerada automaticamente a partir da [especificação OpenAPI](/api-reference/openapi.json)).

## URL base

```
https://api.flowella.io/v1
```

Todos os endpoints v1 vivem sob esta base canónica — por exemplo `https://api.flowella.io/v1/messages`.

<Note>
  Anteriormente, a API estava no host da aplicação em `https://app.flowella.io/api/v1/...`. Os pedidos legados a esse caminho são redirecionados permanentemente (`308`) para `https://api.flowella.io/v1/...` canónico, preservando o método e o corpo — pelo que as integrações existentes continuam a funcionar. Atualize o seu URL base quando puder para evitar o salto extra.
</Note>

## Autenticação

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

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

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

<Warning>
  Trate as chaves como palavras-passe. Nunca as coloque no controlo de versões, nunca as cole em chat ou documentos partilhados, e rode-as quando colegas saírem da organização. Consulte [Definições → Chaves API](/pt/settings/api-keys) para os passos de rotação.
</Warning>

### Criar uma chave

Precisa da função **Proprietário** ou **Administrador** para gerir chaves API.

1. Aceda a **Definiçõ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 — só é mostrada no momento da criação.

Trate as chaves como palavras-passe: nunca as coloque no controlo de versões, nunca as cole em chat e rode-as quando colegas saírem da organização.

### Verificar uma chave

Chame o endpoint de ping para confirmar que uma chave é válida:

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

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

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

  requests.get(
      "https://api.flowella.io/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 vêm num envelope consistente:

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

| Estado HTTP | Quando o verá |
| - | - |
| `400` | Validação falhou, corpo mal formado ou rejeição a montante da Meta |
| `401` | Chave 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 opt-out, ou Meta não ligada |
| `404` | O canal ou recurso pedido não existe |
| `429` | Limite de taxa — abrande |

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

## Limites de taxa

As chaves API têm limite de taxa por organização. Se exceder o limite, obterá um `429` com o código `RATE_LIMITED` e a mensagem `Too many requests`. Quando presente, o cabeçalho de resposta `Retry-After` indica quantos segundos deve esperar. Recue e tente novamente com atraso exponencial.

Se está a executar envios em massa grandes, prefira **`POST /v1/templates/send`** com o parâmetro `throttlePerHour` — o Flowella aplica o limite no servidor, portanto não precisa de ritmar pedidos.

## Chaves de idempotência

Os envios em massa de modelos são assíncronos. `POST /v1/templates/send` valida o pedido, coloca-o em fila de forma durável e devolve `202 Accepted` imediatamente:

```json theme={null}
{
  "id": "v1ts-0123456789abcdef",
  "status": "accepted"
}
```

O Flowella entrega o lote em segundo plano e tenta novamente erros temporários da WhatsApp automaticamente. Os destinatários são processados individualmente, portanto um número inválido não bloqueia o resto do lote. Acompanhe o progresso da entrega no separador **Estatísticas** do modelo, na aplicação.

Como a entrega ocorre após a resposta, as retentativas precisam de ser seguras. Passe um cabeçalho `Idempotency-Key` (até 200 caracteres) que identifique unicamente cada lote:

```bash theme={null}
curl -X POST "https://api.flowella.io/v1/templates/send" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: campaign-2026-08-31-launch" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "recipients": [{ "phone": "+15551234567" }]
  }'
```

Repetições da mesma chave dentro de sete dias devolvem o `id` do trabalho original em vez de criar um novo envio. Pode retentar com segurança um pedido após um timeout ou erro de rede sem enviar mensagens para ninguém duas vezes.

Se omitir o cabeçalho, o Flowella deriva uma chave a partir do corpo do pedido. Um lote idêntico submetido duas vezes em rápida sucessão não é, portanto, enviado duas vezes. Uma chave explícita é ainda mais segura, porque qualquer alteração ao corpo (mesmo reordenar destinatários) produz uma nova chave derivada.

## Paginação

Os endpoints de listagem (`/conversations`, `/contacts`, `/templates`) usam **paginação por cursor**:

* Passe `limit` (1–100, predefinição 25) e um `cursor` opcional.
* A resposta contém `items` e, quando há mais resultados, um `nextCursor`.
* Passe `nextCursor` de volta como parâmetro `cursor` para obter a página seguinte.
* Quando `nextCursor` está ausente, chegou ao fim.

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

## Data e hora

Todos os timestamps são strings ISO 8601 em UTC (por exemplo `2025-01-15T14:30:00.000Z`). Onde a API aceita datas, tanto date-only (`2025-01-15`) como ISO 8601 completo são coagidos no servidor.

## Números de telefone

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

## Canais

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

Para o padrão de URL completo e a mudança de canal, consulte [Multicanal](/pt/essentials/multi-channel).

## Especificação OpenAPI

A especificação legível por máquina encontra-se em:

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

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

<Tip>
  A construir uma integração? Combine esta página com [Webhooks](/pt/api-reference/webhooks) para reagir a eventos em vez de fazer polling ao estado.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.