E2E

Kontekst

E2E koristi centralni (“master”) Minimax račun kao izvor istine za šifrarnik artikala. Podizvođači rade u svojim Minimax organizacijama i trebaju usklajene podatke o artiklima, kako ne bi dolazilo do nesklada u šifrah, nazivima, cijenama i VAT konfiguraciji.

Problem

• Jedan master Minimax račun mora propagirati promjene artikala u 50+ podizvođačkih računa.
• Sinkronizacija mora biti inkrementalna i idempotentna (bez duplikata).
• Podizvođačeve specifične kontne postavke se ne smiju prepisati.
• Operativa treba jednostavan način za onboarding i uključivanje/isključivanje računa.

Ciljevi projekta

• Sinkronizacija master šifrarnika artikala u 50+ Minimax organizacija.
• Deterministički upsert: stvaranje nedostajućih artikala, ažuriranje promijenjenih.
• Praćenje master↔podizvođač mapiranja i RowVersiona za učinkovitu detekciju promjena.
• Admin tooling za onboarding i operativne kontrole.

Ograničenja i izazovi

• OAuth2 token lifecycle (expiry + refresh) mora biti stabilen.
• Multi-tenant mapiranje mora biti robustno (master ItemId → podizvođačev ItemId).
• Ažuriranja moraju očuvati kontne postavke (StocksAccount + revenue accounts).
• API pozivi moraju ostati učinkoviti pri 50+ organizacijama.

Pregled rješenja

Razvili smo integracijski sustav koji:

• Autentificira se na Minimax i čita inkrementalne “sync candidates” iz master računa.
• Upserta artikle u svaku aktivnu podizvođačku organizaciju.
• Mapiranje + RowVersion sprema u MySQL (bez duplikata, manje API poziva).
• Uključuje jednostavan admin UI za upravljanje credentialima podizvođača i sudjelovanjem u sinkronizaciji.

Kao operativni dodatak sustav može automatski slati podsjetnike za dospjele izdane račune (Minimax).

Arhitektura i tehnički pristup

Minimax API client

• OAuth2 dohvat tokena i refresh.
• `GET`/`POST`/`PUT` helperji z Bearer auth.
• Odvojene instance po organizaciji (master + podizvođači).

Inkrementalna sinkronizacija

• Master `/items/synccandidates` (opcionalno s `RecordDtModifiedFrom`).
• Deterministički create/update tok po podizvođaču.
• Očuvanje kontnih postavki podizvođača tijekom updatea.

Mapping + praćenje verzija

• Pohranjuje master ItemId/RowVersion i podizvođačev ItemId/RowVersion.
• Usporedba RowVersiona sprječava nepotrebne zapise.

Admin operacije

• UI za dodavanje podizvođačkih Minimax organizacija.
• Kontrole za uključivanje/isključivanje iz sinkronizacije.

Tehnološki stack

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

Proces implementacije

1. Definicija master→podizvođač mappinga i verzioniranja.
2. Implementacija OAuth2 Minimax client utilitija.
3. Implementacija inkrementalne sinkronizacije i determinističkog upserta.
4. Persistencija mappinga i praćenja RowVersiona.
5. Admin UI za onboarding i operativne prekidače.

Rezultati i učinak

• Usklajen šifrarnik artikala u 50+ podizvođačkih Minimax organizacijama.
• Inkrementalna, idempotentna sinkronizacija bez duplikata.
• Očuvane kontne postavke podizvođača tijekom ažuriranja.
• Jednostavan operativni workflow za upravljanje uključenosti u sinkronizaciju.

Refleksija

U multi-organizacijskom okruženju stabilan identity mapping i verzijski vođena sinkronizacija su nužni. Pohrana RowVersiona na obje strane omogućuje predvidljivo ponašanje i učinkovite API pozive, a očuvanje podizvođačevih kontnih polja sprječava skupe zahvate u računovodske postavke.

Sažetak

Integracija sinkronizira master Minimax šifrarnik artikala u 50+ podizvođačkih Minimax računa determinističkim upsertom, persistencijom mappinga i RowVersion detekcijom promjena. Jednostavan admin UI podržava onboarding i operativnu kontrolu.