Conceptos principales
Marcas, suscriptores, consentimiento y los recursos disponibles actualmente en la API.
Fluyio organiza el producto en varios recursos. La API pública expone actualmente suscriptores y su consentimiento por canal; las demás funciones tienen su propia disponibilidad en el panel.
API v1 en beta
Las API de listas, eventos, campañas, flujos, plantillas, formularios, métricas y envío por WhatsApp están en desarrollo. Los webhooks salientes tampoco entregan eventos. Consulta la hoja de ruta.
Identificadores
Los IDs públicos usan un prefijo y 32 caracteres hexadecimales, correspondientes al UUID sin guiones. Por ejemplo, sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8 identifica un suscriptor.
| Prefijo | Recurso | Disponibilidad |
|---|---|---|
sub_ | Suscriptor | Recurso /v1/subscribers. |
lst_ | Lista | Solo IDs de lectura dentro del array lists. |
req_ | Petición | Cabecera Fluyio-Request-Id y errores. |
Las rutas de suscriptor también admiten el UUID con o sin guiones.
Marca
La marca, también llamada tenant en la API, delimita los contactos, dominios, equipo y claves. Cada clave pertenece a una marca. Para trabajar con otra marca, utiliza una credencial asociada a ella; no envías un ID de marca en la URL.
Suscriptor
{
"id": "sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8",
"object": "subscriber",
"email": "[email protected]",
"phone": "+34600000000",
"first_name": "Ada",
"last_name": "Lovelace",
"external_id": "user_12345",
"consent": {
"email": "subscribed",
"sms": "never_subscribed",
"whatsapp": "subscribed"
},
"properties": { "plan": "pro", "country": "ES" },
"lists": ["lst_0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f"],
"tags": ["vip"],
"created_at": "2026-05-11T14:32:08.421Z",
"updated_at": "2026-05-11T14:32:08.421Z",
"last_active_at": "2026-05-12T09:10:00.000Z"
}- Identidad: email o teléfono, más un
external_idopcional que corresponde al ID en tu sistema. - Propiedades: datos JSON para segmentación y personalización; el prefijo
__está reservado. - Listas y etiquetas: solo lectura desde la API actual.
- Actividad:
last_active_atrepresenta la última apertura o clic de email registrado.
Un email duplicado al crear en la misma marca devuelve 409 resource_already_exists.
Consentimiento
| Estado | Significado |
|---|---|
subscribed | Alta registrada en ese canal. |
unsubscribed | Baja o supresión registrada. |
never_subscribed | No hay alta para la identidad actual o falta esa identidad. |
El consentimiento es independiente para email, SMS y WhatsApp. Crear sin consentimiento de email explícito deja el estado pendiente y devuelve never_subscribed. Un cambio de email o teléfono no transfiere altas anteriores; las bajas y supresiones se conservan.
Usa subscribe y unsubscribe para cambios explícitos. El alta requiere identidad y consentimiento previamente obtenido. Un rebote, una queja o un bloqueo no se elimina mediante una nueva alta.
Listas y etiquetas
Una lista agrupa suscriptores; una etiqueta es un nombre para organizarlos. La API muestra pertenencias y etiquetas, pero su gestión se realiza en el panel.
Campañas, flujos, plantillas y formularios
Una campaña es un envío puntual; un flujo, una secuencia automática; una plantilla, contenido reutilizable; y un formulario, un punto de captación. Consulta su disponibilidad y configuración en el producto. No existen endpoints públicos para operarlos automáticamente.
Webhooks
Un webhook saliente sería una llamada HTTP desde Fluyio a tu servidor. La entrega está pendiente; disponer de configuración no acredita entrega de eventos. Consulta webhooks.
Claves y permisos
Una clave autoriza peticiones de su marca. Las rutas comprueban permisos de lectura o escritura. Las claves test devuelven 403 test_mode_unavailable; no existe un sandbox.
Recorrido de una integración
- Tu sistema crea o actualiza perfiles mediante POST y PATCH, y registra los cambios explícitos de consentimiento.
- El equipo utiliza las funciones disponibles en el panel.
- Tu integración consulta los perfiles para reconciliar cambios como bajas, etiquetas y actividad.
Consulta tu primera llamada, la referencia de suscriptores y la hoja de ruta.