> ## 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. # Introducción a la API > Autenticación, URL base, códigos de error, paginación, límites de velocidad y claves de idempotencia para la API REST v1 de Flowella — todo lo que necesitas antes de tu primera llamada. La API REST de Flowella te permite enviar mensajes de WhatsApp, gestionar contactos y exclusiones, listar y enviar plantillas en masa, y obtener analíticas — todo programáticamente. Esta página cubre todo lo que necesitas saber antes de llamar a un endpoint. La referencia completa de endpoints se encuentra en la barra lateral **Referencia de la API** (autogenerada a partir de la [especificación OpenAPI](/api-reference/openapi.json)). ## URL base ``` https://api.flowella.io/v1 ``` Todos los endpoints v1 se encuentran bajo esta base canónica — por ejemplo `https://api.flowella.io/v1/messages`. La API antes vivía en el host de la aplicación en `https://app.flowella.io/api/v1/...`. Las solicitudes legadas a esa ruta se redirigen permanentemente (`308`) a la canónica `https://api.flowella.io/v1/...`, conservando el método y el cuerpo — por lo que las integraciones existentes siguen funcionando. Actualiza tu URL base cuando puedas para saltarte el salto adicional. ## Autenticación Cada solicitud necesita una clave de API en la cabecera `Authorization`: ```http theme={null} Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx ``` Las claves están limitadas a una organización — actúan en una única organización de Flowella y heredan los permisos de un administrador en esa organización. Trata las claves como contraseñas. Nunca las incluyas en el control de versiones, nunca las pegues en chats o documentos compartidos, y rótalas cuando algún compañero deje la organización. Consulta [Configuración → Claves de API](/es/settings/api-keys) para los pasos de rotación. ### Crear una clave Necesitas el rol de **Propietario** o **Administrador** para gestionar las claves de API. 1. Ve a **Configuración → Claves de API** en la aplicación de Flowella. 2. Haz clic en **Crear clave** y asígnale un nombre memorable. 3. Copia la clave una vez — solo se muestra en el momento de la creación. Trata las claves como contraseñas: nunca las incluyas en el control de versiones, nunca las pegues en chats y rótalas cuando algún compañero deje la organización. ### Verificar una clave Llama al endpoint de ping para confirmar que una clave es válida: ```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']}"}, ) ``` Un `200 OK` con `{ "ok": true, "organizationId": "…" }` significa que estás autenticado. ## Errores Todos los errores devuelven una envoltura consistente: ```json theme={null} { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" } } ``` | Estado HTTP | Cuándo lo verás | | - | - | | `400` | Falló la validación, cuerpo mal formado o rechazo de Meta upstream | | `401` | Clave de API faltante o inválida | | `402` | Pago requerido — tu suscripción no cubre la acción | | `403` | Prohibido — por ejemplo, enviar a un contacto excluido o Meta no está conectado | | `404` | El canal o recurso solicitado no existe | | `429` | Limitación de velocidad — reduce el ritmo | El campo `error.code` es estable y seguro para hacer switch programáticamente. El `error.message` es legible por humanos y puede cambiar. ## Límites de velocidad Las claves de API tienen límites de velocidad por organización. Si superas el límite, recibirás un `429` con el código `RATE_LIMITED` y el mensaje `Too many requests`. Cuando esté presente, la cabecera de respuesta `Retry-After` te indica cuántos segundos esperar. Retrocede y reintenta con retraso exponencial. Si estás ejecutando grandes envíos masivos, prefiere **`POST /v1/templates/send`** con el parámetro `throttlePerHour` — Flowella aplica el límite en el servidor, por lo que no necesitas marcar el ritmo de las solicitudes tú mismo. ## Claves de idempotencia Los envíos masivos de plantillas son asíncronos. `POST /v1/templates/send` valida la solicitud, la pone en cola de forma duradera y devuelve `202 Accepted` inmediatamente: ```json theme={null} { "id": "v1ts-0123456789abcdef", "status": "accepted" } ``` Flowella entrega el lote en segundo plano y reintenta automáticamente los errores temporales de WhatsApp. Los destinatarios se procesan individualmente, por lo que un número inválido no bloquea el resto del lote. Sigue el progreso de entrega en la pestaña **Estadísticas** de la plantilla en la aplicación. Como la entrega ocurre después de la respuesta, los reintentos deben ser seguros. Pasa una cabecera `Idempotency-Key` (hasta 200 caracteres) que identifique cada lote de forma única: ```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" }] }' ``` Las repeticiones de la misma clave dentro de siete días devuelven el `id` del trabajo original en lugar de crear un nuevo envío. Puedes reintentar una solicitud de forma segura después de un timeout o error de red sin enviar mensajes a nadie dos veces. Si omites la cabecera, Flowella deriva una clave del cuerpo de la solicitud. Un lote idéntico enviado dos veces en rápida sucesión no se envía por duplicado. Aun así, una clave explícita es más segura, porque cualquier cambio en el cuerpo (incluso reordenar los destinatarios) produce una clave derivada nueva. ## Paginación Los endpoints de listado (`/conversations`, `/contacts`, `/templates`) usan **paginación por cursor**: * Pasa `limit` (1–100, por defecto 25) y un `cursor` opcional. * La respuesta contiene `items` y, cuando hay más resultados, un `nextCursor`. * Pasa `nextCursor` como el parámetro `cursor` para obtener la siguiente página. * Cuando falta `nextCursor`, has llegado al final. ```bash theme={null} curl "https://api.flowella.io/v1/conversations?limit=50" \ -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx" ``` ## Fecha y hora Todas las marcas de tiempo son cadenas ISO 8601 en UTC (por ejemplo `2025-01-15T14:30:00.000Z`). Cuando la API acepta fechas, tanto solo fecha (`2025-01-15`) como ISO 8601 completo se coercionan en el servidor. ## Números de teléfono Pasa los números de teléfono en formato **E.164** (`+15551234567`) siempre que sea posible. Flowella normaliza variaciones comunes en el servidor, pero E.164 es lo más seguro. ## Canales Muchos endpoints aceptan un `whatsappChannelId`. Si tu organización tiene un solo canal y lo omites, Flowella usa tu canal por defecto. Si tienes varios canales, pasa el ID explícitamente para evitar enviar desde el remitente equivocado. Para el patrón de URL completo y el cambio de canal, consulta [Multi-canal](/es/essentials/multi-channel). ## Especificación OpenAPI La especificación legible por máquinas se encuentra en: ``` /api-reference/openapi.json ``` Súbela a Postman, Insomnia o tu generador de código preferido. ¿Construyendo una integración? Combina esta página con [Webhooks](/es/api-reference/webhooks) para reaccionar a eventos en lugar de sondear el estado. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.