E2E

Context

E2E werkt met een centrale (“master”) Minimax-organisatie als bron van waarheid voor de productcatalogus. Onderaannemers werken in hun eigen Minimax-organisaties en hebben consistente artikeldata nodig om mismatches in codes, namen, prijzen en btw-configuratie te vermijden.

Probleem

• Eén master Minimax-account moet artikelwijzigingen doorzetten naar 50+ onderaannemer-accounts.
• De sync moet incrementeel en idempotent zijn (geen duplicaten).
• Onderaannemer-specifieke boekhoudmappings mogen niet worden overschreven tijdens updates.
• Operations heeft een simpele manier nodig om onderaannemer-accounts te onboarden/uitschakelen.

Projectdoelen

• De master artikelcatalogus synchroniseren naar 50+ Minimax-organisaties.
• Deterministische upsert-logica implementeren: ontbrekende artikelen aanmaken, gewijzigde artikelen bijwerken.
• Master↔onderaannemer mappings en RowVersions bijhouden voor efficiënte change detection.
• Admin tooling voorzien voor account-onboarding en operationele controles.

Beperkingen & Uitdagingen

• OAuth2 token lifecycle (expiry + refresh) moet robuust zijn.
• Multi-tenant mapping moet stabiel zijn (master item ID → onderaannemer item ID).
• Updates moeten onderaannemer-boekhoudvelden behouden (voorraad-/omzetrekeningen).
• API-gebruik moet efficiënt blijven bij 50+ organisaties.

Oplossingsoverzicht

We hebben een klein integratiesysteem gebouwd dat:

• Authenticeert bij Minimax en haalt incrementele sync-candidates op uit het master-account.
• Upserts uitvoert naar elke actieve onderaannemer-organisatie.
• Mapping + RowVersion-tracking opslaat in MySQL om duplicaten te voorkomen en API-calls te beperken.
• Een lichte admin UI bevat om credentials en deelname van onderaannemers te beheren.

Als operationele add-on kan het systeem ook automatisch herinneringsmails sturen voor verlopen uitgereikte facturen.

Architectuur & Technische aanpak

Minimax API client

• OAuth2 token retrieval en refresh.
• `GET`/`POST`/`PUT` helpers met Bearer auth.
• Per-organisatie client instances voor master en onderaannemers.

Incrementele synchronisatie

• Haalt master `/items/synccandidates` op (optioneel met `RecordDtModifiedFrom`).
• Laadt artikeldetails en past deterministische create/update-logica toe per onderaannemer.
• Behoudt onderaannemer-account mappings tijdens updates.

Mapping + version tracking

• Slaat master item ID/RowVersion en onderaannemer item ID/RowVersion op.
• Gebruikt RowVersion-vergelijkingen om onnodige writes te vermijden.

Admin operations

• Onboarding-UI voor het toevoegen van Minimax-organisaties van onderaannemers.
• Enable/disable controls om accounts in of uit de sync te nemen.

Technologiestack

• PHP + MySQL
• Minimax OAuth2 + REST API
• PHPMailer (automatisering voor factuurherinneringen)
• Minimale admin-frontend (Material Components + jQuery)

Implementatieproces

1. Master→onderaannemer mapping- en versioningmodel definiëren.
2. OAuth2-aware Minimax-client hulpfuncties implementeren.
3. Incrementele sync en deterministische upsert-logica bouwen.
4. Persistency toevoegen voor mappings en RowVersion-tracking.
5. Admin UI bouwen voor onboarding en operationele toggles.

Resultaten en impact

• Consistente artikelcatalogi over 50+ Minimax-organisaties van onderaannemers.
• Incrementele, idempotente sync die duplicaten voorkomt en handwerk vermindert.
• Onderaannemer-boekhoudconfiguratie blijft behouden tijdens updates.
• Eenvoudige operations-workflow voor het beheren van deelname van onderaannemers.

Reflectie

In een multi-organization omgeving zijn stabiele identity mapping en version-aware sync niet onderhandelbaar. Door zowel master als onderaannemer RowVersions te persisteren, kregen we voorspelbaar gedrag en efficiënt API-gebruik, terwijl het behouden van onderaannemer-specifieke velden kostbare boekhoudverstoringen voorkomt.

Samenvatting

Deze integratie houdt een master Minimax-voorraadcatalogus gesynchroniseerd naar 50+ Minimax-accounts van onderaannemers, met deterministische upserts, persistency van mappings en RowVersion-gebaseerde change detection. Een lichte admin UI ondersteunt onboarding en operationele controle.