Fluyio Developers

Recorre el ciclo del suscriptor: crear, consultar, actualizar, registrar consentimiento, filtrar y eliminar.

Este recorrido muestra los endpoints publicados en el orden habitual de una integración. Usa datos de prueba aislados y una clave con subscribers:read y subscribers:write.

Crea una clave live y guárdala en FLUYIO_API_KEY, como indica el inicio rápido. Las claves test devuelven 403 test_mode_unavailable; no proporcionan un entorno aislado. Las llamadas de esta guía modifican la marca asociada a tu clave.

El recorrido

1. POST   /v1/subscribers                     create Ada
2. GET    /v1/subscribers/:id                 read her back
3. PATCH  /v1/subscribers/:id                 add a phone number and properties
4. POST   /v1/subscribers/:id/subscribe       opt her into SMS
5. GET    /v1/subscribers?filter[external_id] find her by your own id
6. POST   /v1/subscribers/:id/unsubscribe     opt her out of every channel
7. DELETE /v1/subscribers/:id                 remove her

Los ejemplos usan https://fluyio.com/api/v1, Authorization: Bearer $FLUYIO_API_KEY y Fluyio-Version: 2026-05-15.

1. Crea el suscriptor

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: first-call-ada-0001" \
  -d '{
    "email": "[email protected]",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "external_id": "user_42",
    "consent": { "email": "subscribed" },
    "properties": { "plan": "trial", "signup_source": "docs" }
  }'

Respuesta: `201 Created`

{
  "id": "sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8",
  "object": "subscriber",
  "email": "[email protected]",
  "phone": null,
  "first_name": "Ada",
  "last_name": "Lovelace",
  "external_id": "user_42",
  "consent": { "email": "subscribed", "sms": "never_subscribed", "whatsapp": "never_subscribed" },
  "properties": { "plan": "trial", "signup_source": "docs" },
  "lists": [],
  "tags": [],
  "created_at": "2026-05-11T14:32:08.421Z",
  "updated_at": "2026-05-11T14:32:08.421Z",
  "last_active_at": null
}

Guarda el ID devuelto junto al usuario correspondiente en tu base. El alta de email requiere consent.email: subscribed explícito y consentimiento previamente obtenido. Sin él, la API devuelve never_subscribed.

La misma clave y cuerpo reproducen una respuesta completada durante 24 horas con Idempotency-Replayed: true. Si una operación ya reservada tiene un 5xx o resultado incierto, conserva la reserva de idempotencia durante 24 horas; no reejecuta automáticamente la operación.

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.

2. Consulta el registro

curl https://fluyio.com/api/v1/subscribers/sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8 \
  -H "Authorization: Bearer $FLUYIO_API_KEY" \
  -H "Fluyio-Version: 2026-05-15"

Devuelve el objeto con 200 OK. Un ID desconocido da 404 resource_not_found; uno mal formado, 400 invalid_param.

3. Actualiza el perfil

PATCH solo modifica los campos enviados. properties se combina clave por clave. Las propiedades con prefijo __ están reservadas.

curl -X PATCH https://fluyio.com/api/v1/subscribers/sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8 \
  -H "Authorization: Bearer $FLUYIO_API_KEY" \
  -H "Fluyio-Version: 2026-05-15" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+34600000000",
    "properties": { "plan": "pro" }
  }'

El ejemplo añade phone y deja properties en { "plan": "pro", "signup_source": "docs" }. No permite cambiar consentimiento, listas ni etiquetas. Cambiar una dirección o un número tampoco traslada su consentimiento al nuevo identificador; las bajas y supresiones se conservan.

4. Registra consentimiento

Con un teléfono y consentimiento SMS previamente obtenido, registra el alta:

curl -X POST https://fluyio.com/api/v1/subscribers/sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8/subscribe \
  -H "Authorization: Bearer $FLUYIO_API_KEY" \
  -H "Fluyio-Version: 2026-05-15" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "sms", "source": "api" }'

consent.sms queda subscribed. Si falta la identidad que necesita el canal se devuelve 422 missing_required_field. Las supresiones por rebote, queja o bloqueo devuelven 409 channel_unavailable al intentar una nueva alta.

5. Localiza el perfil con filtros

Si solo conoces el ID de tu sistema, usa filter[external_id] para una coincidencia exacta. Los filtros se combinan con AND.

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

{
  "object": "list",
  "data": [ { "id": "sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8", "object": "subscriber", "email": "[email protected]", "...": "..." } ],
  "has_more": false,
  "next_cursor": null
}

También existen filter[email], filter[created_at_gte], filter[created_at_lte] y filter[has_consent] para email, SMS o WhatsApp. Consulta paginación.

6. Retira el consentimiento de todos los canales

Cuando la decisión de la persona implique dar de baja todos los canales, utiliza channel: "all":

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": "all", "reason": "user_request" }'

Se registran las bajas, incluida consent.sms: unsubscribed. Una operación de baja no elimina una supresión por rebote, queja o bloqueo. Repetir la misma baja conserva ese estado.

7. Elimina el registro

curl -X DELETE https://fluyio.com/api/v1/subscribers/sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8 \
  -H "Authorization: Bearer $FLUYIO_API_KEY" \
  -H "Fluyio-Version: 2026-05-15"

Respuesta: `200 OK`

{ "id": "sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8", "object": "subscriber", "deleted": true }

Un GET posterior devuelve 404 resource_not_found. Si solo necesitas detener mensajes, conserva el registro con unsubscribe; DELETE elimina el suscriptor. Revisa también los datos que mantengas en otros sistemas.

Resultado

Has recorrido la superficie pública de suscriptores. Listas, campañas, flujos y formularios todavía no tienen endpoints públicos; consulta la hoja de ruta antes de integrarlos.

Si algo falla

409 resource_already_exists al crear: busca el email y actualiza el perfil existente.
403 profile_limit: la creación supera el límite de perfiles aplicable.
403 missing_scope: falta el permiso de la operación.
422 missing_required_field: añade la identidad requerida antes de registrar consentimiento.
400 invalid_cursor: reinicia la paginación con parámetros coherentes.

Tu primera llamada completa