Pantheon Middleware

Što je trebalo riješiti.

Webshop i Pantheon ERP su u većini instalacija dva odvojena svijeta. Narudžbe se ručno prepisuju, računi izdaju ručno, a hrvatska fiskalizacija - zakonska obveza - ostaje izvan tijeka ili se rješava zasebnim alatom.

Rezultat je poznat: kašnjenje između narudžbe i računa, greške pri prepisivanju, i ovisnost o tome da netko svaki dan odradi isti niz koraka.

Trebao je servis produkcijske razine koji preuzima narudžbu iz webshopa i nosi je sve do fiskaliziranog računa poslanog kupcu e-mailom - pouzdano, ponovljivo i bez ičijeg dodira.

Kako smo to izgradili.

Izgradili smo integracijski servis koji ide samo naprijed: webshop šalje narudžbe u jednom smjeru, middleware obavlja ostalo. Čist ugovor sprijeda, sigurni zapisi i fiskalizacija straga - jednostavno za razumjeti, teško srušiti.

• Vlastiti API ugovor. Middleware definira format narudžbe, ne obrnuto. Kanonski JSON objavljen kao OpenAPI/Swagger specifikacija, sa Zod/DTO validacijom na ulazu i primjerima zahtjeva. Webshop se integrira prema stabilnom, dokumentiranom i verzioniranom sučelju - bez adaptera, bez pogađanja, bez naknadnih iznenađenja.
• Sigurni zapisi u ERP. Svaki zapis ide kroz Pantheon pohranjene procedure - nikad izravni INSERT u tablice ERP-a. Zapisi su umotani u transakcije, numeriranje dokumenata ostaje u vlasništvu ERP-a, a pristup ide preko namjenskog integracijskog korisnika s minimalnim ovlastima. ERP nikad ne završi u nedosljednom stanju zbog integracije.
• Hrvatska fiskalizacija, vlastita izvedba. Generiranje ZKI-ja, digitalno potpisani XML (XML-DSig), razmjena s FINA-inim servisom, preuzimanje JIR-a i QR kod na računu. Bez posrednika i bez third-party fiskalizacijskog servisa. Prijelaz demo → produkcijski certifikat izveden je kao kontrolirani, dokumentirani postupak.
• Automatsko fakturiranje. PDF računi renderirani headless Chromiumom iz predložaka, s fiskalnim podacima i QR kodom, dostavljeni kupcu e-mailom putem SMTP-a - uz interne BCC kopije.
• Otporno i idempotentno. Trajan red poslova s ponovnim pokušajima i eksponencijalnom odgodom. Idempotentnost na razini narudžbe - ista narudžba poslana dvaput ne stvara dva dokumenta. Praćenje stanja sigurno na pad procesa, obrada dead-letter poruka s ponovnim stavljanjem u red, i automatsko ponovno spajanje na ERP nakon prekida veze.
• Nadzorljivo. Strukturirano JSON bilježenje s korelacijskim ID-jem kroz cijeli životni ciklus zahtjeva - od HTTP zahtjeva do poslanog e-maila. Health i readiness provjere za svaku ovisnost (ERP, baza, red, SMTP) i nadzorna ploča reda poslova.
• Konfigurabilna poslovna pravila. Popusti, mapiranje skladišta, tretman digitalnih artikala, porezne stope, predlošci računa - sve su to postavke po okruženju, ne izmjene koda. Ista slika radi kod različitih naručitelja s različitim postavkama.

Dva procesa, jedna baza koda.

Servis radi kao dva neovisna procesa iz jedne baze koda, tako da se svaki može skalirati i pasti zasebno bez rušenja drugoga.

Najmanje ovlasti, ništa vani.

• Autentikacija dolaznih zahtjeva tokenom, uz odbacivanje svega što ne prođe shemu.
• Nikakvi izravni zapisi u ERP tablice; namjenski integracijski korisnik umjesto administratorskog računa.
• Tajne i certifikati isključivo iz okruženja - nikad u repozitoriju ni u slici.
• Isporuka bez izvornog koda: aplikacija se u sliku pakira prevedena u V8 bytecode, pa čitljiv izvorni kod nikad ne dolazi na infrastrukturu naručitelja. Isporučuje se samo slika.

Dvije opcije smještaja.

Servis se isporučuje kao Docker slika, pa se jednako vrti bilo gdje - a naručitelj bira gdje.

Odabrano zbog pouzdanosti.

Izgrađeno za predaju.

• TypeScript strogi način s dodatnim sigurnosnim zastavicama; tipizirane klase pogrešaka s lancima uzroka.
• Jedinični, integracijski (protiv žive Pantheon instance) i end-to-end testovi.
• Dva načina isporuke - samostalni handoff paket za vanjske operatere, ili deploy iz repozitorija s alatima za ponovni deploy, backup i rollback.
• Odvojena test i produkcijska okruženja, s demo fiskalizacijskim certifikatom na testu.
• Dvojezična (EN / HR) dokumentacija: API specifikacija, tehnička dokumentacija, deploy i go-live runbookovi.

Gdje se nalazi.

Servis je u produkciji. Cijeli tijek radi bez ručnih koraka: zaprimanje narudžbe → osiguranje kupca → ERP narudžba i račun → fiskalizacija → PDF → e-mail kupcu.

Uz produkcijsko okruženje radi i odvojeno test okruženje s demo fiskalizacijom, na kojem se integracije razvijaju i provjeravaju prije nego dođu do stvarnih računa.

Middleware, ne jednokratna integracija.

Servis je izgrađen kao proizvod, a ne kao izvedba po mjeri jednog naručitelja. Ugovor prema webshopu, pristup Pantheonu i fiskalizacijski sloj su općeniti; ono što se razlikuje od naručitelja do naručitelja - vjerodajnice, certifikat, skladišta, porezne stope, predlošci računa, poslovna pravila - su postavke okruženja.

Praktično, to znači da se uvođenje kod novog Pantheon korisnika svodi na konfiguraciju i provjeru na testnom okruženju, a ne na novi razvojni ciklus.

Prikladno za trgovce koji koriste Pantheon ERP i žele da webshop narudžbe završe kao fiskalizirani računi bez ručnog rada - bez obzira na to koja platforma pokreće webshop, jer webshop se integrira prema našoj objavljenoj specifikaciji.