API REST do Flowella: autenticação, âmbitos, limites e erros

A API REST do Flowella permite-lhe enviar mensagens WhatsApp, gerir contactos e opt-outs, trabalhar com modelos e Flows e ler análises a partir do seu próprio código. Esta página aborda o que precisa de saber antes de chamar um endpoint. A secção Endpoints desta referência da API documenta os pedidos individuais. Para a lista completa e atual, use o documento OpenAPI em tempo real ou a documentação interativa da API na aplicação.

URL base

https://api.flowella.io/v1

Todos os endpoints estão sob esta base, por exemplo https://api.flowella.io/v1/messages. Use-a mesmo quando a aplicação mostra um endereço terminado em /api/v1, como API base URL no Developer hub.

Os pedidos para o anfitrião da aplicação, https://app.flowella.io/api/v1/..., são redirecionados permanentemente (308) para https://api.flowella.io/v1/.... Muitos clientes HTTP descartam o cabeçalho Authorization quando seguem um redirecionamento para outro anfitrião, por isso o pedido redirecionado pode falhar com 401. Chame diretamente https://api.flowella.io/v1.

Autenticação

Envie um bearer token no cabeçalho Authorization de cada pedido:

Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

O Flowella aceita dois tipos de token. Ambos atuam apenas sobre uma organização.

Token	Começa por	De onde vem	Âmbitos	Expiração
Chave de API	`flo_`	Settings → API keys, criada por um Owner ou Admin. Consulte Chaves de API.	Todos os âmbitos	Nenhuma. Funciona até ser revogada.
Token de acesso OAuth	`fla_`	Uma aplicação OAuth registada em Settings → Developer apps. Consulte Registar uma aplicação de parceiro com OAuth.	Apenas os âmbitos concedidos quando a aplicação foi autorizada	1 hora. Peça um novo token quando expirar.

Use uma chave de API para os seus próprios scripts e integrações. Use uma aplicação OAuth quando outras organizações Flowella instalam a sua integração.

Trate as chaves e os tokens como palavras-passe. Nunca os inclua no controlo de versões nem os cole em chats ou documentos partilhados. Revogue uma chave de que já não precisa em Chaves de API.

Verificar as suas credenciais

Chame o endpoint ping para confirmar que uma chave ou token funciona:

curl https://api.flowella.io/v1/ping \
  -H "Authorization: Bearer $FLOWELLA_API_KEY"

const res = await fetch("https://api.flowella.io/v1/ping", {
  headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
});
console.log(await res.json());

import os
import requests

res = requests.get(
    "https://api.flowella.io/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
)
print(res.json())

Uma resposta 200 OK significa que está autenticado. organizationId é o ID numérico da sua organização:

{
  "ok": true,
  "organizationId": 4821
}

Uma resposta 401 tem o código UNAUTHORIZED e uma destas mensagens: Missing bearer token, Invalid or expired API key, Invalid or expired access token ou Unsupported bearer token.

Âmbitos

Cada endpoint precisa de um âmbito. As chaves de API criadas na aplicação têm todos os âmbitos. Os tokens de acesso OAuth têm apenas os âmbitos concedidos na autorização.

Âmbito	Permite
`messages:read`	Ler mensagens.
`messages:write`	Enviar mensagens com `POST /v1/messages`.
`contacts:read`	Ler contactos e opt-outs.
`contacts:write`	Criar, atualizar e eliminar contactos, upserts em massa e registar opt-outs.
`conversations:read`	Ler conversas e canais WhatsApp.
`conversations:write`	Atualizar, fechar e reabrir conversas.
`templates:read`	Ler modelos e o respetivo estado de aprovação.
`templates:write`	Criar, editar, submeter e eliminar modelos, envios de teste e envios em massa com `POST /v1/templates/send`.
`webhooks:manage`	Gerir webhooks, entregas, repetições e segredos de assinatura.
`analytics:read`	Ler análises e utilização.
`account:read`	Ler capacidades, estado das integrações e detalhes dos pedidos.
`flows:read`	Ler Flows e o respetivo estado de sincronização.
`flows:write`	Criar, editar, publicar e eliminar Flows e configurar fornecedores de formulários.
`forms:ingest`	Enviar e ler submissões de formulários, incluindo webhooks de formulários recebidos.
`events:read`	Ler o feed de eventos com `GET /v1/events`.
`jobs:read`	Ler tarefas em segundo plano e os respetivos resultados.
`jobs:write`	Cancelar tarefas em segundo plano.
`sandbox:manage`	Ler e alterar a definição de sandbox e usar as ferramentas de teste da sandbox.

GET /v1/ping e GET /v1/rate-limits não precisam de âmbito. GET /v1/capabilities (âmbito account:read) lista os âmbitos que o seu token tem. Um pedido sem o âmbito necessário devolve 403 com o código INSUFFICIENT_SCOPE. details.required lista os âmbitos em falta:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Token is missing required scope(s)",
    "requestId": "req_5b1e0c2a-8f3d-4e6a-9c7b-2d4f6a8e0b1c",
    "details": { "required": ["webhooks:manage"] }
  }
}

Erros

Os erros usam o mesmo envelope. requestId identifica o pedido quando contacta o suporte, e details contém informação adicional, como problemas de validação, quando existe:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

Estado HTTP	`error.code`	Quando o vê
`400`	`BAD_REQUEST`	O pedido falhou a validação, a `API-Version` não é suportada ou a `Idempotency-Key` tem o comprimento errado.
`400`	`META_ERROR`	A Meta rejeitou o pedido.
`400`	`INVALID_TEMPLATE_NAME`, `INVALID_TEMPLATE_COMPONENTS`	O nome ou os componentes do modelo não são válidos.
`401`	`UNAUTHORIZED`	O bearer token está em falta, é inválido, foi revogado ou expirou.
`402`	`PAYMENT_REQUIRED`	O pagamento da sua subscrição está em atraso.
`403`	`INSUFFICIENT_SCOPE`	O seu token não tem um âmbito de que o endpoint precisa.
`403`	`FORBIDDEN`	A ação não é permitida, por exemplo enviar para um contacto que fez opt-out nesse número, ou a sua subscrição não está ativa.
`404`	`NOT_FOUND`	O recurso não existe na sua organização.
`409`	`CONFLICT`, `IDEMPOTENCY_KEY_CONFLICT`, `IDEMPOTENCY_KEY_IN_FLIGHT`	Um valor duplicado, como um `externalId`, ou um conflito de chave de idempotência.
`429`	`RATE_LIMITED`	Enviou demasiados pedidos. Consulte Limites de taxa.
`500`	`INTERNAL_ERROR`, `INTERNAL_SERVER_ERROR`	Algo correu mal do lado do Flowella. Tente novamente mais tarde e indique o `requestId` ao suporte.

O valor error.code é estável, por isso o seu código pode depender dele. O texto error.message destina-se a pessoas e pode mudar.

Limites de taxa

Cada chave de API e cada token de acesso OAuth tem o seu próprio limite de pedidos por minuto. O Flowella conta os pedidos em janelas fixas de um minuto que começam no início de cada minuto (UTC). As respostas a pedidos que passam as verificações de autenticação e de âmbito incluem estes cabeçalhos:

Cabeçalho	Significado
`X-RateLimit-Limit`	Pedidos permitidos em cada janela.
`X-RateLimit-Remaining`	Pedidos restantes na janela atual.
`X-RateLimit-Reset`	Quando termina a janela atual, em segundos Unix.

Quando ultrapassa o limite, o Flowella devolve 429 com o código RATE_LIMITED e um cabeçalho Retry-After com o número de segundos a aguardar. GET /v1/rate-limits devolve os seus valores limit, remaining e reset em JSON. Para envios grandes, use POST /v1/templates/send, que aceita até 50.000 destinatários num único pedido. O pedido também aceita um campo opcional throttlePerHour, um número inteiro de 1 a 100.000, mas de momento não controla o ritmo dos envios, por isso não dependa dele. Para distribuir um envio grande ao longo do tempo, divida a lista de destinatários em lotes mais pequenos e envie cada lote separadamente.

IDs de pedido

As respostas incluem um cabeçalho X-Request-Id, e os corpos de erro repetem-no como error.requestId. POST /v1/templates/send é a exceção: consulte Envios de modelos em massa. Para usar o seu próprio ID, envie um cabeçalho X-Request-Id com até 128 caracteres e o Flowella reutiliza-o. Indique o ID do pedido quando contactar o suporte. Para consultar um pedido por si próprio, chame GET /v1/requests/{requestId} (âmbito account:read): devolve o pedido registado com os eventos, tarefas e entregas de webhook associados. O Developer hub lista os seus pedidos recentes e os respetivos IDs.

Idempotência

As chaves de idempotência permitem-lhe repetir um pedido de escrita após um tempo limite ou um erro de rede sem fazer o trabalho duas vezes. POST /v1/templates/send segue regras próprias, descritas abaixo.

A maioria dos pedidos de escrita

Os pedidos POST, PATCH, PUT e DELETE aceitam um cabeçalho opcional Idempotency-Key:

A chave tem de ter entre 8 e 255 caracteres. Outros comprimentos devolvem 400.
O Flowella memoriza cada chave da sua organização durante 24 horas.
Uma repetição com a mesma chave, método, caminho e corpo devolve a resposta guardada sem executar novamente o pedido.
Uma repetição com a mesma chave, mas um método, caminho ou corpo diferente, devolve 409 IDEMPOTENCY_KEY_CONFLICT.
Uma repetição enviada enquanto o primeiro pedido ainda está em execução devolve 409 IDEMPOTENCY_KEY_IN_FLIGHT. Aguarde e tente novamente.
As respostas repetem a chave num cabeçalho Idempotency-Key.

Os pedidos sem o cabeçalho são executados normalmente, sem proteção contra duplicados.

Envios de modelos em massa

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

{
  "id": "v1ts-0123456789abcdef",
  "status": "accepted"
}

O Flowella entrega o lote em segundo plano e repete automaticamente os erros temporários do WhatsApp. Os destinatários são processados individualmente, por isso um número inválido não bloqueia o resto do lote. Acompanhe o progresso da entrega no separador Statistics do modelo na aplicação. Passe um cabeçalho Idempotency-Key que identifique cada lote:

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

Este endpoint trata as chaves de forma diferente dos outros pedidos de escrita:

A chave pode ter até 200 caracteres. Uma chave mais longa devolve 400.
Uma repetição com a mesma chave dentro de 7 dias devolve o id original e não envia nada, mesmo que o corpo tenha mudado.
Sem o cabeçalho, o Flowella usa um hash do corpo do pedido como chave. Se voltar a enviar um corpo idêntico byte a byte dentro de 7 dias, recebe de volta o id original e nada é enviado. Use uma nova chave para cada lote que pretende enviar.

Há outros comportamentos que também diferem neste endpoint:

Chame-o com uma chave de API. Os tokens de acesso OAuth são recusados com 401.
As suas respostas não incluem os cabeçalhos X-Request-Id, API-Version ou X-RateLimit-*. Os seus pedidos continuam a contar para o limite de taxa da chave.

Versionamento

Pode fixar a versão da API com o cabeçalho API-Version:

API-Version: 2026-08-11

2026-08-11 é a única versão suportada e a predefinição quando omite o cabeçalho. Qualquer outro valor, ou um valor que não seja uma data YYYY-MM-DD, devolve 400 com a mensagem Unsupported API-Version. As respostas repetem a versão nos cabeçalhos API-Version e X-Flowella-Api-Version.

Sandbox

A sandbox permite-lhe testar uma integração sem enviar nada para o WhatsApp. Funciona na sua organização real: não existe uma conta de teste separada. Pode usá-la de duas formas:

Uma chave de sandbox, que afeta apenas os pedidos feitos com essa chave. Consulte Chaves de sandbox.
A API sandbox ao nível da organização no Developer hub, que um Owner ou Admin pode ativar. Consulte API sandbox.

Enquanto a sandbox se aplica, POST /v1/messages guarda a mensagem e devolve "sandbox": true sem contactar a Meta, e a submissão de modelos devolve uma decisão simulada instantânea. As ferramentas de teste da sandbox em /v1/test/ e /v1/sandbox precisam do âmbito sandbox:manage.

Paginação

Os endpoints de listagem, como /v1/conversations, /v1/contacts e /v1/templates, usam paginação por cursor:

Passe limit (1 a 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á em falta ou é null, chegou ao fim.

curl "https://api.flowella.io/v1/conversations?limit=50" \
  -H "Authorization: Bearer $FLOWELLA_API_KEY"

Data e hora

Todos os carimbos de data/hora são strings ISO 8601 em UTC, por exemplo 2025-01-15T14:30:00.000Z. Quando a API aceita datas, funcionam tanto valores só com data (2025-01-15) como valores ISO 8601 completos.

Números de telefone

Passe os números de telefone no formato E.164 (+15551234567) sempre que possível. O Flowella normaliza as variações comuns, mas o 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 vários canais, passe o ID explicitamente para não enviar a partir do número errado. Para o padrão de URL completo e a troca de canal, consulte Multicanal.

Especificação OpenAPI

A especificação em tempo real, legível por máquina, é pública:

https://api.flowella.io/v1/openapi.json

Importe-a para o Postman, o Insomnia ou um gerador de código. Descreve a autenticação por chave de API e por OAuth.

Recursos para programadores

A aplicação tem mais material para programadores. Estas páginas são públicas, por isso pode abri-las sem iniciar sessão:

Recurso	Endereço
Documentação interativa da API, com pedidos de teste	`https://app.flowella.io/docs`
Coleção Postman (descarrega um ficheiro `.json`)	`https://app.flowella.io/docs/postman`
Guia da sandbox	`https://app.flowella.io/docs/sandbox`
Guias de início rápido em Markdown para Salesforce, Zoho CRM, SurveyMonkey, Typeform e n8n	`https://app.flowella.io/docs/quickstarts/salesforce`, com `zoho`, `surveymonkey`, `typeform` ou `n8n` em vez de `salesforce`

O Developer hub em Settings reúne estes links com os seus pedidos de API recentes e o interruptor da API sandbox.

Combine esta página com a referência de webhooks para reagir a eventos em vez de consultar periodicamente as alterações.

Primeiros passos

Essenciais

Usar a aplicação

Definições

Configuração Meta e WhatsApp

Integração HubSpot

Flows e campanhas

Referência da API

Resolução de problemas

Registro de alterações

API REST do Flowella: autenticação, âmbitos, limites e erros

URL base

Autenticação

Verificar as suas credenciais

Âmbitos

Erros

Limites de taxa

IDs de pedido

Idempotência

A maioria dos pedidos de escrita

Envios de modelos em massa

Versionamento

Sandbox

Paginação

Data e hora

Números de telefone

Canais

Especificação OpenAPI

Recursos para programadores

​URL base

​Autenticação

​Verificar as suas credenciais

​Âmbitos

​Erros

​Limites de taxa

​IDs de pedido

​Idempotência

​A maioria dos pedidos de escrita

​Envios de modelos em massa

​Versionamento

​Sandbox

​Paginação

​Data e hora

​Números de telefone

​Canais

​Especificação OpenAPI

​Recursos para programadores

URL base

Autenticação

Verificar as suas credenciais

Âmbitos

Erros

Limites de taxa

IDs de pedido

Idempotência

A maioria dos pedidos de escrita

Envios de modelos em massa

Versionamento

Sandbox

Paginação

Data e hora

Números de telefone

Canais

Especificação OpenAPI

Recursos para programadores