​

Centro de preferencias: página pública de inclusión/exclusión

Original en inglés: Preference center: the public opt-in/opt-out page.

​

1. Configurar una vez: POST/GET /preference-center

​

Campos de configuración

​

Temas de suscripción

• name (1–120 caracteres) — el nombre mostrado en la página.
• description (opcional, ≤500) — una línea de contexto mostrada junto al conmutador.
• defaultOptIn (por defecto false) — cómo se trata un contacto sin preferencia registrada.
• archived (opcional) — los temas archivados permanecen en la pista de auditoría pero ya no se muestran en la página.

​

2. Crear un enlace por contacto

curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/preference-center/link" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "cnt_01H…" }'

• El enlace apunta a la página alojada, no al punto de acceso JSON. Cómpielo tal cual en sus plantillas de pie de página/remitente; la página misma recupera el punto de acceso a datos en segundo plano.
• TTL de 30 días. Después, el token se verifica como expirado y el contacto debe solicitar un nuevo enlace (crear uno nuevo toma una llamada API).
• La página es agnóstica a la localización en el momento de creación. La aplicación web resuelve una redirección preservando la consulta ?token=, por lo que no necesita adivinar la configuración regional del contacto.

​

Dónde colocarlo

• Pie de página de correo electrónico (primario). Agregue el enlace generado (o la variante corta rastreada que usa su remitente) en la zona de cancelación de suscripción de las plantillas de marketing.
• Rescate SMS / WhatsApp. Cuando el mensaje no tiene bloque de pie de página, agregue el enlace en línea: {optOutMessage}: {link}. El ayudante que construye cuerpos salientes acepta un enlace corto pre-generado, por lo que su clic de cancelación sigue recibiendo la atribución normal de clics.
• Re-inclusión impulsada por supresión. Cuando un contacto se re-incluye a través de otro flujo, puede darle un enlace nuevo para que obtenga la misma página de autoservicio.

​

3. La página pública del token

• GET /preferences/:token — devuelve el payload de la página.
• PUT /preferences/:token — aplica actualizaciones.

​

Respuesta GET

{
  "contactId": "cnt_01H…",
  "displayName": "…",
  "email": "m*****@example.com",
  "phone": "+15551****…",
  "channelPreferences": { "sms": "opted_in", "email": "opted_out" },
  "frequencyPreference": "all",
  "channels": ["sms", "email"],
  "topics": [ { "id": "newsletter", "name": "Newsletter", "defaultOptIn": false } ],
  "topicPreferences": { "newsletter": "opted_in" },
  "consentHistory": [
    { "channel": "all", "state": "opted_out", "topicId": "newsletter", "occurredAt": "2026-09-01T…" }
  ],
  "config": { /* la configuración del centro de preferencias de la organización */ }
}

​

Cuerpo de solicitud PUT

{
  "channelPreferences": {
    "sms": "opted_in",
    "email": "opted_out"
  },
  "frequencyPreference": "important_only",
  "topicPreferences": { "newsletter": "opted_in" },
  "requestDataDeletion": false
}

• channelPreferences — mapa parcial permitido (Zod registro parcial); se requiere al menos un canal.
• frequencyPreference — opcional, uno de all, important_only, weekly_digest, monthly_digest.
• topicPreferences — mapa { topicId: opted_in | opted_out } opcional validado contra sus temas configurados; los id desconocidos se ignoran.
• requestDataDeletion — establece una solicitud de eliminación GDPR junto a la exclusión (ver sección 6).

​

4. Cómo fluyen las actualizaciones

• Libro de consentimiento. Una fila consent_records por canal (o por tema) se añade con source: preference_center — su pista de auditoría de carga probatoria GDPR Artículo 7.
• Lista de supresión. En cualquier canal excluido, el teléfono/correo electrónico canonizado del contacto se inserta con ámbito all — un bloqueo entre canales que lee cada puerta de envío.
• Valla STOP. Una valla de ruta rápida Redis se establece al opt-out (y se borra en una re-inclusión completa), de modo que los lotes de campañas en vuelo ven el cambio antes de que la propagación de supresión de base de datos más lenta llegue.
• Registro de auditoría. compliance.preference_center_updated se registra cuando cambia la configuración, y los eventos opt-in/out a nivel de contacto se capturan en el libro de consentimiento.

​

5. Semántica del conmutador de eliminación GDPR

​

6. Probarlo

curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/preference-center" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Acme Logistics",
    "primaryColor": "#1d4ed8",
    "channels": ["sms", "email"],
    "headerText": "Manage how Acme contacts you",
    "topics": [
      { "id": "shipping-updates", "name": "Shipping updates", "defaultOptIn": true },
      { "id": "promotions", "name": "Promotions", "defaultOptIn": false }
    ]
  }'

LINK=$(curl -s -X POST "https://api.orbit.devotel.io/api/v1/compliance/preference-center/link" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contactId":"cnt_01H…"}' | jq -r '.link')

TOKEN="${LINK#*token=}"

curl -s "https://api.orbit.devotel.io/api/v1/compliance/preferences/$TOKEN" | jq

curl -s -X PUT "https://api.orbit.devotel.io/api/v1/compliance/preferences/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channelPreferences":{"sms":"opted_out"}}' | jq

​

Relacionado

• Barreras de envío y protecciones pre-envío — dónde vive el resumen del centro de preferencias junto a las horas de silencio, parada de emergencia y limitaciones.
• Exclusión y Listas de supresión — cómo el ámbito all y las importaciones CSV masivas se relacionan con esta superficie.
• Gestión de consentimiento — la API del lado del operador que almacena el mismo libro de consentimiento.
• Referencia DSAR — el pipeline de borrado rastreado al que enrutar las solicitudes requestDataDeletion.