Integración Square + Medusa.js
La única integración bidireccional publicada de Square para Medusa v2. Sincronización de catálogo, inventario, pagos (Apple Pay, Google Pay), OAuth y una extensión de UI para el panel de administración — en un solo paquete npm.
Todo lo que maneja el medusa-square-plugin
Productos, variantes, precios e inventario se sincronizan en ambas direcciones entre Square y Medusa. Los cambios del catálogo de Square llegan a Medusa mediante webhooks. Los cambios del catálogo de Medusa se envían a Square mediante la Catalog API. La resolución de conflictos es configurable.
Square Web Payments SDK integrado en el checkout de Medusa. Los pagos con tarjeta, Apple Pay y Google Pay se procesan con Square: una sola integración, todos los métodos de pago. La confirmación del pago crea el pedido de Medusa automáticamente.
Los comerciantes conectan su cuenta de Square por OAuth directamente en el panel de administración de Medusa. La extensión de la interfaz muestra el estado de la conexión y la salud de la sincronización, y permite resincronizar manualmente, sin ingeniería para la operación diaria.
Detalles de la arquitectura del plugin
Patrón de módulo Medusa v2
El plugin sigue las convenciones de módulo de Medusa v2: patrón MedusaService, StepResponse en workflows, idempotencia en subscribers. Extiende Medusa correctamente — sin modificaciones al núcleo, con compatibilidad total para actualizaciones.
Flujo Square OAuth
El plugin implementa Square OAuth a nivel del servicio de Medusa. Los comerciantes autorizan el acceso mediante el flujo OAuth de Square; el token de acceso se almacena en GCP Secret Manager (no en la base de datos). El plugin gestiona la renovación del token de forma automática.
Procesamiento de webhooks
Los webhooks de Square para actualizaciones de catálogo, cambios de inventario y eventos de órdenes son procesados por un microservicio dedicado en Cloud Run. El microservicio valida las firmas HMAC, elimina duplicados y reenvía los eventos verificados a los subscribers de Medusa.
Soporte multi-tenant
El plugin admite múltiples cuentas de comerciante de Square en una sola instancia de Medusa — necesario para arquitecturas de marketplace donde cada vendedor tiene su propia conexión Square OAuth.
Extensión de UI para el panel de administración
Una extensión del panel de administración de Medusa construida con @medusajs/ui y @tanstack/react-query. Muestra el estado de la conexión con Square, la profundidad de la cola de sincronización, la marca de tiempo de la última sincronización y permite re-sincronizar manualmente por tipo de entidad.
Preguntas frecuentes
Preguntas comunes sobre medusa-square-plugin.
Obtener soporte de integración
Cuéntanos tu versión de Medusa, tu configuración de Square y qué necesitas que cubra el plugin.
Publicado en npm
Instala con npm install @weareseeed/medusa-square-plugin.
Patrón de módulo Medusa v2
Sin modificaciones al núcleo, compatibilidad total con actualizaciones.
Apple Pay + Google Pay incluidos
Todos los métodos del Square Web Payments SDK cubiertos.
Seeed lo mantiene
Actualizaciones continuas conforme evolucionan las APIs de Square y Medusa.
Obtener soporte de integración
Cuéntanos tu versión de Medusa, tu configuración de Square y qué necesitas que cubra el plugin.
Publicado en npm
Instala con npm install @weareseeed/medusa-square-plugin.
Patrón de módulo Medusa v2
Sin modificaciones al núcleo, compatibilidad total con actualizaciones.
Apple Pay + Google Pay incluidos
Todos los métodos del Square Web Payments SDK cubiertos.
Seeed lo mantiene
Actualizaciones continuas conforme evolucionan las APIs de Square y Medusa.
