Webshop × Pantheon

Što ovo rješava.

Trgovina se vodi na webshopu, a poslovanje u Pantheon ERP-u - i to su dva odvojena svijeta. Narudžbe se prepisuju ručno, statusi se razilaze, zalihe i cijene se ne slažu, a hrvatska fiskalizacija odvija se - ako uopće - kao zaseban ručni korak.

Nitko to nije naručio jer se pretpostavlja da drukčije ne ide. Mi smo izgradili servis koji ta dva sustava tjera da se ponašaju kao jedan: prodaja se odmah pojavi u Pantheonu, promjene statusa zrcale se u oba smjera, katalog ostaje usklađen, a kupac dobije ispravan fiskalizirani račun - bez ičijeg dodira.

Jezgra je neovisna o platformi. Konektor nije.

Servis stoji na istim temeljima kao naš jednosmjerni Pantheon middleware - ali je dvosmjeran. Sve što je specifično za pojedinu trgovinu živi u tankom konektoru; sve ispod njega - red poslova, upis u ERP, fiskalizacija, PDF, e-mail, revizijski zapis - zajedničko je i ne mijenja se od platforme do platforme.

Ulazni tijek radi s bilo kojim webshopom. Narudžba dolazi ili preko konektora za platformu, ili izravno kao naš kanonski JSON na objavljeni endpoint. Trgovina koja može poslati HTTP zahtjev može slati narudžbe - bez konektora, bez čekanja na nas.

Povratni tijek traži konektor po platformi. Da bismo gurnuli status, zalihu ili cijenu natrag u trgovinu, moramo govoriti njezinim API-jem. Zato je konektor jasno ograničeno sučelje s malim brojem operacija - dohvati narudžbu, postavi status, ažuriraj zalihu i cijenu, upiši proizvod. Novi konektor znači implementirati to sučelje, a ne graditi novi servis.

WooCommerce je prvi konektor - REST API i webhookovi, potpuno pokriven i integracijski testiran. Isti oblik primjenjuje se na Shopify, Magento, PrestaShop ili vlastitu trgovinu.

Što servis radi, neovisno o platformi.

• Narudžbe unutra. Narudžba se upisuje u Pantheon kroz pohranjene procedure - nikad izravnim zapisom u tablice - uz prethodno osiguranje kupca i numeriranje dokumenata koje ostaje u vlasništvu ERP-a.
• Status u oba smjera. Trgovina → ERP (plaćeno, otkazano) i ERP → trgovina (potvrđeno, u obradi, poslano, dovršeno), uz idempotentne prijelaze koji ne stvaraju petlje ni duple događaje.
• Zalihe, cijene i proizvodi - u oba smjera. Bez obzira započinje li promjena u trgovini ili u Pantheonu.
• Hrvatska fiskalizacija, vlastita izvedba. Generiranje ZKI-ja, digitalno potpisani XML (XML-DSig), razmjena s FINA-inim servisom, JIR i QR kod na računu. Bez posrednika i bez third-party fiskalizacijskog servisa.
• Račun u inbox. PDF renderiran headless Chromiumom i poslan kupcu e-mailom putem SMTP-a u trenutku kad je prodaja fiskalizirana.
• Otporno i idempotentno. Trajan red poslova s ponovnim pokušajima i eksponencijalnom odgodom, stanje sigurno na pad procesa, obrada dead-letter poruka i automatsko ponovno spajanje na trgovinu i ERP.
• Nadzorljivo. Strukturirano JSON bilježenje s korelacijskim ID-jem kroz cijeli životni ciklus događaja, health i readiness provjere za svaku ovisnost, i nadzorna ploča reda poslova.
• Konfigurabilna poslovna pravila. Mapiranje statusa, skladišta, poreznih stopa, popusta i predložaka računa su postavke po okruženju, ne izmjene koda.

Jedan servis, dva smjera.

Sve što pokreće prodaju.

Tri načina spajanja.

• WooCommerce - potpun konektor, REST API i webhookovi. Integracijski testiran.
• Bilo koja trgovina, ulazni tijek - narudžbe se šalju kao kanonski JSON na naš objavljeni endpoint, prema OpenAPI/Swagger specifikaciji. Bez konektora.
• Ostale platforme, puni dvosmjerni tijek - Shopify, Magento, PrestaShop ili vlastita trgovina, kroz implementaciju istog konektorskog sučelja. Jezgra ostaje netaknuta.

Najmanje ovlasti, ništa vani.

• Provjera potpisa dolaznih webhookova i autentikacija tokenom na kanonskom endpointu; odbacuje se sve što ne prođe shemu.
• Nikakvi izravni zapisi u ERP tablice; namjenski integracijski korisnik umjesto administratorskog računa.
• Tajne, API ključevi 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 tuđu infrastrukturu. Isporučuje se samo slika.

Dvije opcije smještaja.

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

Odabrano zbog pouzdanosti.

Middleware, ne jednokratna integracija.

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

Za trgovinu na podržanoj platformi, uvođenje se svodi na konfiguraciju i provjeru na testnom okruženju - ne na novi razvojni ciklus. Za novu platformu, dodaje se konektor; sve ostalo već postoji i već radi u produkciji.

Gdje se nalazi.

Projekt je u aktivnom razvoju. Cijela petlja je izgrađena i integracijski testirana protiv žive Pantheon instance i staging trgovine: narudžba unutra → osiguranje kupca → ERP narudžba → zrcaljenje statusa → fiskalizacija → PDF → e-mail.

Kontejnerizirano i nadzorljivo. Prijelaz na produkcijski fiskalizacijski certifikat dokumentiran je kao runbook - isti postupak koji je već proveden na našem jednosmjernom Pantheon middlewareu, koji je u produkciji.