Saltar para o conteúdo principal
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).

​
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: 
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.
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 para os passos de rotação.

​
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: 
curl https://app.flowella.io/api/v1/ping \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
Um 200 OK com { "ok": true, "organizationId": "…" } significa que está autenticado.

​
Erros

Todos os erros são devolvidos num envelope consistente: 
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
Status HTTPQuando você o verá
400Falha na validação, corpo malformado ou rejeição Meta do upstream
401Chave de API em falta ou inválida
402Pagamento necessário - a sua subscrição não cobre a ação
403Proibido - por exemplo, enviar para um contacto excluído, ou o Meta não está ligado
404O canal ou recurso solicitado não existe
429Taxa 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.
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.

​
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.
Construindo uma integração? Emparelhe esta página com Webhooks para reagir a eventos em vez de sondar o estado.