ElVendedorDocs

Arquitectura del ecosistema

Las tres piezas de ElVendedor, la responsabilidad de cada una, el flujo offline-first y quién es la autoridad de cada dato.

Para implementadores6 min de lecturaActualizado el 16 de noviembre de 2026

ElVendedor no es un programa único: es un ecosistema de tres aplicaciones que se prometen cosas entre sí mediante contratos versionados. Esta página describe qué hace cada pieza, cómo fluye la información cuando no hay internet y qué fuente manda cuando dos datos se contradicen. Léela antes de desplegar un cliente nuevo o de tocar una forma de payload.

Diagrama de la arquitectura: la app móvil y la app de escritorio guardan datos locales y sincronizan por HTTPS con la API del backend Laravel; el hub LAN de restaurante conecta los móviles con el escritorio en la red local.
Las dos apps trabajan sin conexión y sincronizan con el backend; el hub de restaurante vive solo en la red local.

Panorama: tres piezas, un contrato

Pieza Stack Rol Se instala como
el-vendedor Ionic 8 + Angular 17 + Capacitor 6; PouchDB sobre SQLite Cliente móvil: POS, inventario, compras, gastos, deudas, lotes, catálogo online, marketplace, licencias y terminal del hub de restaurante APK de Android (staging y producción)
el-vendedor-desktop Electron 42 + Vite + JavaScript; PouchDB sobre IndexedDB Cliente escritorio: POS y caja, compras, inventario, facturación fiscal, reportes de cierre y hub LAN de restaurante Instaladores de Windows y Linux (squirrel, deb, rpm, zip)
el-vendedor-back Laravel 12 + Sanctum + Inertia/Vue 3; SQLite o MySQL Autoridad: sync v1, licencias, catálogo online, marketplace, backoffice y caja por REST Servicio PHP detrás de HTTPS

Los tres comparten lo mismo en la versión de producto 2.1.6:

  • protocolo de sincronización 1 (cabecera X-Sync-Version);
  • contrato de datos 1 (contract_version del bootstrap);
  • cabeceras Authorization, X-Client-App-Version y, en el pull, X-Client-Entities;
  • las bases de producción y staging del backend.

La versión de producto, la del protocolo y la del contrato de datos son tres números distintos y se suben por motivos distintos. El detalle está en Compatibilidad de versiones.

Qué hace cada pieza

Cliente móvil

Es el motor operativo del vendedor y la implementación de referencia del producto. Escribe siempre en local y sincroniza después. Además de la operación diaria, es el único cliente que gestiona licencias y trial, que emite invitaciones de vendedor, que administra lotes con vencimiento, y el único que publica catálogo online y marketplace. Como terminal de restaurante, consulta mesas y emite comandos contra el hub del escritorio.

Cliente escritorio

Cubre el mostrador fijo y el trabajo de oficina: caja con arqueo, reportes de cierre imprimibles y facturación fiscal con series, numeración y huella. Es la única pieza que emite y reimprime facturas, y la única que puede ser hub LAN de restaurante: sirve la red del local, arbitra mesas y comandas y no depende de internet para el servicio.

Backend

No reemplaza la operación local: consolida los cambios de varios dispositivos, valida reglas globales, marca conflictos, audita y redistribuye. Es la autoridad de licencias, numeración fiscal y pertenencia de los datos a un negocio.

Flujo offline-first

El principio es que ninguna operación de negocio (vender, comprar, mover inventario, cambiar un precio) espera a la red para darse por hecha.

  1. Escritura local. La operación se guarda en la base local del dispositivo y se registra en una cola de salida (sync_outbox) con un event_id estable.
  2. Bootstrap. Un equipo nuevo pide GET /api/v1/sync/bootstrap y recibe contrato, negocio actual, estado de licencia, catálogo de licencia, límites de lote y lista de entidades soportadas.
  3. Pull. El cliente pide los cambios desde su cursor. El formato recomendado es v3:<N>, un orden global por server_version del negocio; una instalación nueva arranca en v3:0. El formato v2-serial se conserva por compatibilidad.
  4. Push. El cliente envía su cola en lotes con event_id como clave de idempotencia. El servidor responde accepted, duplicates y rejected.
  5. Conflictos. Cuando dos equipos tocan lo mismo o se repite una clave crítica, el servidor conserva un registro de conflicto y el cliente lo muestra para que una persona decida (keep_remote, discard_local, reviewed).

El stock no se sincroniza como valor absoluto. Viaja como eventos discretos (movimientos, ajustes, ventas, compras, mermas) y cada cliente reconstruye su proyección; así dos equipos offline no se sobrescriben el inventario.

El backend no es la fuente del día a día

Si el servidor se cae, el local sigue vendiendo, cobrando y emitiendo. La nube se usa para consolidar, respaldar y reportar; por eso el contrato tolera clientes desconectados durante días.

Quién es la autoridad de cada dato

Dato Autoridad Cómo se propaga
Negocio, usuarios y roles Backend bootstrap.current_business, employees
Licencia y vencimiento Backend bootstrap.current_business.license y cada business_profile
Limpieza de datos del negocio Backend data_reset_version; el cliente borra su copia local
Catálogo de productos, precios, almacenes y POS Dueño, desde el cliente Push de catálogo; el servidor consolida
Ventas, compras y gastos El dispositivo que las crea Eventos inmutables por push
Factura fiscal Escritorio (emisión) y backend (unicidad) Push de invoices y pull para el resto
Sesión de caja y su arqueo Backend (REST) con lease del dispositivo que abre cash-register REST; el servidor arbitra
Stock por almacén Derivado de eventos Cada cliente lo recalcula al aplicar deltas
Plano de salón y comandas Hub del escritorio Comandos LAN; la venta se crea al cobrar
Catálogo online y marketplace Backend, alimentado desde el móvil Entidades catalog_* y marketplace_*
Fotos de producto El dispositivo No viajan: son locales por equipo

Hub LAN de restaurante

El escritorio levanta un servidor HTTP y un WebSocket en la red del local (puerto por defecto 3897) y las terminales móviles se conectan a él. El hub es la autoridad dentro del WiFi: mesas, comandas, bloqueo de cobro y cierre. El flujo vivo no pasa por el backend; la nube solo recibe después la venta cerrada.

  • Cabeceras del contrato LAN: Authorization y X-Restaurant-Device-Id.
  • Una comanda abierta no es una venta contable ni descuenta inventario: la venta nace en confirm_payment y el inventario se mueve al cobrar.
  • El hub controla el bloqueo de cobro para evitar dobles cobros.

El contrato completo y el procedimiento de puesta en marcha están en Red de restaurante.

Licencias y arranque comercial

El backend sustituye al antiguo gestor de licencias. Cada equipo se activa con un token propio ligado a su device_id, y el estado viaja también por sync: el móvil revalida cada 12 horas y, sin red, aplica una gracia de 7 días. El gate de escrituras del push viene apagado por defecto; cuando se enciende, un negocio sin licencia vigente recibe 403 con error.code = license_invalid en sync/push.

Activación desde escritorio

El escritorio muestra el estado y el vencimiento de la licencia, pero todavía no tiene flujo de activación propio: la activación y la renovación se gestionan desde la app móvil o el backoffice. Es una decisión de producto pendiente de cerrar, no un defecto del contrato.

Cómo seguir

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