DOCUMENTACIÓN TÉCNICA
DataController — [Link] Core Web API
Sistema de Sincronización entre Parroquias
Este documento describe en detalle cada uno de los endpoints expuestos por el controlador DataController,
incluyendo su propósito, los parámetros que reciben, los stored procedures que invocan y el comportamiento
esperado ante distintos escenarios.
1. Ejecutar Stored Procedure
POST /api/Data/ejecutar-sp
Endpoint central del controlador. Permite ejecutar cualquier stored procedure de forma dinámica sin necesidad
de escribir un endpoint específico para cada operación. El cliente envía el nombre del SP y un diccionario de
parámetros en formato JSON.
Flujo de ejecución:
• 1. Se extrae y valida _ParroquiaId del cuerpo o del diccionario de parámetros.
• 2. Se abre la conexión a SQL Server y se construye un SqlCommand de tipo StoredProcedure.
• 3. Los parámetros del JSON se mapean a parámetros SQL, convirtiendo automáticamente los tipos (string, int,
double, bool, DateTime, null). Los parámetros internos (prefijo _) y el campo Hash se excluyen de este mapeo.
• 4. Se ejecuta el SP principal con ExecuteNonQuery.
• 5. Si el JSON contiene la clave Hash, se llama adicionalmente a sp_RegistrarCambio para guardar el cambio en
la cola de sincronización.
• 6. Retorna HTTP 200 con mensaje de éxito, o HTTP 500 ante error SQL.
Stored Procedures involucrados: sp_RegistrarCambio (condicional)
Cuerpo de la petición (JSON):
{ "SpName": "sp_InsertarFeligres", "Parametros": { "Nombre": "Juan Pérez", "FechaNacimiento":
"1990-05-12", "Hash": "abc123xyz", "_ParroquiaId": 3 } }
Nota: La clave Hash activa el registro del cambio para sincronización. Si no se incluye, el SP se ejecuta localmente sin
dejar rastro en la cola.
2. Obtener Cambios Pendientes por Parroquia
GET /api/Data/cambios-pendientes/{parroquiaId}
Devuelve la lista de cambios que aún no han sido sincronizados hacia una parroquia destino específica. Es
consumido por otros nodos durante el proceso de pull para saber qué operaciones deben replicar.
Parámetros:
Parámetro Tipo Descripción
parroquiaId int (URL) ID de la parroquia destino que solicita sus cambios pendientes.
Stored Procedures involucrados: sp_ObtenerCambiosPendientes
Respuesta exitosa (HTTP 200) — Array de objetos:
[ { "id": 12, "spName": "sp_ActualizarMiembro", "parametrosJson": "{\"Nombre\":\"Ana\"}",
"hash": "d4f1a2b3", "origenParroquiaId": 1 } ]
3. Obtener Todos los Cambios Pendientes
GET /api/Data/cambios-pendientes-todos
Variante global del endpoint anterior. Retorna todos los cambios pendientes sin filtrar por parroquia destino. Se
usa cuando se requiere una sincronización completa del sistema, por ejemplo al inicializar un nodo nuevo o ante
una resincronización masiva.
No recibe parámetros. La estructura de respuesta es idéntica al endpoint anterior.
Stored Procedures involucrados: sp_ObtenerCambiosPendientesTodos
Diferencia clave: mientras el endpoint 2 filtra por DestinoParroquiaId, este endpoint trae todos los cambios
independientemente de a quién van dirigidos.
4. Marcar Cambio como Entregado
POST /api/Data/marcar-entregado
Una vez que un nodo remoto ha aplicado exitosamente un cambio, llama a este endpoint para registrar la
entrega. Esto evita que el mismo cambio vuelva a aparecer en futuras consultas de cambios pendientes para esa
parroquia.
Parámetros del cuerpo:
Parámetro Tipo Descripción
CambioId int Identificador único del cambio que fue aplicado exitosamente.
DestinoParroquiaId int ID de la parroquia que confirmó la recepción del cambio.
Stored Procedures involucrados: sp_MarcarEntregado
Cuerpo de la petición (JSON):
{ "CambioId": 12, "DestinoParroquiaId": 4 }
5. Aplicar Cambio Recibido
POST /api/Data/aplicar-cambio-recibido
Aplica localmente un cambio que proviene de un nodo remoto. El stored procedure sp_AplicarCambioRecibido
utiliza el Hash como mecanismo de idempotencia: si el cambio ya fue aplicado anteriormente (mismo Hash), lo
ignora y retorna un indicador de duplicado. Esto garantiza que los datos no se corrompan ante re-envíos.
Parámetros del cuerpo:
Parámetro Tipo Descripción
Hash string Identificador único del cambio. Actúa como clave de idempotencia.
SpName string Nombre del stored procedure original que generó el cambio.
ParametrosJson string JSON con los parámetros originales del SP serializado como string.
OrigenParroquiaId int ID de la parroquia que originó el cambio.
Stored Procedures involucrados: sp_AplicarCambioRecibido
Respuesta: retorna el resultado del scalar (APLICADO o indicador de duplicado) junto con el Hash procesado.
6. Jalar Cambios (Sincronización Pull)
POST /api/Data/jalar-cambios
Endpoint orquestador de la sincronización. Ejecuta un proceso completo de pull: consulta los cambios
pendientes en una API remota y los aplica localmente uno a uno. Es el único endpoint async del controlador, ya
que realiza llamadas HTTP externas.
Parámetros del cuerpo:
Parámetro Tipo Descripción
UrlRemota string URL base de la API remota de donde se jalaran los cambios.
ParroquiaDestinoId int? (opt) Si se provee y es mayor a 0, filtra cambios de esa parroquia. Si es null o 0,
jala TODOS los cambios disponibles.
Flujo interno:
• Paso 1 — Determinar URL: construye la URL de consulta según si se filtra por parroquia
(/cambios-pendientes/{id}) o no (/cambios-pendientes-todos).
• Paso 2 — Consultar API remota: realiza un GET HTTP con timeout de 2 minutos.
• Paso 3 — Iterar cambios: por cada cambio recibido, llama al método interno AplicarCambioRecibidoInternal
que ejecuta sp_AplicarCambioRecibido localmente.
• Paso 4 — Contabilizar: lleva conteo de cambios aplicados y errores.
• Paso 5 — Responder: retorna un resumen con totales de cambios encontrados, aplicados y errores.
Cuerpo de la petición (JSON):
// Sincronización global (trae todos) { "UrlRemota": "[Link]
"ParroquiaDestinoId": null } // Sincronización filtrada { "UrlRemota":
"[Link] "ParroquiaDestinoId": 3 }
Respuesta exitosa (HTTP 200):
{ "mensaje": "Sincronizacion completada", "cambiosEncontrados": 5, "cambiosAplicados": 4,
"errores": 1, "timestamp": "2025-07-15T10:23:45" }
Flujo General del Sistema de Sincronización
El siguiente diagrama muestra cómo interactúan los endpoints para lograr la replicación de datos entre
parroquias:
Paso Nodo Origen Acción Nodo Destino
1 Parroquia A POST /ejecutar-sp → Guarda cambio con Hash —
2 Parroquia B POST /jalar-cambios → Solicita cambios a A —
3 — GET /cambios-pendientes/{id} ← A responde Parroquia A
4 Parroquia B sp_AplicarCambioRecibido → Aplica localmente —
El Hash actúa como llave de idempotencia en todo el flujo: garantiza que aunque un cambio sea enviado
múltiples veces, solo se aplique una vez en cada nodo destino. Los parámetros con prefijo _ (como _ParroquiaId)
son metadatos de contexto y nunca se pasan directamente a SQL Server.