ElVendedorDocs

Actualizaciones y versiones

Orden correcto para actualizar backend, escritorio y móvil, cómo verificar protocolo y contrato, y qué hacer con clientes atrasados.

Para implementadores4 min de lecturaActualizado el 16 de noviembre de 2026

Actualizar ElVendedor no es instalar tres archivos: backend, escritorio y móvil comparten un protocolo y un contrato de datos. Al terminar esta página sabrás en qué orden actualizar, cómo comprobar que las versiones encajan y cómo sacar a un cliente de un estado bloqueado sin romper sus datos.

Orden recomendado

  1. Backend primero, sin subir todavía la baseline de app. Publica el contrato, la política y los límites nuevos; los clientes viejos siguen sincronizando.
  2. Escritorio, que es el hub LAN y quien firma facturas.
  3. Móvil, que es el que más rápido se propaga entre vendedores y cajeros.
  4. Cierre: cuando la mayoría de los equipos ya corra la versión nueva, sube SYNC_MINIMUM_APP_VERSION y, si corresponde, enciende LICENSING_ENFORCE_SYNC_GATE.

Subir la baseline antes de actualizar la flota deja a los clientes viejos con sync_app_version_too_old, un error no reintentable.

Qué versión se mueve en cada repo

Repo Dónde Cuándo cambia
Backend APP_VERSION en .env y .env.example Cada release de producto
Backend SYNC_PROTOCOL_VERSION / SYNC_SUPPORTED_PROTOCOL_VERSIONS Solo si cambia el protocolo de forma incompatible
Backend SYNC_CONTRACT_VERSION Solo con cambios incompatibles de payload
Escritorio package.json → version (hoy 2.1.6) Cada release
Móvil package.json → version, versionName Cada release
Móvil versionCode Cada APK instalado encima

Los tres repos deben llevar el mismo vX.Y.Z de producto. SYNC_CONTRACT_VERSION sube en los tres a la vez, y una misma versión de contrato debe significar lo mismo en todos.

Verificar protocolo y contrato

El cliente móvil y el escritorio declaran SYNC_CONTRACT_VERSION = 1; el backend lo publica en el bootstrap junto al protocolo:

{
  "sync_version": 1,
  "contract_version": 1,
  "compatibility": {
    "policy": "minimum_version",
    "enforced": true,
    "server_app_version": "2.1.6",
    "required_app_version": null,
    "minimum_app_version": "2.1.6"
  }
}

Lectura correcta:

  • sync_version fuera de SYNC_SUPPORTED_PROTOCOL_VERSIONS → nada sincroniza. Hay que actualizar el cliente que quedó atrás.
  • contract_version mayor que el del cliente → el cliente está viejo (sync_contract_version_too_new); menor → el servidor está viejo (sync_contract_version_too_old). Ambos cortan el sync.
  • compatibility.enforced: false significa que el servidor no valida la versión de app; solo el protocolo.
  • required_app_version solo llega con policy = same_version.

Comprobación rápida desde el servidor:

php artisan tinker --execute="
  \$svc = app(App\Support\Sync\SyncCompatibility::class);
  echo 'policy: '.\$svc->appPolicy().PHP_EOL;
  echo 'minimum_app_version: '.(\$svc->minimumAppVersion() ?? 'null').PHP_EOL;
  echo 'protocol_version: '.\$svc->currentProtocolVersion().PHP_EOL;
"

Si un cliente quedó atrás

Código Significado Qué hacer
sync_protocol_version_mismatch El cliente habla otro protocolo Actualizar el cliente
sync_client_app_version_missing No envía X-Client-App-Version Cliente muy viejo: actualizar
sync_app_version_too_old Está por debajo de la baseline Actualizar o bajar la baseline (decisión de producto)
sync_contract_version_too_new Cliente con contrato más nuevo Actualizar el backend
business_data_reset_required El negocio se limpió en backoffice El cliente borra datos locales y re-bootstrapea

Si la actualización del cliente no es posible de inmediato, la vía temporal es ampliar la política: explicit_list con las versiones que sí pueden sincronizar, o none mientras se diagnostica. none es un interruptor de desarrollo: no lo dejes activo en producción. Recuerda regenerar la caché de configuración al cambiar .env.

Migraciones y ventana de mantenimiento

php artisan migrate --force

Antes de migrar, respalda la base de datos y anota el .env vigente (política, versiones). La práctica para el cliente, tomada de la guía de instalación, es actualizar fuera del horario de venta y con la caja del día ya cerrada.

Pendiente de validación

El repositorio no documenta un procedimiento de respaldo de la base ni una ventana de mantenimiento estándar. Confirma con el Lead qué backup se exige antes de un migrate en producción y quién autoriza la ventana.

Rollback

  • Backend: revierte el despliegue y restaura el .env anterior (política y versiones); después php artisan config:cache si usas caché de configuración.
  • Escritorio: instala la versión anterior encima. No hay actualizaciones automáticas ni servidor de updates, y el perfil local se conserva.
  • Móvil: reinstala el APK anterior; el versionCode debe poder instalarse (ver Despliegue de la app móvil).
  • Contrato: si subiste SYNC_CONTRACT_VERSION por error, vuelve atrás y verifica que ningún cliente haya adoptado el contrato nuevo. No reescribas historia ni fuerces push para "deshacer" un release: publica una versión nueva.

Política de versiones soportadas

Política Uso
minimum_version Recomendada en producción y staging; no bloquea por parches
explicit_list Rollout por olas o betas concretas
same_version Lockdown puntual; default del config, no de un release normal
none Solo desarrollo

Bajar la baseline es una decisión de producto explícita, no un ajuste operativo. La matriz de qué versión de cliente habla con qué backend y protocolo está en Compatibilidad.

Siguiente paso

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