Fluyio Developers

Crea una clave API, da de alta un suscriptor con consentimiento y consulta tu audiencia.

API v1 en beta

La API pública expone suscriptores. El resto de recursos sigue en desarrollo; consulta la hoja de ruta.

Esta guía recorre la creación de una clave, un suscriptor mediante POST /v1/subscribers y una consulta paginada reutilizable.

Antes de empezar

Necesitas una cuenta de Fluyio con una marca y una terminal con cURL, Node.js 18+, Python 3.9+ o PHP 8.1+. No hay SDKs oficiales; la API utiliza JSON sobre HTTPS.

Crea una clave API

Abre Claves API en el panel y crea una clave para la marca que vas a utilizar.

Nombre: quickstart.
Modo: live.
Permisos: subscribers:read y subscribers:write; utiliza full solo si necesitas todos los permisos.

La clave completa se muestra una vez. El formato es fly_live_ seguido de 48 caracteres hexadecimales; el panel conserva un prefijo de 15 caracteres para identificarla.

No existe un sandbox aislado. Las claves test se rechazan con 403 test_mode_unavailable. Usa una marca y contactos aislados para esta prueba, con una clave live dedicada. Protege la clave como una contraseña: no la publiques en código del navegador, repositorios ni capturas; revócala si se expone.

Guarda la clave en el entorno

export FLUYIO_API_KEY="fly_live_..."

Cada petición la envía en Authorization: Bearer …. Aunque Fluyio-Version es opcional con la única versión actual 2026-05-15, enviarla de forma explícita fija el contrato de la integración.

Crea un suscriptor

El ejemplo registra un consentimiento de email ya obtenido. Omitir consent.email o enviar never_subscribed conserva el estado pendiente y devuelve never_subscribed; no da de alta automáticamente a la persona.

curl -X POST https://fluyio.com/api/v1/subscribers \
  -H "Authorization: Bearer $FLUYIO_API_KEY" \
  -H "Fluyio-Version: 2026-05-15" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-ada-0001" \
  -d '{
    "email": "[email protected]",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "external_id": "user_12345",
    "consent": { "email": "subscribed" },
    "properties": { "company": "Analytical Engines", "plan": "pro" }
  }'

Respuesta: `201 Created`

{
  "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": { "company": "Analytical Engines", "plan": "pro" },
  "lists": [],
  "tags": [],
  "created_at": "2026-05-11T14:32:08.421Z",
  "updated_at": "2026-05-11T14:32:08.421Z",
  "last_active_at": null
}

Encontrarás a Ada en los suscriptores de la marca. Guarda su id para las operaciones posteriores.

Reutiliza la misma Idempotency-Key y el mismo cuerpo para una operación. Una respuesta completada se reproduce durante 24 horas. Si una operación ya reservada devuelve un 5xx o tiene resultado incierto, la clave permanece reservada 24 horas y no reejecuta automáticamente la escritura. Revisa el estado antes de iniciar otra operación con una clave distinta. Consulta idempotencia.

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.

Consulta los suscriptores

curl -g "https://fluyio.com/api/v1/subscribers?limit=25&filter[has_consent]=email" \
  -H "Authorization: Bearer $FLUYIO_API_KEY" \
  -H "Fluyio-Version: 2026-05-15"

La respuesta incluye has_more y next_cursor. Envía este último como cursor para la siguiente página. Conserva filtros y orden durante el recorrido; consulta paginación.

Cambia el consentimiento

El consentimiento se gestiona por canal mediante operaciones explícitas. Este ejemplo da de baja el email:

# Opt Ada out of email
curl -X POST https://fluyio.com/api/v1/subscribers/sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8/unsubscribe \
  -H "Authorization: Bearer $FLUYIO_API_KEY" \
  -H "Fluyio-Version: 2026-05-15" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "email" }'

Para un alta con consentimiento nuevo utiliza subscribe. SMS y WhatsApp requieren teléfono; WhatsApp exige E.164. Las supresiones por rebote, queja o bloqueo no se eliminan con una nueva llamada de alta.

Errores frecuentes

401 missing_api_key o invalid_api_key: revisa la cabecera, la caducidad y la revocación.
403 missing_scope: la clave no tiene el permiso de lectura o escritura necesario.
403 test_mode_unavailable: utiliza una clave live dedicada; no hay sandbox.
400 unknown_version: usa 2026-05-15 u omite la cabecera.
409 resource_already_exists: localiza el email con filter[email] y usa PATCH.
403 profile_limit: revisa el límite de perfiles aplicable antes de continuar.
429 rate_limit_exceeded: respeta Retry-After. Los límites por clave son 150 peticiones cada 10 segundos y 600 por minuto.

Inicio rápido