ElVendedorDocs

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.

Para implementadores5 min de lecturaActualizado el 16 de noviembre de 2026

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-run

Ventanas 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_VERSION solo cuando la flota ya esté actualizada; es el corte que deja a los clientes viejos sin sincronizar.
  • Tras cambiar .env, ejecuta php artisan config:cache y verifica el bootstrap otra vez.
  • Los cambios de SYNC_CONTRACT_VERSION son incompatibles: publica notas y evita hacerlo en horario de venta.
  • same_version es 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

↑↓ para navegar · Enter para abrir · Esc para cerrar