Integrar POS con inventario de vinos: guía práctica

El POS y el inventario no observan lo mismo

Para integrar el POS con el inventario de vinos, empieza por una frontera: el POS registra pedidos, cargos, pagos, anulaciones y reembolsos; el inventario registra unidades físicas, botellas abiertas, ubicaciones, propiedad y movimientos.

Una línea de venta no identifica automáticamente qué botella salió. Un refund no demuestra que una unidad volvió al rack. Y una copa vendida no equivale a una botella completa.

Esta guía cubre la especialización de vino: añada, formato, copeo, botella individual y locker de socio. La implantación general del restaurante se explica en integrar POS e inventario, y las alternativas de topología en middleware para restaurante.

Define el resultado antes de conectar

Escribe casos verificables:

• una botella de carta servida reduce una unidad del SKU y sitio correctos;
• una copa reduce mililitros o equivalentes según la receta vigente;
• una cortesía servida conserva consumo aunque el ingreso sea cero;
• un void antes de servir no reduce existencia;
• un refund no repone sin devolución física confirmada;
• una botella de socio sale de su locker sin convertirse en venta de inventario del restaurante;
• un evento duplicado no descuenta dos veces;
• un evento offline queda visible hasta sincronizar o resolver.

“Sincronizar en tiempo real” no es un resultado suficiente. Define latencia aceptable, estado pendiente, responsable y recuperación.

Una fuente de verdad por entidad

Evita dos maestros que se sobrescriben.

Entidad	Fuente sugerida	Copia o consumidor
ítem y variación vendible	POS o catálogo designado	inventario recibe mapeo
precio e impuestos	POS	inventario puede consultar
cantidad física	inventario	POS recibe disponibilidad si procede
botella individual	inventario	POS referencia ID cuando el flujo lo permite
socio y locker	sistema de cava	POS recibe relación mínima autorizada
pedido, void, comp y refund	POS	inventario procesa eventos
costo contable	sistema financiero/inventario designado	POS no lo recalcula

La matriz no es universal. Elige y documenta. Si el POS crea el producto y el inventario lo edita después, define qué atributos puede enriquecer sin devolver cambios que generen un bucle.

Contrato de identidad

El nombre visible no basta. Mapea IDs:

• location_id de sucursal;
• pos_item_id;
• pos_variation_id;
• inventory_sku_id;
• GTIN si existe;
• añada y formato;
• unidad vendible y almacenable;
• lote cuando se controla;
• serial o ID interno para botella individual;
• member_id y locker_id como relaciones autorizadas, no texto del SKU.

Square Catalog API separa ITEM de ITEM_VARIATION. Una etiqueta puede ser el ítem y “botella 750 ml” o “copa” variaciones vendibles. El mapeo debe usar IDs, no coincidencia de nombres.

Las especificaciones GS1 distinguen GTIN para la clase comercial y GTIN más serial para una instancia. Un GTIN no señala qué botella de un locker salió.

No dupliques un maestro completo en ambos sistemas. Conserva un mapa con estado activo, huérfano, conflicto o retirado y una bitácora de cambios.

Botella, copa e instancia

Venta por botella

La variación vendible y la unidad almacenable pueden ser una botella del formato definido. El evento reduce cantidad cuando el servicio físico se confirma según la política.

Venta por copa

Square documenta el caso de una variación de vino por botella frente a una por copa. Para inventario necesitas convertir la copa a mililitros o fracción de botella.

Define:

• tamaño de servicio;
• unidad base;
• botella abierta vigente;
• fecha y versión de receta;
• remanente;
• merma o muestra separada.

No uses 4.5 o 5 copas por botella como verdad universal.

Cava privada

La venta puede ser un cargo de servicio o descorche, mientras el movimiento físico retira una botella propiedad del socio. La línea POS y la instancia se vinculan, pero no tienen el mismo significado contable.

El locker y titular no deben viajar en texto libre ni aparecer en tickets más allá de lo necesario.

Decide cuándo ocurre el movimiento

Un pedido pasa por estados: creado, abierto, enviado, completado, cancelado o reembolsado, según la plataforma. El inventario necesita un punto efectivo.

Opciones:

• al agregar el ítem: demasiado pronto para consumo definitivo;
• al enviar a preparación: útil para reserva, no necesariamente salida;
• al confirmar servicio físico: cercano al hecho, requiere acción operativa;
• al cerrar la cuenta: simple, pero puede retrasar el saldo;
• al completar pago: pago e inventario no siempre coinciden.

Una arquitectura puede reservar al enviar y consumir al servir. Si la cuenta se cancela, libera la reserva. Documenta estados y transiciones.

Matriz de eventos y efecto

Evento POS/operativo	Efecto de inventario	Nota
pedido creado	ninguno o reserva	no asumir servicio
botella servida y confirmada	consume 1 unidad	SKU, sitio o instancia correctos
copa servida	consume volumen	receta versionada
comp después de servir	conserva consumo	ingreso puede ser cero
void antes de servir	sin consumo	libera reserva si existe
void después de servir	evento de corrección o merma	exige motivo; no repone solo
refund	no repone automáticamente	requiere devolución física aceptada
devolución física	entrada condicionada	estado vendible, cuarentena o descarte
cuenta reabierta	no borra historia	genera compensaciones
servicio de socio	retira instancia de locker	cargo comercial separado

No elimines el evento original. Una corrección usa un evento compensatorio vinculado.

Contrato técnico del evento

Cada mensaje debería incluir:

• event_id único;
• tipo y versión del esquema;
• sistema de origen;
• ubicación;
• hora efectiva y zona;
• hora emitida y recibida;
• pedido, línea y versión;
• ítem, variación y mapeo;
• cantidad y unidad;
• estado anterior y posterior;
• actor o dispositivo cuando proceda;
• referencia a evento compensado;
• metadatos mínimos de trazabilidad.

No transportes credenciales, datos completos del socio ni información de tarjeta.

Un consumidor debe validar esquema, firma, versión, mapeo y transición antes de aplicar.

Idempotencia y reintentos

Los webhooks son asíncronos. Square advierte que pueden llegar duplicados y fuera de orden; exige respuesta rápida y reintenta entregas.

Reglas:

1. guarda event_id antes o junto con el efecto;
2. si vuelve a llegar, responde éxito sin repetir consumo;
3. usa control transaccional o outbox/inbox;
4. conserva estado de procesado, error y cuarentena;
5. no deduzcas unicidad del número de pedido solamente.

Una cuenta puede tener varias líneas, cantidades y reembolsos parciales. La clave idempotente debe distinguir el efecto exacto.

Orden y concurrencia

Un refund puede llegar antes que la notificación de completed. Dos meseros pueden intentar servir la última botella.

Usa:

• versión de pedido o recurso;
• secuencia cuando el proveedor la ofrece;
• validación de transición;
• reserva o bloqueo optimista;
• cola de eventos pendientes de predecesor;
• compensación para efectos ya aplicados.

No apliques “gana el último” sin detectar conflicto. La última hora de recepción no necesariamente es la última hora efectiva.

Offline y fallos

El POS o inventario puede quedar sin red. Define qué operaciones siguen:

• POS cobra offline según sus capacidades y riesgo;
• aplicación de cava captura servicio pendiente;
• ID del evento se crea en origen;
• la cola es durable y visible;
• el sistema reintenta con backoff;
• el gerente ve antigüedad y errores;
• al reconectar, se valida estado y mapeo.

Un formulario en papel puede ser último recurso. Limita datos personales, numera registros y concilia después. No dependas de memoria.

Un timeout no significa fracaso. Antes de reintentar una operación no idempotente, consulta el estado o usa la misma clave.

Seguridad de la integración

• OAuth o credenciales con permisos mínimos;
• secretos fuera del código y rotación;
• verificación de firma del webhook;
• TLS;
• lista de endpoints y versiones autorizadas;
• bitácora de cambios de mapeo;
• separación de ambientes prueba/producción;
• datos personales mínimos;
• retención definida para payloads;
• alertas por fallos y reintentos.

No registres payloads completos de pago o cliente para depurar inventario. Enmascara y controla acceso.

Matriz de pruebas

Ejecuta extremo a extremo:

• una botella;
• varias botellas en una línea;
• varias líneas del mismo vino;
• copa con receta vigente;
• comp antes y después de servir;
• void antes y después de servir;
• refund parcial y total;
• devolución física vendible y no vendible;
• cuenta reabierta;
• botella de socio y cargo de servicio;
• evento duplicado;
• evento fuera de orden;
• timeout después de aplicar;
• credencial expirada;
• mapeo huérfano;
• dos solicitudes por última unidad;
• desconexión y sincronización tardía.

Para cada caso define saldo inicial, eventos, saldo esperado y evidencia. Repite tras cambios de versión.

Conciliación diaria por líneas y unidades

Comparar “20 tickets contra 20 movimientos” falla si un ticket contiene varias botellas, copas o refunds.

Concilia:

• pedido y línea POS;
• versión y estado;
• cantidad y unidad;
• evento de inventario;
• SKU o instancia;
• sitio;
• estado de procesamiento;
• compensaciones.

Clasifica excepciones:

• sin mapeo;
• duplicado;
• pendiente de orden;
• error de unidad;
• transición inválida;
• inventario insuficiente;
• servicio sin cargo;
• cargo sin servicio;
• devolución sin recepción física;
• cola offline vencida.

La conciliación digital no sustituye el conteo físico. El sistema puede estar perfectamente sincronizado y partir de un saldo inicial equivocado.

Observabilidad

Mide:

• eventos recibidos, procesados y rechazados;
• duplicados;
• latencia efectiva y de entrega;
• antigüedad de cola;
• mapeos huérfanos;
• reintentos por endpoint;
• diferencias por unidad;
• compensaciones;
• discrepancias reabiertas.

Incluye un ID de correlación desde POS hasta inventario. Un log que dice “sync failed” sin pedido, línea ni evento no permite investigar.

Evita canibalización con la integración general

La guía general decide plataforma, responsables y despliegue. Este artículo debe conservar la especialización:

• ítem y variación de vino;
• añada y formato;
• copeo y botella abierta;
• botella individual;
• socio y locker;
• comp, void y refund después del servicio;
• reconciliación física.

No repitas una lista de proveedores o un “paso a paso en horas”. La arquitectura depende de APIs, planes y flujo real.

Límites de Kavasoft

Al evaluar Kavasoft para restaurantes, confirma POS compatibles, endpoints, eventos, roles, unidades, offline, importación, exportación y evidencias del plan contratado. Kavasoft puede procesar movimientos cuando la integración y configuración lo permiten; no garantiza que cada POS emita el evento necesario ni que cada botella física se haya servido correctamente.

Lista de control

• Cada entidad tiene una fuente de verdad designada.
• Ítem, variación, SKU, GTIN e instancia están separados.
• Añada, formato, copa y botella tienen mapeos y unidades.
• El momento de reserva y consumo está documentado.
• Comp, void, refund, devolución y reapertura tienen efecto explícito.
• El event_id evita dobles descuentos.
• Eventos fuera de orden y concurrencia se detectan.
• La cola offline es durable, visible y conciliable.
• Webhooks verifican firma y usan mínimos permisos.
• La reconciliación opera por línea, unidad e instancia.
• Conteos físicos validan el saldo digital.

Fuentes oficiales

• Square Catalog API: What it does
• Square Orders API
• Square Webhooks Overview
• GS1 General Specifications

Contenido relacionado

• Inventario de vinos y carta digital
• Control de inventario de vinos