PS PrestaShop Intermedio

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.

Actualizado Versión del módulo 2.0.0

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.
Panel del conector de TPV: ventas importadas, stock sincronizado, errores, cola y última sincronización
Panel del conector de TPV

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

  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. 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.

Conexiones Square, Zettle y SumUp con sus funciones disponibles
Conexiones Square, Zettle y SumUp con sus funciones disponibles

Square

  1. 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.
  2. 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.
  3. Haz clic en Conectar con Square, acepta los permisos y luego en Probar la conexión.
  4. Elige el local que lleva el stock y marca aquellos cuyas ventas se importan (10 como máximo).
  5. 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.updated y oauth.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.
Asistente de conexión Square: OAuth, permisos mínimos, locales
Asistente de conexión Square

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.

Pantalla de autorización OAuth simulada (modo demostración)
Pantalla de autorización OAuth simulada (modo demostración)
Locales Square: local de stock e importación de ventas
Locales Square

Zettle by PayPal

  1. 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.
  2. Guarda y luego prueba la conexión.
  3. 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.
  4. El seguimiento de stock debe estar activado en los productos de Zettle. Los productos enviados por el módulo lo tienen automáticamente.
Asistente de conexión Zettle: clave API u OAuth y webhook firmado
Asistente de conexión Zettle

SumUp

  1. Pega tu clave API secreta (panel de SumUp, Developers > API keys) con tu código de comercio, o conéctate con OAuth.
  2. Prueba la conexión. El código de comercio se lee automáticamente si falta.
  3. 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.
Asistente de conexión SumUp: clave API u OAuth, importación por el cron
Asistente de conexión SumUp

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.
Sentido de sincronización del stock por TPV y fuente de verdad
Sentido de sincronización del stock por TPV y fuente de verdad

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.
Correspondencias entre artículos del TPV y productos PrestaShop con sugerencias
Correspondencias entre artículos del TPV y productos PrestaShop con sugerencias

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.

  1. 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.
  2. 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.
Envío del catálogo PrestaShop al TPV con vista previa antes de crear
Envío del catálogo PrestaShop al TPV con vista previa antes de crear

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.

Conciliación del stock entre PrestaShop y el TPV con informe de diferencias
Conciliación del stock entre PrestaShop y el TPV con informe de diferencias

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.

Registro de ventas del TPV con pedido PrestaShop, IVA y propina
Registro de ventas del TPV con pedido PrestaShop, IVA y propina

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.

Ajustes de pedidos, facturas, reembolsos y clientes identificados
Ajustes de pedidos, facturas, reembolsos y clientes identificados
  • 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.
Pedido PrestaShop creado para una venta en TPV, con el resumen del ticket
Pedido PrestaShop creado para una venta en TPV, con el resumen del ticket

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.
Devolución parcial en el TPV repuesta en stock con factura por abono
Devolución parcial en el TPV repuesta en stock con factura por abono

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.

Registro técnico filtrable con la causa y la solución de cada error
Registro técnico filtrable con la causa y la solución de cada error

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.
Centro de alertas con causa, solución y emails
Centro de alertas con causa, solución y emails

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.

Email de alerta del conector de TPV con explicación y solución
Email de alerta del conector de TPV con explicación y solución

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.

¿Te ha resultado útil esta página?

¿Sigues atascado? Contacta con soporte