Sincronización en producción
Cómo comprobar que el sync funciona, leer sus contadores, resolver conflictos y reprocesar eventos fallidos sin romper el contrato v1.
Esta página es la vista operativa del sync: qué mirar, en qué orden y qué hacer cuando un cliente deja de subir datos. El contrato completo —campos, códigos y cursores— vive en Sincronización (referencia); aquí no se repite.
Verificar que el sync está vivo
El backend expone /api/v1/sync/bootstrap, /pull y /push bajo auth:sanctum con ability sync:owner o sync:seller, y el token debe pertenecer al negocio actual. La prueba mínima:
curl -s https://mi-servidor.example/api/v1/sync/bootstrap \
-H "Authorization: Bearer <token>" \
-H "X-Sync-Version: 1" \
-H "X-Client-App-Version: 2.1.6"Respuesta sana: sync_version y contract_version iguales a los del cliente, compatibility con policy y enforced, current_business con data_reset_version y license, y los límites en push_contract.max_batch_size y pull_contract.default_limit.
Lee los límites del bootstrap
No codifiques 500 ni 1000 a mano: el servidor publica sus límites y puede cambiarlos sin avisar.
Estados y contadores
El cliente de escritorio resume el sync en su vista de sincronización; el móvil muestra el mismo tipo de datos en su pantalla de sync. Los campos que exporta el reporte de diagnóstico son:
| Campo | Qué te dice | Valor sano |
|---|---|---|
last_attempt_at / last_success_at |
Último intento y último éxito. | Diferencia de minutos, no de días. |
last_result |
Resultado del último ciclo (idle u otro). |
Sin errores repetidos. |
last_error_code / last_error_stage |
Código real del servidor y etapa donde falló. | Vacío. |
last_http_status |
Código HTTP del último fallo. | 200 / 202. |
last_pushed_count / last_pulled_count |
Cambios enviados y recibidos. | Coherentes con la operación del día. |
last_push_rejected_count |
Items rechazados en el último push. | 0. |
outbox_issues |
Pendientes con error en la cola local. | Lista vacía. |
data_reset_version |
Versión de limpieza del negocio. | Igual a la del bootstrap. |
license (status, is_usable, days_remaining, blocked) |
Estado de licencia y bloqueo. | is_usable: true, blocked: false. |
El ciclo: bootstrap, pull, push
| Paso | Endpoint | Qué ocurre |
|---|---|---|
| Bootstrap | GET /api/v1/sync/bootstrap |
Contrato, negocio actual, licencia, capacidades y límites. |
| Pull | GET /api/v1/sync/pull |
Deltas de servidor a cliente desde el cursor. |
| Push | POST /api/v1/sync/push |
Lote de 1 a max_batch_size cambios, con event_id como clave de idempotencia. |
Cabeceras que viajan en cada llamada:
| Cabecera | Obligatoria | Uso |
|---|---|---|
X-Sync-Version |
Sí | Protocolo del cliente; si falta, la petición se rechaza. |
X-Client-App-Version |
Según compatibility.enforced |
Versión de la app para la política activa. |
X-Client-Entities |
No | Entidades que el cliente sabe aplicar; el servidor sirve la intersección. |
X-Business-Data-Reset-Version |
Recomendada en cada push | Detecta equipos con datos anteriores a una limpieza del negocio. |
Un 409 con business_data_reset_required no se reintenta: borra los datos locales del negocio, descarta el outbox, limpia el checkpoint y relanza el bootstrap.
Conflictos
Los conflictos abiertos llegan en el campo conflicts del pull, independientes del cursor de datos. Se resuelven con:
curl -s -X POST https://mi-servidor.example/api/v1/sync/conflicts/12/resolve \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"resolution":"keep_remote","notes":"Se adoptó el dato del servidor"}'resolution acepta keep_remote, discard_local o reviewed, y el endpoint devuelve id, status, resolution_notes y resolved_at. En escritorio los mismos valores están en los botones Mantener remoto, Descartar local y Revisado, que aparecen por conflicto en la vista de sync.
Antes de resolver, lee conflict_type y entity_id: los conflictos de código de producto duplicado o de número de factura no se arreglan manteniendo el remoto, se arreglan corrigiendo el dato.
Eventos fallidos
Si un push se cortó a mitad de lote, parte del payload puede haber quedado en sync_received_events con estado failed. Para el dueño hay dos endpoints:
| Método | Ruta | Uso |
|---|---|---|
GET |
/api/v1/sync/failed-events |
Resumen: total_failed y per_entity, sin tocar datos. |
POST |
/api/v1/sync/reprocess-failed-events |
Reaplica eventos failed, filtrable por tipo de entidad y por event_id. |
El reproceso devuelve attempted, applied, still_failed, remaining_failed, per_entity y hasta 50 reasons. Si remaining_failed no baja, el problema no es de red: lee error_message. La limpieza de eventos ya aplicados es tarea de mantenimiento:
php artisan sync:prune-events --days=180 --dry-runVentanas de mantenimiento
- Actualiza primero el backend y después los clientes: el servidor debe anunciar el contrato nuevo antes de que los equipos lo hablen.
- Mueve
SYNC_MINIMUM_APP_VERSIONsolo cuando la flota ya esté actualizada; es el corte que deja a los clientes viejos sin sincronizar. - Tras cambiar
.env, ejecutaphp artisan config:cachey verifica el bootstrap otra vez. - Los cambios de
SYNC_CONTRACT_VERSIONson incompatibles: publica notas y evita hacerlo en horario de venta. same_versiones lockdown: no se usa en releases normales.
Pendiente de validación
No hay una ventana de mantenimiento declarada en los repos (duración, aviso al cliente, horario sugerido). Defínela con el responsable de operaciones antes de tocar producción.
Cuando un cliente no sube datos
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
Push responde 409 y code de versión |
App o protocolo fuera de política. | Actualiza el cliente; el error no es reintentable. |
Push responde 403 license_invalid |
Gate de licencias encendido y licencia no vigente. | Renueva desde backoffice; apaga el gate mientras investigas. |
rejected con retryable: false |
Dato inválido o no permitido (código duplicado, número repetido, permiso). | Corrige el dato en el cliente y vuelve a encolar. |
Todo accepted pero el otro equipo no ve nada |
El cliente no está pidiendo esa entidad en X-Client-Entities. |
Revisa la capacidad declarada y fuerza un pull. |
| Nada sale del equipo | Red, token caducado o negocio actual distinto. | Prueba el bootstrap con curl y compara current_business. |
Siguiente paso
¿Falta algo o encontraste un error?
Ayúdanos a mejorar esta documentación con tu experiencia real.
Escribir a soporte