rckrdmrd
27b4e7bccf
- Update docs/_MAP.md with new phase references - Add docs/04-fase-saas/ phase structure - Add docs/05-fase-ia/ phase structure Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
199 lines
6.4 KiB
Markdown
199 lines
6.4 KiB
Markdown
---
|
|
id: MGN-018-webhooks
|
|
title: Modulo Webhooks para Clinica Dental
|
|
type: Module
|
|
status: Draft
|
|
version: 1.0.0
|
|
created_date: 2026-01-13
|
|
updated_date: 2026-01-13
|
|
phase: 04-fase-saas
|
|
normativas: [NOM-013-SSA2-2015, LFPDPPP]
|
|
---
|
|
|
|
# MGN-018: Webhooks Outbound para Clinica Dental
|
|
|
|
**Modulo:** MGN-018
|
|
**Nombre:** Webhooks Outbound
|
|
**Fase:** 04 - SaaS
|
|
**Estado:** Pendiente Documentacion
|
|
**Ultima actualizacion:** 2026-01-13
|
|
|
|
---
|
|
|
|
## Descripcion
|
|
|
|
Sistema de webhooks outbound para notificar eventos de la clinica dental a sistemas externos. Permite a las clinicas registrar endpoints HTTP para recibir notificaciones automaticas cuando ocurren eventos como agendamiento de citas, finalizacion de tratamientos, actualizacion de odontogramas, pagos de servicios, etc.
|
|
|
|
---
|
|
|
|
## Funcionalidades Principales
|
|
|
|
1. **Registro de Endpoints** - CRUD de endpoints webhook por clinica
|
|
2. **Firma HMAC-SHA256** - Firma criptografica de payloads
|
|
3. **Reintentos con Backoff** - Politica de reintentos exponencial
|
|
4. **Dead Letter Queue** - Almacenamiento de entregas fallidas
|
|
5. **Delivery Logs** - Historial completo de entregas
|
|
|
|
---
|
|
|
|
## Eventos Disponibles para Clinica Dental
|
|
|
|
| Categoria | Eventos |
|
|
|-----------|---------|
|
|
| **Citas** | `cita.creada`, `cita.confirmada`, `cita.cancelada`, `cita.completada` |
|
|
| **Pacientes** | `paciente.creado`, `paciente.actualizado` |
|
|
| **Tratamientos** | `tratamiento.iniciado`, `tratamiento.completado`, `tratamiento.cancelado` |
|
|
| **Odontograma** | `odontograma.actualizado`, `pieza.tratada` |
|
|
| **Pagos** | `pago.recibido`, `pago.fallido` |
|
|
| **Presupuestos** | `presupuesto.creado`, `presupuesto.aprobado`, `presupuesto.rechazado` |
|
|
|
|
---
|
|
|
|
## Casos de Uso Odontologicos
|
|
|
|
- Sincronizar pacientes con sistema de laboratorio dental
|
|
- Notificar a aseguradoras sobre tratamientos completados
|
|
- Actualizar sistema contable con pagos recibidos
|
|
- Integrar con Slack/Teams para alertas del equipo
|
|
- Trigger de recordatorios automaticos en herramientas externas
|
|
- Notificar a sistema de rayos X sobre nuevas citas
|
|
|
|
---
|
|
|
|
## Arquitectura
|
|
|
|
```
|
|
+-------------------+ +-------------------+ +-------------------+
|
|
| Evento Dental |---->| Webhook Service |---->| BullMQ Queue |
|
|
| (cita, tratam.) | | (enqueue) | | (webhooks) |
|
|
+-------------------+ +-------------------+ +-------------------+
|
|
|
|
|
v
|
|
+-------------------+
|
|
| Webhook Processor |
|
|
| (worker) |
|
|
+-------------------+
|
|
|
|
|
+-------------------+-------------------+
|
|
| |
|
|
v v
|
|
+---------------+ +---------------+
|
|
| HTTP POST | | Retry Queue |
|
|
| (lab dental, | | (backoff) |
|
|
| aseguradora) | +---------------+
|
|
+---------------+ |
|
|
| v (5 fails)
|
|
v +---------------+
|
|
+---------------+ | DLQ |
|
|
| Delivery Log | | (failed) |
|
|
| (success) | +---------------+
|
|
+---------------+
|
|
```
|
|
|
|
---
|
|
|
|
## Ejemplo de Payload
|
|
|
|
### Evento: cita.confirmada
|
|
|
|
```json
|
|
{
|
|
"event": "cita.confirmada",
|
|
"timestamp": "2026-01-13T10:30:00Z",
|
|
"webhook_id": "wh_dental_001",
|
|
"data": {
|
|
"cita_id": "cita_xyz789",
|
|
"paciente": {
|
|
"id": "pac_abc123",
|
|
"nombre": "Maria Garcia",
|
|
"telefono": "+521234567890"
|
|
},
|
|
"fecha": "2026-01-15",
|
|
"hora": "10:00",
|
|
"tratamiento": "Limpieza dental",
|
|
"doctor": "Dr. Rodriguez",
|
|
"sillon": 2,
|
|
"duracion_minutos": 45
|
|
}
|
|
}
|
|
```
|
|
|
|
### Evento: tratamiento.completado
|
|
|
|
```json
|
|
{
|
|
"event": "tratamiento.completado",
|
|
"timestamp": "2026-01-13T11:45:00Z",
|
|
"webhook_id": "wh_dental_002",
|
|
"data": {
|
|
"tratamiento_id": "trat_def456",
|
|
"paciente_id": "pac_abc123",
|
|
"tipo": "Resina",
|
|
"piezas_tratadas": ["16", "17"],
|
|
"doctor": "Dr. Martinez",
|
|
"costo": 1500.00,
|
|
"moneda": "MXN",
|
|
"notas": "Resina compuesta en molares superiores"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Dependencias
|
|
|
|
**Este modulo depende de:**
|
|
- MGN-001 Auth (autenticacion de administradores)
|
|
- MGN-004 Tenants (aislamiento por clinica)
|
|
- MGN-017 Plans (feature gating - solo planes Clinica y Centro)
|
|
|
|
**Modulos que dependen de este:**
|
|
- Integraciones con laboratorios dentales
|
|
- Sistemas de aseguradoras
|
|
- Herramientas de notificacion
|
|
|
|
---
|
|
|
|
## Seguridad y Normativas
|
|
|
|
| Medida | Implementacion |
|
|
|--------|----------------|
|
|
| HMAC signature | SHA-256 con secret por endpoint |
|
|
| Timestamp | Previene ataques de replay (5 min) |
|
|
| URL validation | Solo HTTPS en produccion |
|
|
| Timeout | 30 segundos maximo |
|
|
| NOM-013-SSA2-2015 | No enviar datos sensibles de salud sin consentimiento |
|
|
| LFPDPPP | Cumplimiento de privacidad de datos |
|
|
|
|
### Datos Sensibles
|
|
|
|
Los webhooks NO deben incluir:
|
|
- Expediente clinico completo
|
|
- Diagnosticos detallados
|
|
- Radiografias o imagenes
|
|
- Datos de pago completos
|
|
|
|
Para datos sensibles, el receptor debe hacer una consulta autenticada a la API.
|
|
|
|
---
|
|
|
|
## Documentacion
|
|
|
|
- **Requerimientos:** [requerimientos/](./requerimientos/)
|
|
- **Especificaciones:** [especificaciones/](./especificaciones/)
|
|
- **User Stories:** [historias-usuario/](./historias-usuario/)
|
|
- **Trazabilidad:** [implementacion/TRACEABILITY.yml](./implementacion/TRACEABILITY.yml)
|
|
|
|
---
|
|
|
|
## Referencias
|
|
|
|
- **Fuente:** [erp-core/MGN-018-webhooks](../../../../../erp-core/docs/04-fase-saas/MGN-018-webhooks/)
|
|
- **Arquitectura SaaS:** [ARQUITECTURA-SAAS.md](../../00-vision-general/ARQUITECTURA-SAAS.md)
|
|
|
|
---
|
|
|
|
*Modulo: MGN-018-webhooks | Clinica Dental*
|
|
*Propagado desde erp-core via erp-clinicas*
|
|
*Actualizado: 2026-01-13*
|