Conectar TPV con PrestaShop (Square, Zettle, SumUp): documentación
Instalar el módulo, conectar Square, Zettle o SumUp, asociar los productos y sincronizar stock y ventas entre el TPV y PrestaShop.
Funcionamiento
El módulo conecta PrestaShop con tu TPV Square, Zettle by PayPal o SumUp. Importa cada venta, devolución y reembolso del TPV en un registro, actualiza el stock en el sentido que elijas y puede convertir cada venta en un pedido de PrestaShop. También puede enviar tu catálogo de PrestaShop al TPV.
El stock se sincroniza en uno de estos tres sentidos, que se ajusta por TPV:
- De la tienda al TPV: PrestaShop es la referencia. Las ventas del TPV se descuentan en PrestaShop y luego el nuevo nivel vuelve al TPV.
- Del TPV a la tienda: el TPV es la referencia. PrestaShop toma las cantidades del TPV en cada ejecución del cron y con cada webhook de stock.
- Bidireccional: los cambios hechos en cada lado desde la última sincronización se suman. Una venta en línea y una venta en tienda cuentan una sola vez cada una.

Lo que admite cada TPV
- Square: ventas, devoluciones y reembolsos, stock en los tres sentidos, varios locales, envío del catálogo con la imagen principal, webhooks firmados.
- Zettle by PayPal: ventas y reembolsos, stock en los tres sentidos, envío del catálogo, webhook firmado creado por el módulo.
- SumUp: ventas y reembolsos, descontados del stock de PrestaShop. La API pública de SumUp no expone stock, ni catálogo, ni webhook de las ventas en TPV. La importación pasa por el cron, y el stock que muestra SumUp no se actualiza.
El módulo no sustituye a tu TPV y no lo convierte en una caja certificada. Los tickets, el cierre de caja y las obligaciones fiscales siguen a cargo de Square, Zettle o SumUp.
Requisitos
- PrestaShop 1.7.8 a 9.x. El módulo se ha probado en PrestaShop 1.7.8.11 (PHP 7.4), 8.2.1 (PHP 8.1) y 9.1.5 (PHP 8.5).
- Una tarea cron en tu alojamiento.
- Una tienda en HTTPS para los webhooks y para la conexión OAuth.
- Una cuenta de Square, Zettle o SumUp, y acceso a su espacio de desarrollador si te conectas con un token o una clave API.
Instalación y actualización
- En Módulos > Gestor de módulos, haz clic en Subir un módulo y envía el ZIP.
- El módulo añade el menú Catálogo > Conector de TPV. El panel muestra una lista Primeros pasos que se va marcando a medida que configuras el módulo.
Para pasar de una versión 1.x a la 2.0.0, envía el nuevo ZIP de la misma manera. La actualización conserva las correspondencias, el registro de ventas, las conexiones, los cursores de importación (ninguna venta se vuelve a importar) y los ajustes. Las URL de webhook existentes siguen siendo válidas. La actualización añade las nuevas tablas, vuelve a cifrar los secretos antiguos y quita del estado «Venta en TPV» el indicador de envío que provocaba un segundo pago. Los pedidos ya creados no se modifican.
Conectar tus TPV
La pestaña Conexiones muestra el estado de cada TPV y las funciones disponibles. Cada TPV tiene su propio asistente. Los secretos se guardan cifrados y nunca se vuelven a mostrar ni se escriben en el registro. Un campo vacío conserva el valor guardado.

Square
- Elige el modo de conexión. Se recomienda OAuth: autorizas el módulo desde tu cuenta de Square y el token se renueva automáticamente. Para una sola tienda, también puedes pegar un token de acceso personal.
- Con OAuth, introduce el ID y el secreto de tu aplicación de Square, y declara en esa aplicación la URL de redirección que se muestra. El módulo solo pide los permisos necesarios: lectura de locales, pedidos, pagos, catálogo, stock y clientes, y escritura de catálogo y stock.
- Haz clic en Conectar con Square, acepta los permisos y luego en Probar la conexión.
- Elige el local que lleva el stock y marca aquellos cuyas ventas se importan (10 como máximo).
- Para la importación instantánea, añade en Webhooks > Subscriptions la URL de notificación que se muestra con los eventos
order.updated,refund.created,inventory.count.updatedyoauth.authorization.revoked, y pega la clave de firma en el módulo. La URL debe ser idéntica, carácter por carácter, en ambos lados.

El botón de conexión OAuth te lleva a la página de autorización del TPV, en su propio sitio, y luego te devuelve al módulo. La captura siguiente se tomó en modo demostración, con una pantalla de autorización simulada.


Zettle by PayPal
- Para una sola tienda, se recomienda la clave API self-hosted: créala en el Zettle Developer Portal y pégala con su ID de cliente. También se ofrece una conexión OAuth para una aplicación de partner, con renovación automática de los tokens.
- Guarda y luego prueba la conexión.
- Haz clic en Activar el webhook: el módulo crea él mismo la suscripción (
PurchaseCreated,InventoryBalanceChanged) y guarda cifrada su clave de firma. Zettle exige una tienda en HTTPS. - El seguimiento de stock debe estar activado en los productos de Zettle. Los productos enviados por el módulo lo tienen automáticamente.

SumUp
- Pega tu clave API secreta (panel de SumUp, Developers > API keys) con tu código de comercio, o conéctate con OAuth.
- Prueba la conexión. El código de comercio se lee automáticamente si falta.
- SumUp no envía webhook para las ventas en TPV: el cron las importa cada 5 minutos. Se asocian por referencia o por nombre de artículo.

Desconectar un TPV
El botón Desconectar revoca los tokens cuando el TPV lo permite (Square, Zettle) y los elimina de PrestaShop. Las correspondencias y el registro de ventas se conservan.
Sentido del stock
En Ajustes > Stock, elige el sentido del stock para Square y para Zettle: de la tienda al TPV, del TPV a la tienda, bidireccional o sin sincronización de stock. En SumUp, las ventas se descuentan del stock de PrestaShop, pero su TPV no recibe stock.
- Solo un TPV puede ser la referencia del stock. Si eliges un segundo, el módulo lo ajusta en Bidireccional.
- En bidireccional, la fuente de verdad decide la primera alineación y los conflictos.
- Un nivel escrito por el módulo nunca se reenvía, para evitar ecos. Cuando el TPV ya contabiliza sus propias ventas, la importación no las descuenta una segunda vez.
- La opción Enviar justo después de cada cambio de stock en PrestaShop envía el nivel al momento. Si no, sale en la siguiente ejecución del cron.

Asociar los productos
La pestaña Correspondencias vincula cada artículo del TPV con un producto o una combinación de PrestaShop.
- Leer el catálogo de Square o Zettle: los artículos se asocian automáticamente por SKU (referencia del producto o de la combinación) y por código de barras EAN-13 / UPC.
- Sugerencias por nombre: para cada artículo restante, el módulo propone el producto más parecido con una puntuación. Las sugerencias del 90 % o más se pueden aceptar de una vez, las demás una a una. Ninguna sugerencia se guarda sin tu validación.
- Asociación manual: busca un producto por nombre, referencia o EAN.
- Un artículo vendido en el TPV pero ausente del catálogo leído también aparece en la cola. Puedes ocultarlo si no se vende en línea.

Asociar un artículo recupera el stock de las ventas ya importadas, una sola vez. Las líneas de venta anteriores se vinculan a la nueva regla.
Enviar el catálogo al TPV
La pestaña Catálogo crea tus productos de PrestaShop en Square o Zettle: combinaciones como variantes, precio, SKU, código de barras, imagen principal como opción y luego stock. Elige el TPV, una categoría (subcategorías incluidas), el precio enviado (con o sin IVA, sin descuentos) y si solo se tienen en cuenta los productos activos.
- Comprobar lo que se enviará lee primero el catálogo del TPV, asocia por SKU o código de barras lo que ya existe y luego muestra el número de productos y variantes que se crearán.
- Marca la confirmación y luego Crearlos en el TPV: los productos salen por lotes, con una barra de progreso, y cada artículo creado queda asociado al momento.

Los artículos existentes del TPV nunca se modifican. En Square, cada artículo se vincula a un impuesto de Square existente con el mismo tipo: no se crea ningún impuesto. Los productos virtuales y los packs se excluyen, y las categorías no se envían. Zettle acepta como máximo 99 variantes por producto. SumUp no puede recibir productos por su API.
Control del stock y conciliación
La pestaña Stock compara el stock de PrestaShop y el stock del TPV para cada artículo asociado, y lista las diferencias. Para cada diferencia, o para una selección:
- Conservar PrestaShop: el TPV recibe la cantidad de PrestaShop.
- Conservar el TPV: PrestaShop recibe la cantidad del TPV, con un movimiento de stock.
La sincronización completa nocturna lanza una conciliación y guarda su informe. Los informes anteriores siguen disponibles. Importar todos los niveles del TPV sobrescribe el stock de PrestaShop de cada producto asociado: úsalo una sola vez, en la puesta en marcha, si el stock del TPV es el más fiable.

Ventas en TPV
La pestaña Ventas en TPV lista cada ticket con sus líneas, su TPV, su local, su pago, su IVA por línea, su propina y, si procede, el pedido de PrestaShop. Filtros: TPV, tipo (ventas, devoluciones y reembolsos, pedidos de PrestaShop), diferencias de importe, búsqueda por ticket, artículo, local o número de pedido, y rango de fechas. Exportar CSV exporta la selección.

La importación es idempotente: una venta ya importada nunca se duplica, aunque llegue por varios webhooks y por el cron al mismo tiempo. Los tickets registrados sin conexión en el TPV y transmitidos más tarde también se importan. Las ventas anteriores a la fecha indicada en Importar las ventas del TPV desde se ignoran.
Pedidos de PrestaShop para las ventas en tienda
En Ajustes > Pedidos y reembolsos, la opción Crear un pedido de PrestaShop para cada venta en TPV cuyos artículos estén todos asociados está desactivada por defecto. Una vez activada:
- un cliente de mostrador por tienda, con la dirección de la tienda;
- un transportista gratuito «Venta en TPV», nunca ofrecido en el checkout;
- el método de pago «TPV – Square / Zettle / SumUp», un solo pago y un pedido con la fecha y hora de la venta;
- los precios y descuentos del ticket, repartidos entre las líneas;
- la propina fuera del total del pedido, anotada en su nota;
- ningún email, ni al cliente ni a ti.
El estado por defecto es «Venta en TPV» (pagado, entregado, sin email ni factura). Si PrestaShop calcula un total distinto del ticket (reglas de impuestos, redondeos), la diferencia se muestra en la venta y se anota en el registro.

- Permitir facturas para los pedidos del TPV: desactivado por defecto, porque el TPV ya entrega el recibo. Sin esta opción, se rechaza un estado que genere una factura. Con ella, la factura se crea sobre el pago existente y se indica en el registro.
- Clientes identificados (Square): el pedido puede vincularse al cliente de PrestaShop existente que tenga la misma dirección de email que el cliente de Square. Solo se usa un cliente existente con una dirección: no se crea ningún cliente ni ninguna dirección.

Una venta que contiene artículos sin asociar no recibe pedido: sus artículos asociados se descuentan directamente del stock.
Devoluciones y reembolsos
Las devoluciones de Square, los reembolsos de Zettle y los reembolsos de SumUp se importan, parciales incluidos. Los artículos devueltos se reponen en stock una sola vez, mediante la línea de devolución. Un reembolso sin artículo devuelto no modifica el stock. En el pedido original, elige:
- Solo una nota en el pedido (por defecto);
- Factura por abono por los artículos devueltos o el importe reembolsado;
- Factura por abono y estado «Reembolsado» cuando el pedido se ha reembolsado por completo.

Tareas programadas y webhooks
Ajustes > Tareas programadas muestra la URL del cron. Llámala cada 5 minutos, y la misma URL 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 procesa la cola de webhooks, importa las nuevas ventas, renueva los tokens y envía los niveles de stock pendientes. Dos ejecuciones nunca se solapan. La ejecución nocturna reenvía todos los niveles asociados y genera el informe de conciliación.
Cada webhook se controla antes de aceptarse:
- la clave de URL propia de los webhooks, distinta del token del cron;
- la firma del TPV;
- un tamaño máximo de 256 KB;
- una antigüedad máxima de 96 horas;
- un identificador de evento nunca visto.
El módulo responde al momento y luego procesa el evento. Una notificación sin firma, mal firmada o reenviada se rechaza y se anota en el registro.
Registro técnico
La pestaña Registro lista los errores, avisos e informaciones, con filtros por TPV, nivel, problema, texto y fecha. Cada error conocido indica su causa y su solución, con un enlace a la pantalla correspondiente. Los tokens, claves y firmas se enmascaran antes de escribirse. Las entradas se conservan 30 días por defecto (ajustable), y se listan los últimos eventos webhook recibidos.

Alertas
La pestaña Alertas reúne los problemas en curso con su causa, su solución y un botón Corregir ahora. Una alerta se cierra sola cuando el problema desaparece.
- sincronización fallida en 3 ejecuciones seguidas, y luego un mensaje cuando vuelve a funcionar;
- token rechazado o imposible de renovar, permiso que falta, firmas de webhook rechazadas;
- actualizaciones de stock abandonadas, cron que ya no se ejecuta;
- artículos vendidos en el TPV sin producto de PrestaShop;
- diferencias encontradas por la conciliación nocturna.

Las alertas también pueden enviarse por email, como máximo una cada 6 horas por alerta. Deja la dirección vacía para usar la de la tienda. Enviar una alerta de prueba comprueba el envío.

Resolución de problemas
«Inventario no inicializado» en Zettle
Activa el seguimiento de stock en al menos un producto de Zettle, o envía un producto desde la pestaña Catálogo.
Webhook de Square rechazado (firma no válida)
La URL de notificación declarada en Square debe ser idéntica, carácter por carácter, a la del módulo, y la clave de firma debe corresponder a esa suscripción.
Token rechazado o permiso que falta
Abre Conexiones, vuelve a conectar el TPV con su asistente y acepta todos los permisos indicados.
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. En el sentido de la tienda al TPV, el control de diferencias del cron recupera esos cambios en la siguiente ejecución. También puedes conceder este permiso en Parámetros avanzados > Equipo > Permisos.
Una venta no ha creado pedido
El registro indica el motivo: artículos sin asociar, moneda de la venta inactiva en PrestaShop, producto limitado a ciertos transportistas o cantidad inferior a una unidad. En ese caso el stock se gestionó directamente. Corrige la causa para las ventas siguientes. El botón Crear el pedido de PrestaShop solo se ofrece para una venta cuyo stock aún no se ha descontado, para no descontarlo nunca dos veces.
El total del pedido no coincide con el ticket
Comprueba que la regla de impuestos de PrestaShop de los productos corresponde al tipo de IVA usado en el TPV. La diferencia se muestra en la venta.
Desinstalación
La desinstalación elimina las tablas del módulo (correspondencias, registro de ventas, colas, registro técnico, conciliaciones, alertas) 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.