Visión general de la API
URL base, cabeceras, métodos y recursos de la API REST v1.
API v1 en beta
Actualmente está publicado el recurso de suscriptores. Los demás recursos siguen en desarrollo: consulta la hoja de ruta.
La API utiliza métodos HTTP, cuerpos JSON y estados HTTP. Cada petición corresponde a la marca de la clave; no se pasa un ID de marca en la URL.
URL base
https://fluyio.com/api/v1En esta documentación, /v1/subscribers corresponde a https://fluyio.com/api/v1/subscribers.
Métodos
| Método | Uso |
|---|---|
| GET | Leer un recurso o listado. |
| POST | Crear un suscriptor o ejecutar una acción. |
| PATCH | Actualizar solo los campos enviados. |
| DELETE | Eliminar un recurso, con confirmación 200 OK. |
Los cuerpos usan Content-Type: application/json. Los campos desconocidos se rechazan con 400 invalid_param.
Cabeceras de petición
| Cabecera | Requisito | Descripción |
|---|---|---|
Authorization | Obligatoria | Bearer fly_live_…; consulta autenticación. |
Fluyio-Version | Recomendada | Fija 2026-05-15, también predeterminada actualmente. |
Content-Type | Con cuerpo | application/json. |
Idempotency-Key | Recomendada en escrituras | De 8 a 128 caracteres A-Z a-z 0-9 _ -, estable por operación. |
GET requiere subscribers:read y las escrituras subscribers:write, o permisos globales que incluyan esa acción. La ausencia de permiso devuelve 403 missing_scope.
Cabeceras de respuesta
| Cabecera | Descripción |
|---|---|
Fluyio-Request-Id | ID único de petición para diagnóstico. |
Fluyio-Version | Versión que procesó la petición. |
Fluyio-Mode | Modo de la clave; las test se rechazan sin acceder a datos. |
Ratelimit-Limit, Ratelimit-Remaining, Ratelimit-Reset, Ratelimit-Policy | Estado de los límites por clave, también con alias X-RateLimit-*. |
Retry-After | Segundos de espera ante un 429. |
Idempotency-Replayed | true cuando se reproduce una respuesta completada. |
Primera consulta
Este ejemplo solicita los 25 suscriptores más recientes de la marca.
curl "https://fluyio.com/api/v1/subscribers?limit=25" \
-H "Authorization: Bearer $FLUYIO_API_KEY" \
-H "Fluyio-Version: 2026-05-15"Respuesta
{
"object": "list",
"data": [
{
"id": "sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8",
"object": "subscriber",
"email": "[email protected]",
"phone": null,
"first_name": "Ada",
"last_name": "Lovelace",
"external_id": "user_12345",
"consent": { "email": "subscribed", "sms": "never_subscribed", "whatsapp": "never_subscribed" },
"properties": { "plan": "pro" },
"lists": [],
"tags": [],
"created_at": "2026-05-11T14:32:08.421Z",
"updated_at": "2026-05-11T14:32:08.421Z",
"last_active_at": null
}
],
"has_more": true,
"next_cursor": "MjAyNi0wNS0xMVQxNDozMjowOC40MjFafDlmMWMyYjNhLTRkNWUtNmY3MC04MTkyLWEzYjRjNWQ2ZTdmOA"
}Identificadores
Los IDs combinan un prefijo y 32 caracteres hexadecimales. sub_ identifica suscriptores, lst_ las listas expuestas en modo lectura y req_ las peticiones. Las rutas de suscriptor también admiten UUID con o sin guiones.
Recursos y herramientas
Consulta la referencia de suscriptores. No hay SDKs oficiales, especificación OpenAPI ni colección Postman publicada; puedes usar HTTP y cURL. El MCP es experimental y su recorrido completo contra backend no está validado.
Modo test
Las claves test devuelven 403 test_mode_unavailable. No leen ni escriben datos de la marca y no ofrecen un sandbox. Para probar, usa una marca, datos y clave live dedicados.
Escrituras inciertas
Si una operación ya reservada con Idempotency-Key devuelve un 5xx o tiene resultado incierto, mantiene la reserva 24 horas y no reejecuta automáticamente la escritura. Consulta idempotencia antes de diseñar los reintentos.
Un 503 idempotency_unavailable indica que no se inició la operación; no garantiza una reserva creada. Reintenta la misma operación con la misma clave, sin generar otra para eludir la protección.