Integration — SaleFlex Ecosystem

Protocol Baseline

REST APIs

All system-to-system communication uses HTTP REST endpoints. GATE exposes versioned APIs (/api/v1/...); OFFICE exposes store-level endpoints consumed by PyPOS terminals.

JSON Payloads

All request and response bodies are JSON. PyPOS serializers produce documented cart snapshots (schema_version: 1.0) for campaign evaluation and GATE sync.

Authentication

GATE uses JWT for user sessions and long-lived API tokens for device clients (PyPOS terminals). Tokens are scoped to company, store, and device.

Offline-Resilient Operations — The Outbox Pattern

Store-side components are designed to continue operation even with intermittent or absent connectivity. PyPOS uses an offline outbox pattern backed by the SyncQueueItem model:

Local Event Queue

Every event (transaction, closure, stock movement) is written to the local SyncQueueItem table before any network call — guaranteeing zero data loss.

Background Sync Worker

A PySide6 QThread background worker (SyncWorker) periodically attempts to push queued events to GATE and pull updates such as product prices and campaign definitions.

Zero Data Loss Guarantee

Because every event is persisted locally first, a network outage — or even an application crash — cannot lose completed transaction data. The queue retries until the server acknowledges.

  PyPOS (store floor)
  ┌────────────────────────────────────────────┐
  │  Sale / Payment / Closure / Stock event    │
  │           ↓                                │
  │  SyncQueueItem  (local SQLite)             │
  │           ↓                                │
  │  SyncWorker (QThread — background)         │
  │    push → transactions, closures, stock    │
  │    pull ← products, campaigns, notify      │
  └────────────────────┬───────────────────────┘
                       │  REST/JSON (HTTPS)
                       ▼
  SaleFlex.GATE  ──  /api/v1/...

Three Operational Integration Layers

Local Continuity

PyPOS operates entirely on its local database. All sales, payments, closures, and inventory movements are complete without any network call. Connectivity is opportunistic, not required.

Store Coordination

OFFICE aggregates and coordinates local operational data — distributing master data (products, campaigns) to PyPOS terminals and consolidating transaction data for store-level reporting.

Central Orchestration

GATE centralizes APIs, multi-tenant company/store boundaries, and acts as the integration gateway for third-party systems — keeping edge clients thin and simple.

SaleFlex.GATE — Push and Pull Sync

PyPOS → GATE (Push)

PyPOS pushes completed events to GATE via GateSyncService:

Completed transactions and payment details
End-of-day closures and Z-report data
Warehouse stock movements and adjustments
Campaign usage audit records
Loyalty point earn and redeem events

GATE → PyPOS (Pull)

PyPOS pulls updates from GATE via GatePullService:

Product catalog and price updates
Active campaign definitions and rules
Terminal notifications and signals
Cache-refresh triggers (e.g. after campaign update)

gate.manages_campaign: When this flag is true in settings.toml, PyPOS sends the cart snapshot to GATE for campaign evaluation instead of running the local campaign engine. This allows a central promotion authority while keeping checkout latency acceptable.

Campaign & Coupon Integration

SaleFlex supports both a local campaign engine (embedded in PyPOS) and a GATE-managed campaign engine (delegated to the central hub). The mode is controlled by gate.manages_campaign in settings.toml.

Local Engine (default)

CampaignService.evaluate_proposals() runs in-process
Supports Basket, Product, Time-based, Buy-X-Get-Y, and Payment-method campaigns
ActiveCampaignCache loaded at startup, refreshed on admin save or GATE pull
Coupon activation via CouponActivationService on the SALE form

GATE-Managed Engine

PyPOS builds a CampaignSerializer.build_discount_request() cart snapshot
Snapshot is sent to GATE REST endpoint; proposals are returned as JSON
PyPOS applies the returned discount proposals to the open document
GATE COUPON button shows an info message instead of local activation

Third-Party Integration Architecture

GATE is designed as the integration gateway so edge clients stay simple. PyPOS also ships base connector stubs for direct third-party integration in cases where GATE is not deployed.

ERP Adapters

Base class BaseERPConnector. Planned concrete adapters for SAP, Oracle, Logo, Netsis, and custom ERP systems.

Payment Gateway Adapters

Base class BasePaymentGateway. Planned connectors for iyzico, PayTR, Stripe, Nets, and custom PSPs.

Campaign Module Adapters

Base class BaseCampaignConnector. Allows plugging in a third-party promotion engine behind the same apply_campaign routing interface.

Loyalty System Adapters

Loyalty integration mode: LOCAL (active), GATE, or EXTERNAL. External systems hook into LoyaltyProgramPolicy configuration.

Current status: All adapter classes are log-only stubs. They define the interface contract and are ready to be implemented with real vendor SDKs. Follow the repository roadmap for implementation status.

REST API Conventions (GATE)

Versioned base path: /api/v1/
JSON request and response bodies throughout
JWT for user session authentication
Long-lived API tokens for device (PyPOS) authentication

Tokens scoped to company, store, and device
OpenAPI schema planned (see roadmap)
Rate limiting and structured logging on the roadmap
All device push/pull endpoints align with PyPOS serializer contracts

Implementation Detail Sources

For deep technical integration details, the authoritative sources are the repository documentation folders:

Integration Approach