Sincronización de Puntos de Venta con un Servidor Central en Odoo

1.Cómo usar este manual

Una guía completa para el personal de operaciones, encargados de tienda y equipo de TI que administra la red de puntos de venta.

Este manual documenta el sistema de sincronización que conecta un servidor central Odoo 19 con las instancias de punto de venta Odoo 18 instaladas en cada tienda. Está escrito para tres lectores distintos:

• El encargado de operaciones, que necesita entender qué viaja entre las tiendas y el central, cuándo, y cómo verificar que todo llegó (capítulos 11 a 18).
• El equipo de TI, que instala y configura ambos módulos, administra las llaves API y resuelve incidencias (capítulos 5 a 10 y 19 a 22).
• El personal de tienda, que solo necesita saber qué botones existen en su instancia y qué significa cada estado (capítulos 13 a 16).

Todas las capturas de pantalla provienen de un ambiente real con los dos módulos instalados y sincronizando datos entre sí. Los nombres técnicos de campos y botones aparecen tal como se ven en pantalla, en este formato cuando son valores o rutas técnicas.

2.Qué es el sincronizador y cómo funciona

Un servidor concentra; muchas tiendas operan. Cada dato viaja en una sola dirección y con una clave que lo identifica sin ambigüedad.

Cada tienda opera de forma autónoma: su punto de venta funciona aunque no haya internet hacia el central, porque la base de datos es local. La sincronización ocurre después de los hechos: cuando se cierra una sesión de caja, cuando se valida una recepción de compra, cuando se cuenta un inventario. El central, por su parte, es el dueño del catálogo: los productos, los precios, las categorías y la configuración de cada caja se definen una sola vez en el central y se empujan hacia todas las tiendas.

El mecanismo: colas, endpoints y registros

La comunicación funciona igual en ambas direcciones, con tres piezas:

1. Una cola de envíos en el lado que emite. Cada evento (cerrar una sesión, sincronizar un producto) crea un registro en la cola con el destino, el contenido en formato JSON y un estado: Pending → In Progress → Completed o Failed. Si el envío falla, el registro queda con el error y puede reintentarse.
2. Un receptor (endpoint) en el lado que recibe: una ruta HTTP protegida con llave API que valida el contenido, crea o actualiza los documentos y responde éxito o error.
3. Un log en el lado que recibe, donde queda escrito cada mensaje recibido: cuándo llegó, qué contenía y qué se respondió. Es la bitácora que se consulta cuando algo no cuadra.

3.Los dos módulos y su alcance

Un módulo por lado, diseñados como espejo el uno del otro.

4.Los códigos que emparejan todo

El sistema nunca empareja por nombre: siempre usa una clave estable. Si una clave falta o no coincide, esa sincronización falla o cae a un genérico.

Antes de configurar nada conviene entender esta tabla. Es la causa de la mayoría de los problemas de sincronización — y de sus soluciones:

5.Puesta en marcha: lista de verificación

El orden importa: primero las llaves y los códigos, después el catálogo, y al final los flujos diarios.

En el servidor central (una sola vez)

1. Instalar mrdc_sync_manager (instala también auth_api_key y deltatech_stock_inventory).
2. Crear una llave API para las tiendas (capítulo 8).
3. En la compañía, pestaña MRDC Sync: activar la sincronización y definir el producto genérico y el método de pago genérico (capítulo 6).
4. Crear los almacenes de cada tienda con su MRDC Code y su cuenta analítica (capítulo 9).
5. Crear los puntos de venta de cada tienda con su MRDC Code, su almacén, sus métodos de pago (cada uno con código) y su contacto de sincronización (capítulo 9).
6. Registrar cada tienda como instancia (host, puerto, llave API de esa tienda) y probar la conexión (capítulo 6).
7. Si se migra desde un servidor anterior: importar el catálogo con Import All Master Data (capítulo 10).

En cada tienda

1. Instalar mrdc_sync_user y los complementos (mrdc_montegua_stock, mrdc_montegua_purchase).
2. Crear la llave API local que usará el central para entrar (capítulo 8).
3. En la compañía, pestaña MRDC Sync: host y puerto del central, llave API del central, número de instancia, e interruptores de qué se sincroniza (capítulo 7).
4. Configurar el almacén con el mismo MRDC Code que en el central, y marcar una ubicación como puente de traslados (capítulo 7).
5. Crear el contacto Consumidor Final con NIT CF si no existe (lo usa la configuración automática del PDV).
6. Desde el central, sincronizar hacia la tienda: la configuración del PDV, las categorías y los productos (capítulo 11).
7. Hacer una venta de prueba, cerrar la sesión y verificar que llega al central (capítulo 13).

6.Configuración del servidor central

Dos pantallas concentran todo: la pestaña MRDC Sync de la compañía y el registro de instancias.

6.1 El menú del sincronizador

Al instalar el módulo aparece, dentro de la aplicación Punto de Venta, el menú Sincronizador API con cuatro opciones. Solo lo ven los usuarios con el permiso Encargado del sincronizador (capítulo 8):

6.2 La pestaña MRDC Sync de la compañía

En Ajustes → Usuarios y empresas → Empresas, el formulario de la compañía tiene una pestaña nueva:

6.3 Las instancias: una ficha por tienda

En Punto de Venta → Sincronizador API → Instances se registra cada tienda. El nombre se forma solo con el host y el puerto:

7.Configuración de cada tienda

La tienda necesita saber tres cosas: a dónde enviar, con qué llave, y qué flujos tiene permitido enviar.

7.1 La pestaña MRDC Sync de la compañía de la tienda

7.2 Qué se sincroniza y cuándo: los interruptores

Cada familia de documentos tiene un interruptor maestro y una variante «en Vivo»:

7.3 El menú en la tienda

7.4 El almacén y la ubicación puente

8.Llaves API y seguridad

Cada lado guarda una llave propia y conoce la del otro. Los permisos de pantalla se manejan con dos grupos.

8.1 Cómo se autentica la comunicación

Todas las rutas del sincronizador exigen la cabecera API-KEY, verificada por el módulo auth_api_key. La configuración es cruzada:

• En el central se crea una llave API (en Ajustes → Técnico → Auth API Key) asociada a un usuario interno. Esa llave se escribe en el campo MRDC - Sync API Key de cada tienda.
• En cada tienda se crea su propia llave API local. Esa llave se escribe en la ficha de la instancia correspondiente en el central (campo API Key).

Las llaves conviene tratarlas como contraseñas: generarlas largas y aleatorias, guardarlas en el gestor de contraseñas del equipo de TI y rotarlas si se sospecha una filtración (basta actualizar la llave en ambos lados).

8.2 Grupos de permisos

Ambos módulos crean la categoría de permisos «Sincornizador API» en la ficha del usuario, con dos niveles:

• Usuario — nivel base, sin pantallas propias.
• Encargado — ve el menú Sincronizador API, el campo MRDC Sync en los documentos y los botones de sincronización manual (Sincronizar Sesión, Sincronizar Compra, Sincronizar Inventario, Procesar Sincronización…).

9.Cajas, métodos de pago y almacenes

La ficha de cada caja en el central es la fuente de verdad: de ahí sale la configuración que se replica a la tienda.

9.1 El punto de venta en el central

El botón Sincronizar Punto de Venta envía toda esta configuración a la tienda. Con ese mensaje, la tienda se aprovisiona sola:

1. Crea (o encuentra) el usuario local con el correo indicado.
2. Crea (o actualiza) el diario de ventas POS «nombre» Ventas FEL con los datos del establecimiento para la facturación electrónica.
3. Crea (o encuentra) el almacén y el punto de venta con el mismo MRDC Code.
4. Crea los métodos de pago con sus diarios de caja o banco, respetando los códigos.
5. Asigna el cliente por defecto (el contacto con NIT CF).

9.2 Métodos de pago

9.3 Almacenes

10.Carga inicial desde un servidor origen

Para estrenar el central sin capturar el catálogo a mano: se importa todo desde una instancia existente.

Cuando el servidor central es nuevo (por ejemplo, en la migración desde un servidor anterior), el catálogo completo puede importarse desde cualquier instancia que tenga el módulo de tienda instalado. Para eso se marca la instancia con Is Source Server:

Import All Master Data ejecuta todos los importadores en orden de dependencias: categorías de producto → unidades de medida → categorías POS → métodos de pago → almacenes → cajas → proveedores → productos → tarifas de proveedor → listas de materiales → combos. Al terminar escribe en la pestaña Last Sync Info la fecha, el estado (Success, Partial o Error) y un resumen con el conteo por entidad.

• Los productos se importan en lotes de 100 con confirmación parcial: una importación grande que se interrumpa conserva lo ya procesado.
• Los importadores concilian, no duplican: buscan cada registro por su clave (código, NIT, referencia interna) y lo actualizan si ya existe.
• Si una caja del origen tiene sesiones abiertas en el central, sus métodos de pago y su almacén no se tocan (queda una advertencia); ciérrelas y repita la importación.

11.Catálogo: productos y categorías hacia las tiendas

El catálogo se administra una sola vez, en el central. Las tiendas lo reciben — nunca lo editan.

11.1 Categorías del punto de venta

Desde la pestaña MRDC Sync de la compañía, el botón Sincronizar Todas las Categorias envía el árbol completo a todas las instancias en dos pasos automáticos: primero crea todas las categorías y después les asigna su categoría padre. También puede sincronizarse una categoría individual desde su propio formulario:

11.2 Productos

Hay tres formas de enviar productos, para tres situaciones distintas:

11.3 Verificar que llegó

12.Combos, períodos de compra y proveedores

Tres flujos más del catálogo, cada uno con su botón y su regla.

12.1 Combos

Los productos de tipo combo (promociones que agrupan varios productos con precios extra por opción) se sincronizan con Sincronizar Todos los Combos (compañía) o con el botón Sync Product Combos de cada combo. La tienda los recibe con inteligencia de conciliación: reutiliza las opciones existentes en lugar de duplicarlas y nunca borra opciones que aparezcan en ventas históricas.

12.2 Períodos de compra: controlar cuándo puede comprar la tienda

El central puede definir, por producto, una ventana de fechas fuera de la cual las tiendas no pueden confirmar órdenes de compra de ese producto. Se configura en la ficha del producto del central (grupo Período de compra (MRDC Sync): Fecha inicio de compra y Fecha fin de compra) y se envía con el botón Sync Período Compra. Las fechas vacías eliminan la restricción.

12.3 Correos de compra de los proveedores

13.Ventas: el cierre de sesión del POS

El flujo más importante del sistema: cada cierre de caja en la tienda se convierte, en el central, en una sesión real con su factura, sus pagos y su descarga de inventario.

13.1 Qué pasa en la tienda

1. El cajero cierra su sesión de punto de venta con el procedimiento normal de Odoo.
2. Al validar el cierre, el módulo arma automáticamente un resumen de la sesión: ventas agregadas por producto, pagos por método de pago, y por separado las devoluciones y sus pagos. Solo necesita que la caja tenga su MRDC Code.
3. Se crea la petición en la cola (Punto de Venta → Sincronizador API → Sync). Con Sesiones del POS en Vivo activo, se envía en el acto; si no, la envía el automatismo en los siguientes 10 minutos.
4. El campo MRDC Sync de la sesión queda apuntando a esa petición: es la marca de «esta sesión ya se envió».

13.2 Qué construye el central al recibirla

1. Identifica la caja por su MRDC Code; de ella toma la compañía, el almacén, el diario y el Contacto de Sincronización (el cliente de la factura).
2. Crea una sesión de POS real, marcada con el Sync Session ID de la tienda para nunca duplicarla.
3. Crea las órdenes de venta del POS: una con las ventas y, si hubo devoluciones, otra separada que se factura como nota de crédito.
4. Cada línea encuentra su producto por referencia interna; los desconocidos caen al producto genérico. Cada pago encuentra su método por MRDC Code; los desconocidos caen al método genérico.
5. Se factura y se cierra la sesión: eso genera la factura, los pagos, el asiento de cierre con las líneas de valoración de inventario, y los movimientos de stock que descargan el almacén de la tienda en el central.

13.3 Las fechas se respetan

Todo lo que el central construye queda fechado con la fecha real de la sesión en la tienda, no con el día en que llegó el mensaje: el asiento de cierre, los pagos, la diferencia de caja y la valoración de inventario. Una sesión del viernes que se sincroniza el lunes queda contabilizada el viernes. La única excepción: si esa fecha cae en un período contable ya bloqueado, la valoración se registra con la fecha actual y queda una advertencia (capítulo 21).

14.Compras: órdenes, recepciones y devoluciones

La tienda compra localmente; el central recibe la orden, la recepción y las devoluciones, con la analítica de la tienda y las fechas reales.

14.1 El orden obligatorio del flujo

1. La orden de compra viaja primero. Se envía con el botón Sincronizar Compra de la orden, o automáticamente cuando la orden ya tiene recepción parcial o total. El central la crea buscando al proveedor por NIT y al almacén por su código; le aplica la cuenta analítica del almacén y conserva la fecha de confirmación de la tienda.
2. La recepción viaja después, sola. Al validar la recepción en la tienda, si la orden ya está Completed, se envía automáticamente. El central ajusta las cantidades de su recepción pendiente (lo no recibido queda en cero y genera el pendiente automáticamente), la valida con la fecha contable de la tienda y guarda el emparejamiento.
3. Las devoluciones al proveedor (albarán con «Return Picking») viajan igual al validarse, y el central crea la devolución enlazada a la orden de compra original.

15.Traslados entre almacenes

Un traslado interno validado en el central mueve, además, el inventario de las tiendas involucradas — sin intervención de nadie en la tienda.

15.1 Cómo funciona

1. En el central se crea y valida un traslado interno normal entre el almacén origen y el almacén destino (por ejemplo, de la bodega central a una tienda).
2. Al quedar validado, el módulo identifica a qué instancia pertenece cada almacén (por la cadena MRDC Code del almacén → caja con ese código → instancia de la caja) y crea hasta dos envíos: Sync Transfer Out hacia la tienda origen (que descarga su stock) y Sync Transfer In hacia la tienda destino (que lo carga).
3. La tienda que recibe crea un traslado desde su ubicación puente hacia su stock —o al revés para las salidas— y lo valida automáticamente. El inventario de la tienda queda actualizado sin que nadie toque nada.

15.2 Caso práctico: el traslado entre dos tiendas se validó con la instancia equivocada

Es el incidente más común de este flujo, y lo documentamos completo con un caso real. La situación: se validó un traslado del almacén de una tienda (PDV1) al de otra (PDV2). El PDV1 apuntaba correctamente a su servidor (Servidor 1), pero el PDV2 tenía en su Instancia de Sincronización el servidor equivocado: apuntaba al Servidor 6, cuando la tienda del PDV2 en realidad opera en el Servidor 3.

El resultado: la tienda del PDV1 descargó su inventario correctamente, pero la mercadería «entró» en la tienda del Servidor 6 —que no tenía nada que ver— y la tienda verdadera del PDV2 (Servidor 3) nunca recibió nada. El traslado quedó Hecho en el central y ya no se puede desvalidar.

La corrección son tres pasos, en este orden exacto. El orden no es un capricho: mientras la configuración siga mal, todo lo que se haga «pega» en el mismo servidor equivocado que el traslado original — y eso es precisamente lo que se aprovecha para anular el daño exactamente donde ocurrió.

Paso 1 — Revertir el traslado, ANTES de tocar la configuración

Sobre el traslado equivocado, pulse Devolver. En el asistente use Devolver todo (prellena todos los productos con sus cantidades exactas) y valide la devolución que se genera: el traslado inverso, de PDV2 hacia PDV1.

Paso 2 — Corregir el punto de venta

Ahora sí: en el PDV2, cambie la Instancia de Sincronización al servidor correcto (Servidor 3) y verifique de paso la cadena completa de mapeo: el MRDC Code del almacén y el Código de Sincronización del PDV deben ser el mismo, y la instancia debe apuntar al host de la tienda verdadera.

Paso 3 — Hacer el traslado correcto

Cree y valide un traslado nuevo, idéntico al original (PDV1 → PDV2). Esta vez la salida viaja al Servidor 1 —que vuelve a descargar— y la entrada viaja al Servidor 3, que recibe y valida automáticamente. La mercadería queda, por fin, en la tienda que era.

Verificación final — antes de dar el caso por cerrado, confirme las existencias de los productos involucrados en los tres lugares:

• Tienda del PDV1 (Servidor 1): descargada una sola vez (el efecto del traslado definitivo).
• Tienda equivocada (Servidor 6): en cero — la entrada errónea y su anulación se cancelan.
• Tienda del PDV2 (Servidor 3): exactamente las cantidades del traslado.

16.Inventarios físicos y mermas

La tienda cuenta; el central refleja el mismo ajuste, guardando tanto lo contado como la existencia teórica que la tienda tenía al momento de contar.

16.1 Inventario físico

1. En la tienda se crea el inventario (menú de ajustes de inventario), se inicia y se capturan las cantidades contadas.
2. Al pulsar Validar, el módulo toma una fotografía de cada línea —producto, cantidad contada y cantidad teórica del momento— y la envía junto con el ajuste.
3. El central crea un inventario espejo (nombre «… - MRDC Sync [id]»), aplica las cantidades y lo valida. Los servicios y los combos se omiten automáticamente.

16.2 Mermas (scrap)

Los desechos registrados y validados en la tienda viajan igual: producto, cantidad, motivo y almacén. El central registra el scrap y lo valida contra la ubicación de stock de esa tienda.

17.La cola de sincronización y los reintentos

La cola es el tablero de control diario: aquí se ve qué salió, qué falló y por qué, y desde aquí se reintenta.

17.1 Anatomía de un registro de la cola

En ambos lados, cada envío es un registro con la misma estructura: nombre descriptivo, empresa, fecha, endpoint de destino, estado, número de intentos, y tres pestañas: Payload (lo que se envió), Response (lo que respondió el otro lado) y Connection Info (host, puerto y llave usados, de solo lectura):

17.2 Cómo se reintenta

• Automático (tienda): el automatismo «Sincronizar Cola Requests» corre cada 10 minutos y procesa hasta 30 registros no completados por corrida, los más antiguos primero. Cada tipo de envío se reintenta hasta 3 veces — excepto las sesiones de POS, que se reintentan sin límite hasta entrar.
• Manual (ambos lados): el botón Sincronizar Ahora del registro, o la acción del mismo nombre sobre una selección en la vista de lista. Un registro Completed no se reenvía aunque se pulse el botón (con la excepción del capítulo 15: no lo intente con Transfer In).

18.Los registros de sincronización (logs)

Si la cola cuenta lo que salió, el log cuenta lo que llegó. Juntos reconstruyen cualquier historia.

Tres hábitos que ahorran horas:

• Filtre por nivel Error y Warning al inicio del día: un envío «exitoso con advertencias» (por ejemplo, un método de pago saltado) solo se descubre aquí.
• El JSON recibido es evidencia. Ante un «esta venta no cuadra», el payload guardado en el log muestra exactamente qué reportó la tienda y cuándo.
• Los logs son historia valiosa. A partir de ellos puede reconstruirse información (por ejemplo, las cantidades teóricas de inventarios pasados). No los depure sin respaldo.

19.Automatizaciones programadas

Siete tareas programadas mantienen el sistema andando aunque nadie pulse un botón.

En cada tienda (cada 10 minutos)

En el central (cada 15 minutos)

Consecuencia práctica: sin los interruptores «en Vivo», el retraso normal entre un evento en la tienda y su llegada al central es de hasta 20 minutos (una corrida para encolar y otra para enviar). Con «en Vivo», es inmediato y el automatismo queda como red de seguridad.

20.Resolución de problemas

Los errores del sincronizador casi siempre son de emparejamiento. Esta tabla los resume con su causa y su solución.

Las dos operaciones que exigen cuidado especial

• Transfer In (capítulo 15): reenviar uno completado duplica stock en la tienda. Reintente solo registros fallidos, una vez, verificando el resultado.
• Mermas: el receptor del central no guarda la marca de idempotencia del scrap, así que reenviar una merma ya procesada crearía un segundo descarte. El flujo normal (envío único automático al validar) es seguro; simplemente no reenvíe mermas completadas.

21.Buenas prácticas de operación

Reglas simples que mantienen el sistema sano.

• El catálogo se edita solo en el central. Productos, precios, proveedores, listas de materiales, categorías y combos. Lo que se edite en una tienda se perderá en la siguiente sincronización.
• Revisión diaria de 5 minutos: en el central, la cola sin Failed y el log sin errores; en cada tienda (o por muestreo), lo mismo. Un Failed atendido el mismo día es trivial; acumulado una semana, es una conciliación.
• Toda tienda nueva empieza por los códigos (capítulo 4) y termina con una venta de prueba verificada en el central.
• Coordine los cierres contables. Antes de bloquear un período en el central, confirme que no queden sesiones, recepciones o inventarios de ese período pendientes de sincronizar en las tiendas: las colas deben estar vacías. Así todo queda fechado en su día real.
• Prefiera «Sincronizar Productos Faltantes» para el mantenimiento diario del catálogo; es el envío más liviano y no toca lo que ya está bien. Reserve «Sincronizar Todos los Productos» para cargas iniciales o correcciones masivas.
• No borre registros de cola ni de log como limpieza rutinaria: son la evidencia y, en algunos casos, la única fuente para reconstruir datos históricos.
• Cambios de configuración de cajas, siempre desde el central con «Sincronizar Punto de Venta». El sistema puede actualizar categorías disponibles de una caja incluso con la sesión abierta; los cambios se ven al recargar el POS.
• Documente las llaves API y quién tiene el grupo Encargado en cada instancia.

22.Referencia rápida de endpoints

Para el equipo técnico: qué ruta atiende cada flujo. Todas responden JSON y exigen la cabecera API-KEY (salvo la anotada).

Rutas que atiende el servidor central (las tiendas le envían)

Rutas que atiende cada tienda (el central le envía)