ElVendedorDocs

Compatibilidad de versiones

Qué versión de producto, protocolo y contrato habla cada pieza, qué combinaciones se aceptan y qué política aplica el backend.

Para implementadores4 min de lecturaActualizado el 16 de noviembre de 2026

Tres números gobiernan la compatibilidad y se confunden con facilidad: la versión de producto (qué app instalaste), el protocolo de sync (cómo se habla) y el contrato de datos (qué forma tienen los payloads). Esta página fija los valores vigentes y qué pasa cuando no coinciden.

Versiones vigentes

Elemento Valor vigente Dónde se declara
Versión de producto 2.1.6 package.json del móvil y del escritorio; versionName de Android
Protocolo de sync 1 SYNC_PROTOCOL_VERSION; cabecera X-Sync-Version
Contrato de datos 1 SYNC_CONTRACT_VERSION en servidor; SYNC_CONTRACT_VERSION en ambos clientes
Versión de app del backend 2.1.6 APP_VERSION (por defecto, 2.1.6 en .env.example)
Política de app minimum_version SYNC_APP_COMPATIBILITY_POLICY
Mínimo aceptado 2.1.6 SYNC_MINIMUM_APP_VERSION
Formatos de cursor v2-serial, v3-server-version pull_contract.cursor_formats

El backend no publica una versión de producto propia en su manifiesto: la única versión que anuncia es APP_VERSION, y es la que compara con la de los clientes.

Cómo se negocia

Protocolo. El cliente envía X-Sync-Version; debe estar en supported_sync_versions. Si falta o no está soportado, el servidor responde 409 con sync_protocol_version_missing o sync_protocol_version_mismatch. No es reintentable.

Contrato de datos. El bootstrap anuncia contract_version y el cliente lo compara con el suyo: si el servidor es mayor, la app está vieja (sync_contract_version_too_new); si es menor, el servidor está viejo (sync_contract_version_too_old). Ambos errores los emite el cliente.

Versión de app. Solo se valida si compatibility.enforced es true, según compatibility.policy.

Política Regla required_app_version
none No se comprueba la versión de la app null
same_version Igual a required_app_version se emite
minimum_version Mayor o igual a minimum_app_version null
explicit_list Presente en compatible_app_versions null

Compatibilidad con servidores antiguos. Si no viaja policy, el cliente la infiere de la presencia de required_app_version; si no viaja enforced, asume true para same_version. Si el servidor no envía contract_version, se asume 1.

Combinaciones

Combinación Resultado
Móvil 2.1.6 + escritorio 2.1.6 + backend APP_VERSION=2.1.6, política minimum_version Aceptada: es la configuración de referencia del release
Cliente anterior al mínimo (minimum_version) Bloqueado con sync_app_version_too_old; no reintentable
Cliente posterior al mínimo Aceptado; el servidor no exige igualdad
Cliente con protocolo distinto Bloqueado con sync_protocol_version_mismatch
Servidor con contrato mayor que el del cliente Bloqueado con sync_contract_version_too_new (actualizar la app)
Servidor con contrato menor que el del cliente Bloqueado con sync_contract_version_too_old
Servidor antiguo sin contract_version ni policy Se asume contrato 1 y se infiere la política
Cliente antiguo sin X-Client-Entities El servidor sirve todas las entidades; el cliente registra diagnóstico por las que no aplica

Pendiente de validación

No hay publicada una matriz histórica de combinaciones intermedias (por ejemplo 2.1.5 con backend 2.1.6). Lo anterior describe el contrato y sus pruebas de compatibilidad, no una certificación de cada par posible. Antes de afirmar que una combinación concreta funciona en producción, valídala con el responsable de release.

Variables del backend

Variable Por defecto Efecto
APP_VERSION 2.1.6 Versión de producto que anuncia el servidor
SYNC_PROTOCOL_VERSION 1 Protocolo que habla el servidor
SYNC_SUPPORTED_PROTOCOL_VERSIONS 1 Lista de protocolos aceptados (CSV)
SYNC_CONTRACT_VERSION 1 Versión del contrato de datos
SYNC_APP_COMPATIBILITY_POLICY minimum_version Política de versión de app
SYNC_MINIMUM_APP_VERSION 2.1.6 Mínimo aceptado con minimum_version
SYNC_REQUIRED_APP_VERSION vacío Solo se usa con same_version
SYNC_COMPATIBLE_APP_VERSIONS vacío Lista blanca con explicit_list

La cadena de respaldo de la versión exigida es SYNC_REQUIRED_APP_VERSION → SYNC_CURRENT_APP_VERSION → APP_VERSION. Si ninguna tiene valor, la política no se aplica.

Políticas recomendadas según entorno:

Entorno Política Variable adicional
Desarrollo none —
Staging minimum_version SYNC_MINIMUM_APP_VERSION=<baseline>
Producción estable minimum_version SYNC_MINIMUM_APP_VERSION=<baseline>
Despliegue gradual explicit_list SYNC_COMPATIBLE_APP_VERSIONS=<lista>
Bloqueo estricto same_version SYNC_REQUIRED_APP_VERSION=<exacta>

Verificar la configuración

php artisan tinker --execute="
  \$c = app(App\Support\Sync\SyncCompatibility::class);
  echo 'policy: '.\$c->appPolicy().PHP_EOL;
  echo 'enforced: '.json_encode(\$c->isAppPolicyEnforced()).PHP_EOL;
  echo 'minimum: '.(\$c->minimumAppVersion() ?? 'null').PHP_EOL;
  echo 'protocol: '.\$c->currentProtocolVersion().PHP_EOL;
"

Después de cambiar variables de entorno, limpia la caché de configuración (php artisan config:clear en desarrollo, php artisan config:cache en producción). La respuesta de GET /api/v1/sync/bootstrap muestra el bloque compatibility efectivo, que es lo que ve el cliente.

Política de soporte

  • La versión soportada es la 2.1.6 en móvil y escritorio, contra un backend con protocolo 1 y contrato 1.
  • Subir la versión mínima deja fuera a los equipos que no actualicen: con minimum_version el corte es inmediato y no reintentable, así que conviene desplegar la app primero y subir el mínimo después.
  • Un cambio de forma de payload sube SYNC_CONTRACT_VERSION; añadir entidades o campos opcionales no la sube.
  • Un cambio que rompe el protocolo sube SYNC_PROTOCOL_VERSION y, si hay flota antigua, se amplía SYNC_SUPPORTED_PROTOCOL_VERSIONS durante la transición.

Pendiente de validación

Los repositorios no publican etiquetas de versión: al día de esta revisión git tag no devuelve ninguna en móvil, escritorio ni backend, y el backend no tiene versión de producto en su manifiesto. Por tanto no se puede responder «qué backend corresponde a esta app» consultando el repositorio. El checklist de release de cada repo exige etiquetar y registrar la matriz; hasta que se publique, la correspondencia se valida a mano con el equipo de release.

Siguiente paso

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