Saltar al contenido principal

E-Commerce Integration Module

Reference for apps/backend/src/ecommerce/.

Detailed architecture and operational behavior now lives in: dev/integrations/ecommerce-adapter-architecture

Overview​

The ecommerce module connects a FlowPOS business to external storefront providers through a provider-port architecture.

Current provider status:

  • Shopify: implemented
  • WooCommerce: not implemented in backend yet. The database/provider enum has a woocommerce value and the provider-port pattern is ready, but there is no WooCommerce adapter registered in EcommerceProviderFactory, and the connect DTO currently accepts only shopify.

API surface (high level)​

Authenticated (EcommerceController):

  • GET /ecommerce/connection
  • GET /ecommerce/oauth/url
  • GET /ecommerce/sync/log
  • POST /ecommerce/sync/products
  • POST /ecommerce/sync/collections
  • POST /ecommerce/sync/poll
  • GET /ecommerce/debug/poll (dev-oriented)
  • GET /ecommerce/debug/scopes (dev-oriented)
  • DELETE /ecommerce/connection

Public:

  • GET /ecommerce/oauth/callback
  • POST /ecommerce/webhooks/shopify

Most authenticated endpoints require businessId query parameter.

Quick operational notes​

  • Webhook route POST /ecommerce/webhooks/shopify is public and HMAC-protected.
  • Polling fallback uses BullMQ queue ecommerce-polling.
  • Connection credentials are encrypted at rest.
  • Shopify order ingestion currently creates the ecommerce dedup record, links/creates the customer, deducts mapped inventory, and writes sync logs. It does not create a FlowPOS sale record yet.
  • Shopify inventory_levels/update webhooks are registered but ignored by the current adapter; inventory synchronization is outbound from FlowPOS to Shopify.

For architecture layers, runtime flows, and troubleshooting details, use: dev/integrations/ecommerce-adapter-architecture.