E2E

Context

E2E operates with a central (“master”) Minimax organization as the source of truth for the product catalog. Subcontractors work in their own Minimax organizations and need consistent item data to avoid mismatches in codes, names, prices and VAT configuration.

Problem

• One master Minimax account must propagate item changes to 50+ subcontractor accounts.
• The sync must be incremental and idempotent (no duplicates).
• Subcontractor-specific accounting mappings must not be overwritten during updates.
• Operations need a simple way to onboard/disable subcontractor accounts.

Project Goals

• Synchronize the master item catalog into 50+ Minimax organizations.
• Implement deterministic upsert logic: create missing items, update changed items.
• Track master↔subcontractor item mappings and RowVersions for efficient change detection.
• Provide admin tooling for account onboarding and operational controls.

Constraints & Challenges

• OAuth2 token lifecycle (expiry + refresh) must be robust.
• Multi-tenant mapping must be stable (master item ID → subcontractor item ID).
• Updates must preserve subcontractor accounting fields (stocks/revenue accounts).
• API usage must remain efficient at 50+ organizations.

Solution Overview

We built a small integration system that:

• Authenticates to Minimax and fetches incremental sync candidates from the master account.
• Upserts items into each active subcontractor organization.
• Persists mapping + RowVersion tracking in MySQL to prevent duplicates and reduce API calls.
• Includes a lightweight admin UI to manage subcontractor credentials and participation.

As an operational add-on, the system can also send automated reminder emails for overdue issued invoices.

Architecture & Technical Approach

Minimax API client

• OAuth2 token retrieval and refresh.
• `GET`/`POST`/`PUT` helpers with Bearer auth.
• Per-organization client instances for master and subcontractors.

Incremental synchronization

• Fetches master `/items/synccandidates` (optionally with `RecordDtModifiedFrom`).
• Loads item details and applies deterministic create/update logic per subcontractor.
• Preserves subcontractor account mappings during updates.

Mapping + version tracking

• Stores master item ID/RowVersion and subcontractor item ID/RowVersion.
• Uses RowVersion comparisons to avoid unnecessary writes.

Admin operations

• Onboarding UI for adding subcontractor Minimax organizations.
• Enable/disable controls to include or exclude accounts from sync.

Technology Stack

• PHP + MySQL
• Minimax OAuth2 + REST API
• PHPMailer (invoice reminder automation)
• Minimal admin frontend (Material Components + jQuery)

Implementation Process

1. Define master→subcontractor mapping and versioning model.
2. Implement OAuth2-aware Minimax client utilities.
3. Build incremental sync and deterministic upsert logic.
4. Add persistence for mappings and RowVersion tracking.
5. Build admin UI for onboarding and operational toggles.

Results & Impact

• Consistent item catalogs across 50+ subcontractor Minimax organizations.
• Incremental, idempotent sync that avoids duplicates and reduces manual work.
• Preserved subcontractor accounting configuration during updates.
• Simple operations workflow for managing subcontractor participation.

Reflection

In a multi-organization environment, stable identity mapping and version-aware sync are non-negotiable. Persisting both master and subcontractor RowVersions enabled predictable behavior and efficient API usage, while preserving subcontractor-specific fields prevented costly accounting disruptions.

Summary

This integration keeps a master Minimax inventory catalog synchronized into 50+ subcontractor Minimax accounts, using deterministic upserts, mapping persistence, and RowVersion-based change detection. A lightweight admin UI supports onboarding and operational control.