Integration Approach

SaleFlex is designed API-first. All inter-application communication uses REST endpoints and JSON payloads — whether between PyPOS and OFFICE (LAN), PyPOS and GATE (internet), or GATE and external ERP / payment / loyalty systems. Three integration modes: standalone, office, gate.

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

PyPOS uses an offline outbox pattern backed by the SyncQueueItem model. Every event is persisted locally before any network call — guaranteeing zero data loss regardless of connectivity.

Local Event Queue

Transactions, closures, stock movements, and loyalty events are written to SyncQueueItem (SQLite) before any HTTP call is attempted.

Background Flush Workers

office mode:OfficePushWorker (QThread) flushes to OFFICE Flask REST. gate mode:SyncWorker (QThread) pushes to GATE and pulls product/campaign updates.

Zero Data Loss Guarantee

A network outage or application crash cannot lose committed transaction data. The queue retries until the server acknowledges each item.

PyPOS ↔ OFFICE Integration (office mode)

When app.mode = "office", PyPOS communicates exclusively with SaleFlex.OFFICE over LAN — no internet required.

Startup Seed

On first boot, PyPOS calls GET /api/v1/pos/init on OFFICE to seed its local database with products, cashiers, campaigns, customers, and system settings. The terminal registers itself with its store identity triplet (company / store / POS ID).

Transaction Push

OfficePushWorker flushes the SyncQueueItem outbox in cycles. Each cycle delivers all pending items to OFFICE:

POST /api/v1/pos/transactions — completed sales batches
POST /api/v1/pos/closures — end-of-day closure data
POST /api/v1/pos/sequences — per-POS sequence counters

Post-Closure Master-Data Refresh

After a flush cycle in which at least one closure was successfully delivered, PyPOS automatically calls GET /api/v1/pos/init again to reseed its local cache with any product, price, campaign, or loyalty updates that OFFICE has prepared. This keeps terminals in sync without requiring a manual restart.

Ordinary transaction-only pushes do not trigger the master-data refresh.

SaleFlex.mPOS ↔ OFFICE Integration (Android)

mPOS uses the same OFFICE REST API as PyPOS, making the two clients interchangeable from OFFICE's perspective:

Seed

On first connection, Retrofit client calls GET /api/v1/pos/init to populate the Room (SQLite) local database: cashiers, products, barcodes, campaigns, loyalty config, closure state.

Push

POST /api/v1/pos/transactions — completed sale payloads
POST /api/v1/pos/closures — end-of-day closure payloads
On HTTP failure, events are saved as SyncQueueEntity (Room) and retried.

Commercial Note

SaleFlex.mPOS is a commercial product. The OFFICE REST interface it consumes is open and documented. Implementing a compatible Android client is possible using the published API contracts.

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