> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bbrands.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Notificaciones (OneSignal)

> Notificaciones de usuario basadas en cola (push, in-app, SMS, live activities) entregadas a través de OneSignal con gating de preferencias por usuario, idempotencia y reintentos.

<Info>
  Esta sección documenta la **plataforma de notificaciones de B Brands** — cómo cualquier
  acción de negocio notifica a un usuario (push, in-app, SMS, live activity) encolando
  un mensaje que un consumidor central despacha a
  [OneSignal](https://onesignal.com).
</Info>

## Qué es esto

Cualquier acción de negocio que necesite notificar a un usuario (cobro fallido, contrato
firmado, campaña) **encola** una notificación en lugar de llamar a OneSignal
directamente. Una única cola de Vercel (`notification`) alimenta un consumidor central que
despacha cada mensaje al handler del canal correspondiente.

<CardGroup cols={2}>
  <Card title="Sin notificaciones perdidas" icon="shield-check">
    Reintentos con backoff, dead-letter queue y replay heredados de la
    infraestructura compartida de `queue_event` absorben los picos y las caídas transitorias.
  </Card>

  <Card title="Idempotente" icon="fingerprint">
    Cada mensaje transporta un `queue_event_id`; una reentrega duplicada es un no-op.
  </Card>

  <Card title="Gating de preferencias" icon="sliders">
    El opt-out por usuario se aplica antes de encolar, sin tocar a los productores.
  </Card>

  <Card title="Único punto de entrada" icon="arrow-right-to-bracket">
    Los productores solo llaman a `notificationDispatcher`; la fontanería de canales queda
    oculta detrás de él.
  </Card>
</CardGroup>

## Canales

| Canal           | Entrega                                                         |
| --------------- | --------------------------------------------------------------- |
| `push`          | Notificación push estándar con título + cuerpo.                 |
| `in_app`        | Push solo de datos para que la app renderice un mensaje in-app. |
| `sms`           | SMS al teléfono E.164 del usuario.                              |
| `live_activity` | iOS Live Activity `start` / `update`.                           |

## Cómo fluye la señal

```mermaid theme={null}
flowchart TD
  prod["Business producer"] --> disp["notificationDispatcher"]
  disp --> gate{"Preference gating"}
  gate -- suppressed --> skip["Log + no enqueue"]
  gate -- allowed --> q["Vercel Queue (notification)"]
  q --> consumer["POST /api/queue/notification"]
  consumer --> handler["Channel handler"]
  handler --> os["OneSignal REST v11"]
  consumer --> qe["queue_event (received → processed / DLQ)"]
```

## Adónde ir después

<CardGroup cols={2}>
  <Card title="Arquitectura" icon="sitemap" href="/es/notifications/architecture">
    El dispatcher, el consumidor unificado, los handlers y el payload de la cola.
  </Card>

  <Card title="Canales y segmentación" icon="crosshairs" href="/es/notifications/channels-and-targeting">
    Semántica de canales, categorías y cómo se segmenta a los usuarios.
  </Card>

  <Card title="Preferencias e inbox" icon="inbox" href="/es/notifications/preferences-and-inbox">
    La matriz de opt-out y el inbox de notificaciones de cara al usuario.
  </Card>

  <Card title="Operaciones" icon="book" href="/es/notifications/operations">
    Variables de entorno, runbook de DLQ/replay y salud.
  </Card>
</CardGroup>