API REST: autenticación, scopes, límites y errores

URL base

https://api.flowella.io/v1

Autenticación

Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Comprobar tus credenciales

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())

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

Scopes

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

Errores

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

Límites de velocidad

IDs de solicitud

Idempotencia

La mayoría de las solicitudes de escritura

• La clave debe tener entre 8 y 255 caracteres. Otras longitudes devuelven 400.
• Flowella recuerda cada clave de tu organización durante 24 horas.
• Una repetición con la misma clave, método, ruta y cuerpo devuelve la respuesta almacenada sin volver a ejecutar la solicitud.
• Una repetición con la misma clave pero con otro método, ruta o cuerpo devuelve 409 IDEMPOTENCY_KEY_CONFLICT.
• Una repetición enviada mientras la primera solicitud aún se está ejecutando devuelve 409 IDEMPOTENCY_KEY_IN_FLIGHT. Espera y vuelve a intentarlo.
• Las respuestas devuelven la clave en una cabecera Idempotency-Key.

Envíos masivos de plantillas

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

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" }]
  }'

• La clave puede tener hasta 200 caracteres. Una clave más larga devuelve 400.
• Una repetición con la misma clave en un plazo de 7 días devuelve el id original y no envía nada, aunque el cuerpo haya cambiado.
• Sin la cabecera, Flowella usa un hash del cuerpo de la solicitud como clave. Si vuelves a enviar un cuerpo idéntico byte a byte en un plazo de 7 días, recibes el id original y no se envía nada. Usa una clave nueva para cada lote que quieras enviar.

• Llámalo con una clave de API. Los tokens de acceso OAuth se rechazan con 401.
• Sus respuestas no incluyen las cabeceras X-Request-Id, API-Version ni X-RateLimit-*. Sus solicitudes siguen contando para el límite de velocidad de la clave.

Versionado

API-Version: 2026-08-11

Sandbox

• Una clave de sandbox, que solo afecta a las solicitudes hechas con esa clave. Consulta Claves de sandbox.
• El API sandbox de toda la organización en el Developer hub, que un Owner o Admin puede activar. Consulta API sandbox.

Paginación

• Pasa limit (de 1 a 100, 25 por defecto) y un cursor opcional.
• La respuesta contiene items y, cuando hay más resultados, un nextCursor.
• Devuelve nextCursor como parámetro cursor para obtener la página siguiente.
• Cuando nextCursor falta o es null, has llegado al final.

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

Fecha y hora

Números de teléfono

Canales

Especificación OpenAPI

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

Recursos para desarrolladores