---
id: INT-007
type: Integration
title: "Push Notifications"
provider: "Firebase (Google)"
status: Pendiente
integration_type: "Notificaciones push"
created_at: 2026-01-10
updated_at: 2026-01-10
simco_version: "3.8.0"
tags:
  - notificaciones
  - push
  - firebase
  - fcm
  - mobile
  - web
---

# INT-007: Push Notifications

## Metadata

| Campo | Valor |
|-------|-------|
| **Codigo** | INT-007 |
| **Proveedor** | Firebase (Google) |
| **Tipo** | Notificaciones push |
| **Estado** | Pendiente |
| **Multi-tenant** | Si |
| **Fecha planeada** | 2026-Q1 |
| **Owner** | Backend Team |

---

## 1. Descripcion

Integración con Firebase Cloud Messaging (FCM) para enviar notificaciones push a dispositivos móviles (Android/iOS) y navegadores web. Permite mantener informados a los dueños de changarros sobre ventas, inventario bajo, pedidos nuevos y alertas importantes del negocio en tiempo real.

**Casos de uso principales:**
- Notificación instantánea de nuevas ventas realizadas
- Alertas de inventario bajo o productos agotados
- Notificaciones de pagos recibidos (SPEI, tarjeta)
- Recordatorios de cierre de caja y cortes
- Alertas de seguridad (accesos sospechosos, cambios de contraseña)

---

## 2. Credenciales Requeridas

### Variables de Entorno

| Variable | Descripcion | Tipo | Obligatorio |
|----------|-------------|------|-------------|
| FIREBASE_PROJECT_ID | ID del proyecto en Firebase Console | string | SI |
| FIREBASE_PRIVATE_KEY | Llave privada del service account | string | SI |
| FIREBASE_CLIENT_EMAIL | Email del service account | string | SI |
| FIREBASE_DATABASE_URL | URL de Firebase Realtime DB (opcional) | string | NO |
| FCM_SERVER_KEY | Server key legacy (deprecado, usar service account) | string | NO |

### Ejemplo de .env

```env
# Firebase Cloud Messaging
FIREBASE_PROJECT_ID=michangarrito-prod
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvgIBA...\n-----END PRIVATE KEY-----\n"
FIREBASE_CLIENT_EMAIL=firebase-adminsdk@michangarrito-prod.iam.gserviceaccount.com
FIREBASE_DATABASE_URL=https://michangarrito-prod.firebaseio.com
```

### Archivo de Service Account

Alternativamente, usar archivo JSON de credenciales:

```env
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
```

---

## 3. Arquitectura

```
┌─────────────────────────────────────────────────────────────────┐
│                      MiChangarrito                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │  Event Bus   │───▶│ Notification │───▶│   FCMService     │  │
│  │  (Eventos)   │    │   Manager    │    │                  │  │
│  └──────────────┘    └──────────────┘    └────────┬─────────┘  │
└────────────────────────────────────────────────────┼────────────┘
                                                     │
                                                     ▼
                                          ┌──────────────────┐
                                          │   Firebase FCM   │
                                          │   (Google)       │
                                          └────────┬─────────┘
                                                   │
                          ┌────────────────────────┼────────────────────────┐
                          │                        │                        │
                          ▼                        ▼                        ▼
                   ┌────────────┐          ┌────────────┐          ┌────────────┐
                   │  Android   │          │    iOS     │          │    Web     │
                   │    App     │          │    App     │          │  Browser   │
                   └────────────┘          └────────────┘          └────────────┘
```

### Flujo de Notificación

1. Evento ocurre en el sistema (venta, alerta, etc.)
2. Event Bus dispara evento al Notification Manager
3. Manager determina destinatarios y tipo de notificación
4. FCMService formatea y envía mensaje a Firebase
5. Firebase distribuye a dispositivos registrados
6. Usuario recibe notificación en su dispositivo

---

## 4. Endpoints

### Endpoints Consumidos (Firebase FCM API)

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| POST | `/v1/projects/{project}/messages:send` | Enviar notificación |
| POST | `/v1/projects/{project}/messages:sendAll` | Envío masivo (batch) |
| GET | `/v1/projects/{project}/messages/{id}` | Estado de mensaje |

### Endpoints Expuestos (MiChangarrito)

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| POST | `/api/v1/notifications/register` | Registrar device token |
| DELETE | `/api/v1/notifications/unregister` | Eliminar device token |
| GET | `/api/v1/notifications/settings` | Obtener preferencias |
| PUT | `/api/v1/notifications/settings` | Actualizar preferencias |
| POST | `/api/v1/notifications/test` | Enviar notificación de prueba |

---

## 5. Notas de Implementacion

- Usar Firebase Admin SDK para Node.js (firebase-admin)
- Almacenar device tokens en BD, asociados al usuario/tenant
- Implementar limpieza de tokens inválidos (error: NotRegistered)
- Manejar tokens múltiples por usuario (varios dispositivos)
- Respetar preferencias de notificación del usuario
- FCM tiene límite de 500 destinatarios por mensaje multicast
- Para envíos masivos usar topics o batching
- Implementar cola de notificaciones para alto volumen
- Las notificaciones web requieren HTTPS y service worker
- Considerar notificaciones silenciosas para actualizar datos en background
- iOS requiere configuración adicional de APNs en Firebase Console
- Implementar analytics de delivery y apertura de notificaciones