> ## 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, errores, paginación y límites de tasa para la API REST v1 de Flowella, con consejos prácticos para empezar a integrar hoy mismo.
La API REST de Flowella te permite enviar mensajes de WhatsApp, gestionar contactos y exclusiones, crear listas y plantillas de envío masivo y obtener análisis mediante programación. Esta página cubre todo lo que necesitas saber antes de llamar a un punto final.
La referencia completa del punto final se encuentra en la barra lateral **Referencia API** (generada automáticamente a partir de la [especificación OpenAPI](/api-reference/openapi.json)).
## URL base
```
https://app.flowella.io
```
Todos los puntos finales v1 están bajo `/api/v1`.
## Autenticación
Cada petición necesita una clave API en la cabecera `Authorization`:
```http theme={null}
Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx
```
Las claves son de ámbito organizativo: actúan sobre una única organización Flowella y heredan los permisos de un administrador de esa organización.
Trata las claves como contraseñas. Nunca las confirmes en el control de código fuente, nunca las pegues en el chat o en documentos compartidos, y rótalas cuando los compañeros de equipo dejen la organización. Ver [Settings → API keys](/es/settings/api-keys) para los pasos de rotación.
### Creación de una clave
Necesitas el rol **Owner** o **Admin** para gestionar las claves API.
1. Vaya a **Configuración → Claves API** en la aplicación Flowella.
2. Haz clic en **Crear clave** y dale un nombre memorable.
3. Copia la clave una vez - sólo se muestra en el momento de la creación.
Trata las claves como contraseñas: nunca las envíes al control de código fuente, nunca las pegues en el chat y rótalas cuando tus compañeros de equipo dejen la organización.
### Verificación de una clave
Pulsa el punto final de ping para confirmar que una clave es válida:
```bash cURL theme={null}
curl https://app.flowella.io/api/v1/ping \
-H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"
```
```js Node.js theme={null}
await fetch("https://app.flowella.io/api/v1/ping", {
headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
});
```
```python Python theme={null}
import os, requests
requests.get(
"https://app.flowella.io/api/v1/ping",
headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
)
```
Un `200 OK` con `{ "ok": true, "organizationId": "…" }` significa que está autentificado.
## Errores
Todos los errores vuelven en un sobre consistente:
```json theme={null}
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}
```
| Estado HTTP | Cuándo lo verás | | |
| ----------------------------------------------- | ------------------------------------------------------------------------------- | ----- | --------------------------- |
| `400` | Validación fallida, cuerpo malformado, o rechazo de Meta upstream | | |
| `401` Falta la clave API o no es válida. | | | |
| `402` | Pago requerido - su suscripción no cubre la acción | `403` | |
| `403` | Prohibido - por ejemplo, envío a un contacto excluido, o Meta no está conectado | `404` | Falta la clave API inválida |
| `404` | El canal o recurso solicitado no existe | `429` | |
| `429` Velocidad limitada: reduzca la velocidad. | | | |
El campo `error.code` es estable y seguro de activar mediante programación. El campo `error.message` es legible y puede cambiar.
## Límites de velocidad
Las claves API están limitadas por organización. Si supera el límite, recibirá un `429` con el código `RATE_LIMITED` y el mensaje `Too many requests`. Retroceda y vuelva a intentarlo con un retardo exponencial.
Si está realizando envíos masivos de gran volumen, prefiera **`POST /api/v1/templates/send`** con el parámetro `throttlePerHour` - Flowella aplica el estrangulamiento en el servidor, por lo que no tendrá que controlar el ritmo de las solicitudes.
## Paginación
Los puntos finales de lista (`/conversations`, `/contacts`, `/templates`) utilizan **paginación por cursor**:
* Pasar `limit` (1-100, por defecto 25) y un `cursor` opcional.
* La respuesta contiene `items` y, cuando hay más resultados, un `nextCursor`.
* Devuelva `nextCursor` como parámetro `cursor` para obtener la página siguiente.
* Cuando falte `nextCursor`, habrá llegado al final.
```bash theme={null}
curl "https://app.flowella.io/api/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 la fecha (`2025-01-15`) como la ISO 8601 completa son forzadas por el servidor.
## Números de teléfono
Siempre que sea posible, introduzca los números de teléfono en formato **E.164** (`+15551234567`). Flowella normalizará las variaciones comunes en el servidor, pero E.164 es lo más seguro.
## Canales
Muchos endpoints aceptan un `whatsappChannelId`. Si tu org tiene un único canal y lo omites, Flowella utilizará tu canal por defecto. Si tienes varios canales, pasa el ID explícitamente para evitar enviar desde el remitente equivocado.
Para conocer el patrón de URL completo y el cambio de canal, consulte [Multicanal](/es/essentials/multi-channel).
## OpenAPI spec
La especificación legible por máquina se encuentra en:
```
/api-reference/openapi.json
```
Introdúcela en Postman, Insomnia o el generador de código que prefieras.
¿Estás construyendo una integración? Empareja esta página con [Webhooks](/es/api-reference/webhooks) para reaccionar a eventos en lugar de sondear el estado.