Conectar TPV con PrestaShop (Square, Zettle, SumUp): documentación

Funcionamiento

PrestaShop es la referencia del stock. Cada cambio de stock de un producto asociado se envía al TPV como cantidad absoluta. Cada venta del TPV se importa, se descuenta del stock de PrestaShop con el motivo de movimiento «Venta en TPV» y el nuevo nivel vuelve a los demás TPV. Las devoluciones reponen los artículos en stock con el motivo «Devolución en TPV».

• Square: stock en ambos sentidos, ventas, devoluciones, envío del catálogo.
• Zettle by PayPal: stock en ambos sentidos, ventas, reembolsos, envío del catálogo.
• SumUp: solo importación de ventas. La API pública de SumUp no expone ni stock ni catálogo.

Requisitos

• PrestaShop 8.0 a 9.x.
• Una tarea cron en tu alojamiento.
• HTTPS en la tienda para el webhook de Zettle.
• Una cuenta de Square, Zettle o SumUp con acceso de desarrollador.

Instalación

1. En Módulos > Gestor de módulos, haz clic en Subir un módulo y envía el ZIP.
2. El módulo añade el menú Catálogo > Conector de TPV.
3. El panel muestra una lista «Puesta en marcha» que se va marcando a medida que configuras el módulo.

Conectar tus TPV

Abre la pestaña Conexiones. Cada TPV tiene su propio bloque con una casilla Activado. Las credenciales se cifran en la base de datos: un campo vacío conserva el valor guardado.

Square

1. Crea una aplicación en el Square Developer Dashboard y copia su token de acceso de producción.
2. Pégalo en Token de acceso, elige el entorno, guarda y haz clic en Probar la conexión.
3. Elige el local que recibe el stock. Si tienes varios, marca aquellos cuyas ventas deben importarse (10 como máximo).
4. Para la importación instantánea, crea una suscripción webhook al evento order.updated con la URL de notificación mostrada y pega la clave de firma en el módulo. La URL debe ser idéntica en ambos lados.

Zettle by PayPal

1. En el Zettle Developer Portal, crea una clave API self-hosted con los scopes READ:PURCHASE, READ:PRODUCT, READ:USERINFO y WRITE:PRODUCT.
2. Introduce el Client ID y la clave API, guarda y prueba la conexión.
3. Haz clic en Activar el webhook para recibir las ventas en pocos segundos.
4. El control de stock debe estar activado en los productos de Zettle. Los productos enviados por el módulo lo tienen automáticamente.

SumUp

1. Introduce tu clave API secreta (sup_sk_...), guarda y prueba la conexión. El código de comercio se detecta automáticamente.
2. Las ventas de SumUp se asocian por nombre de artículo: referencia exacta o nombre exacto de un producto sin combinaciones.

Reglas de sincronización

En la parte superior de la pestaña Conexiones:

• Enviar los niveles de stock de PrestaShop al TPV y, opcionalmente, justo después de cada cambio.
• Importar las ventas del TPV y descontarlas del stock de PrestaShop.
• Reponer en stock los artículos devueltos (Square y Zettle).
• Asociación automática por referencia, por EAN-13 / UPC y por nombre para SumUp.
• Importar las ventas del TPV desde: las ventas anteriores se ignoran. Una venta ya importada nunca se duplica.

Tarea programada y webhooks

El panel muestra dos URL. Programa la primera cada 5 minutos y la segunda (con full=1) una vez por noche:

*/5 * * * * curl -s "https://tu-tienda.com/module/dfposconnector/cron?token=TU_TOKEN" >/dev/null
0 3 * * * curl -s "https://tu-tienda.com/module/dfposconnector/cron?token=TU_TOKEN&full=1" >/dev/null

El cron importa las nuevas ventas, envía el stock pendiente y detecta las diferencias creadas fuera de PrestaShop (importación SQL, ERP). La sincronización nocturna reenvía todos los niveles asociados. El cron y los webhooks también funcionan en modo mantenimiento.

Asociar los productos

Pestaña Correspondencia de productos:

• Leer el catálogo de Square o Zettle: asocia automáticamente por SKU y código de barras.
• Sugerir productos por nombre: propone un producto para cada artículo restante, con una puntuación. Las sugerencias del 90 % o más se pueden aceptar en bloque, las demás una a una.
• Asociación manual: busca un producto por nombre, referencia o EAN.
• Enviar todo el stock al TPV, o importar el stock del TPV a PrestaShop (úsalo una sola vez, en la puesta en marcha, si el stock del TPV es el fiable).

Enviar el catálogo al TPV

Pestaña Envío del catálogo: elige el TPV, una categoría (subcategorías incluidas), el precio enviado (con o sin IVA, sin descuentos) y si solo se envían los productos activos.

1. Comprobar qué se enviará lee primero el catálogo del TPV y asocia lo que ya existe, y luego muestra el número de productos y variantes que se crearán.
2. Crearlos en el TPV envía los productos por lotes con una barra de progreso. Las combinaciones se convierten en variantes. Cada artículo creado queda asociado y recibe su stock.

No se envían: los productos ya asociados en ese TPV, los productos virtuales, los packs, las imágenes ni las categorías. Zettle acepta como máximo 99 variantes por producto.

Control de stock

La pestaña Control de stock lee las cantidades reales de Square o Zettle y lista las diferencias con PrestaShop, de mayor a menor. Para cada línea:

• Enviar el stock de PrestaShop: el TPV recibe el valor de PrestaShop.
• Usar el stock del TPV: PrestaShop recibe el valor del TPV, con un movimiento de stock.

Pedidos de PrestaShop para las ventas en tienda

Bloque Pedidos de PrestaShop, desactivado por defecto. Una vez activado, cada venta con todos sus artículos asociados crea un pedido:

• cliente de mostrador dedicado con la dirección de la tienda;
• transportista gratuito «Venta en TPV», nunca ofrecido en el checkout;
• precios del ticket, repartiendo entre las líneas un descuento global;
• pedido fechado a la hora de la venta, con la referencia del TPV en la nota interna;
• estado «Venta en TPV» (pagado, entregado, sin factura ni email), modificable en los ajustes.

En ese caso es el pedido el que descuenta el stock. No se envía ningún email durante la creación. Una venta con artículos sin asociar no recibe pedido: sus artículos asociados se descuentan directamente.

Registro de ventas

La pestaña Ventas TPV lista cada venta con sus líneas, TPV, local, pago y, si procede, el enlace al pedido. Filtros: TPV, estado (por asociar, asociadas, devoluciones, con pedido), búsqueda por ticket, artículo o local, rango de fechas. El botón Exportar CSV exporta la selección, una fila por artículo.

Alertas por email

Bloque Alertas por email: se envía un email cuando la sincronización programada falla 3 veces seguidas (como máximo uno cada 6 horas) y otro cuando vuelve a funcionar. Deja la dirección vacía para usar la de la tienda. El botón Enviar una alerta de prueba comprueba el envío.

Resolución de problemas

«Inventario no inicializado» en Zettle

Activa el control de stock en al menos un producto de Zettle, o envía un producto desde la pestaña Envío del catálogo.

Webhook de Square rechazado (firma no válida)

La URL de notificación declarada en Square debe coincidir carácter por carácter con la del módulo, y la clave de firma debe pertenecer a esa suscripción.

El stock no se envía tras un cambio en el back office

PrestaShop no ejecuta los hooks de un módulo para un empleado sin el permiso «Ver» sobre ese módulo. El control de diferencias del cron recupera esos cambios en la siguiente ejecución. También puedes conceder el permiso en Parámetros avanzados > Equipo > Permisos.

Una venta no ha creado pedido

El registro técnico indica el motivo: artículos sin asociar, moneda de la venta ausente en PrestaShop, restricción de transportista en un producto o cantidad inferior a una unidad. En ese caso el stock se descontó directamente.

Desinstalación

La desinstalación elimina las tablas del módulo (correspondencias, registro de ventas, cola, registro técnico) y sus ajustes, y desactiva el transportista «Venta en TPV». Los pedidos creados, el estado de pedido, el cliente de mostrador y los motivos de movimiento de stock se conservan, porque el historial hace referencia a ellos.