Architecture

System overview

The integration connects two independent systems through REST APIs:

• Flow Retail — The Flow Retail POS platform, with its own REST API.

• Omnium OMS — A cloud-based Order Management System with its own REST API.

Both systems maintain their own databases. The integration keeps them synchronized through API calls, webhook events, and background job processing.

High-level architecture

┌─────────────────────────────────────────────────────────────────┐
│                        OMNIUM OMS                               │
│                                                                 │
│  Products  Prices  Stores  POs  Orders  Customers  Inventory    │
│                                                                 │
└──────┬──────────────────────────────────────┬───────────────────┘
       │                                      │
       │  Omnium REST API                     │  Webhook Events
       │  (Flow calls Omnium)                 │  (Omnium calls Flow)
       │                                      │
       ▼                                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                      FLOW RETAIL CORE                           │
│                                                                 │
│  ┌─────────────────┐    ┌──────────────────────────────────┐    │
│  │  Omnium Module  │    │  Webhook Endpoint                │    │
│  │  (internal/     │    │  (Omnium Event API)              │    │
│  │   omnium/)      │    │                                  │    │
│  └────────┬────────┘    └──────────────┬───────────────────┘    │
│           │                            │                        │
│           ▼                            ▼                        │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Async Job Queue                             │   │
│  │  (external_order_sync / external_receivement_sync)       │   │
│  └──────────────────────────┬───────────────────────────────┘   │
│                             │                                   │
│                             ▼                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │           Sync Engines (Background Workers)              │   │
│  │  - Order Sync Engine                                     │   │
│  │  - Receivement Sync Engine                               │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
│  POS Terminals  ←→  Flow Core API  ←→  PostgreSQL Database      │
└─────────────────────────────────────────────────────────────────┘

Communication patterns

1. Omnium → Flow (product data)

Omnium pushes product data to Flow through Flow's standard REST API. This includes products, brands, categories, prices, stores, purchase orders, and inventory levels. This uses Omnium's built-in export connectors (the FlowRetail connector).

Trigger: Scheduled tasks or on-save events in Omnium.

2. Omnium → Flow (orders via webhook)

When an order is created or updated in Omnium, it sends a webhook event to Flow's Omnium Event API endpoint. Flow then:

1. Receives the event payload

2. Creates an inbound sync job in the queue

3. The sync engine picks up the job and fetches the full order from Omnium's API

4. Creates or updates the order in Flow

3. Flow → Omnium (orders, customers, inventory)

When a POS transaction occurs in Flow (sale, return, customer update, goods reception), Flow:

1. Creates an outbound sync job in the queue

2. The sync engine picks up the job

3. Authenticates with Omnium using OAuth2 client credentials

4. Calls the Omnium REST API to create/update the relevant record

Authentication

Flow authenticates with the Omnium API using OAuth2 Client Credentials:

1. Flow sends client_id and client_secret to Omnium's token endpoint

2. Receives a bearer token

3. Uses the token for subsequent API calls

4. Tokens are cached and refreshed automatically (valid for ~16 hours)

Credentials are stored as tenant-level extension parameters in Flow.

Background sync engines

The integration runs two independent sync engines as background processes:

Order sync engine

Processes order-related sync jobs:

• Inbound: Creates/updates Flow orders from Omnium data

• Outbound: Pushes Flow POS orders to Omnium

Receivement sync engine

Processes goods reception sync jobs:

• Sends delivery confirmations to Omnium after goods are received in Flow

• Updates inventory levels in Omnium when Flow is the stock master

Retry logic

Both sync engines implement the same exponential backoff strategy for failed jobs:

Retry #	Delay
1	1 minute
2	2 minutes
3	5 minutes
4	10 minutes
5	20 minutes
6	30 minutes
7	45 minutes
8	60 minutes
9	90 minutes
10+	120 minutes

Data transformation

Price conversion

Flow Retail stores all monetary values as integers in cents (e.g., 199.50 NOK = 19950). The integration handles conversion in both directions:

• Omnium → Flow: Float values are multiplied by 100 and converted to integers

• Flow → Omnium: Integer values are divided by 100.00 and converted to floats

UID sanitization

Omnium requires UIDs to contain only alphanumeric characters and underscores. Non-compliant characters are automatically stripped during export.

Country/market mapping

Flow maps country codes to Omnium market IDs:

Country Code	Market ID
NO	NOR
SE	SWE
DK	DNK
FI	FIN

The store's externalId field can also be used to specify a custom market ID.