Dar de alta en un canal
Registra consentimiento explícito para email, SMS o WhatsApp.
POST /v1/subscribers/:id/subscribe
Requiere el permiso subscribers:write o full. Los permisos se comprueban en el servidor. Las claves test se rechazan con 403 test_mode_unavailable; no existe un sandbox aislado.
Registra el consentimiento obtenido del suscriptor para un canal y devuelve el objeto actualizado. Requiere email para email y phone para SMS o WhatsApp.
Esta operación registra consentimiento que ya has obtenido; no envía una confirmación. source: "double_opt_in" describe el origen, pero no inicia un proceso de doble confirmación. Una supresión por rebote, queja o bloqueo no se elimina con una nueva alta: se devuelve 409 channel_unavailable.
Parámetro de ruta
id es el identificador sub_… del suscriptor. También se admite el UUID sin prefijo, con o sin guiones. Cualquier otro formato devuelve 400 invalid_param.
Cuerpo de la petición
Los campos desconocidos se rechazan con 400 invalid_param.
| Campo | Tipo | Descripción |
|---|---|---|
channel | string | Obligatorio: email, sms o whatsapp. |
source | string | Origen: double_opt_in, api o import. Por defecto api. Se conserva en las altas de WhatsApp; es informativo para los otros canales. |
Efecto por canal
- Email: registra el alta y devuelve
subscribedcuando el canal no está suprimido por rebote o queja. - SMS: registra el alta y devuelve
subscribed. - WhatsApp: registra el consentimiento para el número actual con origen y fecha. El número debe ser E.164; los bloqueos o rebotes no se anulan. Registrar consentimiento no garantiza acceso al canal de WhatsApp, que sigue en beta privada.
Respuesta
El suscriptor actualizado con 200 OK. Repetir la operación sobre el mismo estado no vuelve a cambiar su significado.
Ejemplo
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": "whatsapp", "source": "double_opt_in" }'Respuesta
{
"id": "sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8",
"object": "subscriber",
"email": "[email protected]",
"phone": "+34600000000",
"first_name": "Ada",
"last_name": "Lovelace",
"external_id": "user_12345",
"consent": {
"email": "subscribed",
"sms": "subscribed",
"whatsapp": "subscribed"
},
"properties": {
"company": "Analytical Engines",
"plan": "pro",
"country": "ES"
},
"lists": ["lst_0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f"],
"tags": ["beta", "vip"],
"created_at": "2026-05-11T12:34:56.000Z",
"updated_at": "2026-05-11T18:42:00.000Z",
"last_active_at": "2026-05-11T15:00:00.000Z"
}Errores
| HTTP | code | Descripción |
|---|---|---|
| 401 | missing_api_key / invalid_api_key | Falta la clave, no es válida, ha caducado o está revocada. |
| 403 | missing_scope | La clave no permite esta operación. |
| 403 | test_mode_unavailable | El modo de pruebas no está disponible. |
| 400 | invalid_param | ID, canal, origen o motivo no válido, propiedad reservada o campo desconocido. |
| 404 | resource_not_found | El suscriptor no existe en esta marca. |
| 409 | channel_unavailable | El canal está suprimido por rebote, queja o bloqueo. |
| 422 | missing_required_field | Falta email o teléfono según el canal; añade la identidad mediante actualizar. |