E2E

Kontekst

E2E uporablja centralni (“master”) Minimax račun kot vir resnice za šifrant artiklov. Podizvajalci delajo v svojih Minimax organizacijah in potrebujejo usklajene podatke o artiklih, da ne prihaja do neskladij v šifrah, nazivih, cenah in VAT konfiguraciji.

Problem

• En master Minimax račun mora propagirati spremembe artiklov v 50+ podizvajalskih računov.
• Sinhronizacija mora biti inkrementalna in idempotentna (brez duplikatov).
• Podizvajalčeve specifične kontne nastavitve se ne smejo prepisati.
• Operativa potrebuje preprost način za onboarding in omogočanje/onemogočanje računov.

Cilji projekta

• Sinhronizacija master šifranta artiklov v 50+ Minimax organizacij.
• Determinističen upsert: ustvarjanje manjkajočih artiklov, posodabljanje spremenjenih.
• Sledenje master↔podizvajalec mapiranju in RowVersion za učinkovito detekcijo sprememb.
• Admin tooling za onboarding in operativne kontrole.

Omejitve in izzivi

• OAuth2 token lifecycle (expiry + refresh) mora biti stabilen.
• Multi-tenant mapiranje mora biti robustno (master ItemId → podizvajalčev ItemId).
• Posodobitve morajo ohraniti kontne nastavitve (StocksAccount + revenue accounts).
• API klici morajo ostati učinkoviti pri 50+ organizacijah.

Pregled rešitve

Razvili smo integracijski sistem, ki:

• Avtenticira na Minimax in bere inkrementalne “sync candidates” iz master računa.
• Upserta artikle v vsako aktivno podizvajalsko organizacijo.
• Mapiranje + RowVersion shranjuje v MySQL (brez duplikatov, manj API klicev).
• Vključuje enostaven admin UI za upravljanje podizvajalskih credentialov in sodelovanja v syncu.

Kot operativni dodatek lahko sistem tudi avtomatsko pošilja opomine za zapadle izdane račune (Minimax).

Arhitektura in tehnični pristop

Minimax API client

• OAuth2 pridobivanje tokena in refresh.
• `GET`/`POST`/`PUT` helperji z Bearer auth.
• Ločene instance na organizacijo (master + podizvajalci).

Inkrementalna sinhronizacija

• Master `/items/synccandidates` (opcijsko z `RecordDtModifiedFrom`).
• Determinističen create/update tok per podizvajalec.
• Ohranjanje kontnih nastavitev podizvajalca pri update.

Mapping + sledenje verzijam

• Hrani master ItemId/RowVersion in podizvajalčev ItemId/RowVersion.
• RowVersion primerjava prepreči nepotrebne zapise.

Admin operacije

• UI za dodajanje podizvajalskih Minimax organizacij.
• Enable/disable kontrole za vključitev/izključitev iz synka.

Tehnološki sklad

• PHP + MySQL
• Minimax OAuth2 + REST API
• PHPMailer (opomini za izdane račune)
• Minimalen admin frontend (Material Components + jQuery)

Proces implementacije

1. Definicija master→podizvajalec mappinga in verzioniranja.
2. Implementacija OAuth2 Minimax client utilitijev.
3. Implementacija inkrementalnega synka in determinističnega upserta.
4. Persistenca mappinga in RowVersion sledenja.
5. Admin UI za onboarding in operativne preklopnike.

Rezultati in učinek

• Usklajen šifrant artiklov v 50+ podizvajalskih Minimax organizacijah.
• Inkrementalna, idempotentna sinhronizacija brez duplikatov.
• Ohranjene kontne nastavitve podizvajalcev pri posodobitvah.
• Enostaven operativni workflow za upravljanje vključenosti v sync.

Refleksija

V multi-organizacijskem okolju sta stabilen identity mapping in verzijsko voden sync nujna. Shranjevanje RowVersion na obeh straneh omogoči predvidljivo obnašanje in učinkovite API klice, ohranjanje podizvajalčevih kontnih polj pa prepreči drage posege v računovodske nastavitve.

Povzetek

Integracija sinhronizira master Minimax šifrant artiklov v 50+ podizvajalskih Minimax računov z determinističnim upsertom, persistenco mappinga in RowVersion detekcijo sprememb. Enostaven admin UI podpira onboarding in operativno kontrolo.