Mogu li povezati dućan s vlastitim sustavima i pouzdano primati i slati podatke?

Suvremeni dućan ne živi sam za sebe. Trgovci ga žele povezati s računovodstvom, skladištem, marketinškim alatima ili vlastitim CRM-om. WebShopHR nudi tri razine povezivanja: odlazni webhookovi, javni REST API i autentikaciju putem OpenID Connect.

Odlazni webhookovi s pouzdanim potpisom i ponovnim pokušajima

Webhookovi se okidaju na četiri ključne točke: order.created nakon kreiranja narudžbe, order.paid nakon potvrde plaćanja, order.refunded nakon povrata i return.requested kad kupac zatraži povrat. Svaki payload (sadržaj poruke koju webhook nosi) sadrži broj narudžbe, status, način plaćanja, kupčeve podatke, iznose i druge relevantne podatke.

Svaka narudžba koja proizvede webhookove obavlja to unutar transakcije, pa je slanje isto toliko pouzdano koliko i upis u bazu. Tajna se generira prilikom kreiranja registracije i prikazuje samo u tom trenutku. Kasnije se vidi samo to da je postavljena, ali se ne može pročitati.

Webhooks se potpisuju HMAC-SHA256 algoritmom (kriptografskim potpisom kojim primatelj sam provjeri da poruku nitko nije usput izmijenio) s tajnom registracije i stavljaju u posebno zaglavlje koje prima klijent može samostalno provjeriti. Tijelo zahtjeva uvijek sadrži tip događaja i vremensku oznaku.

Sustav automatski ponovno pokušava dostavu u eksponencijalnom razmaku, do unaprijed zadanog maksimalnog broja pokušaja, i zabilježava svaki pokušaj u logu dostava.

Prijemne adrese prolaze strogu provjeru: sustav odbija privatne, loopback, link-local i druge zabranjene IP adrese, onemogućava slijeđenje preusmjerenja i postavlja vremensku granicu odgovora. To sprječava da zlonamjerni webhook služi za skeniranje interne mreže ili napade na druge sustave.

Puni JSON REST API s dokumentacijom na istom poslužitelju

Javni API je JSON REST i dokumentiran je unutar same aplikacije na /api/docs. Dokumentacija se temelji na ručno pisanoj OpenAPI 3 specifikaciji koja pokriva sve glavne entitete: katalog, kategorije, kupce, narudžbe, recenzije, poklon bonove, lokacije, sadržajne stranice i izvoz. CMS i dućan dijele isti poslužitelj, pa nema CORS problema: API pozivi idu s istog origin.

Operacije za kupca, narudžbu, recenziju i slične resurse provjeravaju pripadnost tenanta (kojem dućanu resurs pripada) i vraćaju 403 ukoliko pristup pokuša napraviti klijent iz drugog dućana. Timestamp polja, decimalne vrijednosti cijena u centima i statusi plaćanja šalju se u uniformnom formatu. Paginacija, filtri i sortiranje podržani su na popisnim resursima.

Rute su zaštićene i ulogama unutar dućana: djelatnik, upravitelj i vlasnik imaju strogo odvojene ovlasti, a pokušaj pristupa previsokoj ulozi vraća jasnu poruku o nedostatku prava.

Sve rute trenutno žive pod istim prefiksom, /api/v1/, a objavljene politike verzioniranja (kad dolazi nova verzija, kako se najavljuje ukidanje starih polja) još nema. Kod neispravnog JSON tijela odgovor kombinira kratki hrvatski uvod sa sirovom tehničkom porukom Go parsera na engleskom, pa integracijski klijent u istoj poruci dobiva i naš i tuđi jezik.

OpenID Connect preko Zitadela

Autentikacija kupaca i administratora zasniva se na Zitadelu, a aplikacija ga koristi kao OpenID Connect dobavljač identiteta. Poslužitelj provjerava pristupni token slanjem prema Zitadelu, rukuje osvježavanjem tokena i kroz cijelu aplikaciju poznaje identitet kupca.

Potpisivanje putem JWT-a (digitalno potpisane propusnice koju aplikacija provjeri bez upita u bazu) koristi JWK-ove dohvaćene putem JWKS krajnje točke (javnog kataloga ključeva za provjeru potpisa), a zadani algoritam je RS256 (jači, asimetričan potpis, ne dijeljena lozinka). Ako neki server pokuša prihvatiti token s nepodržanim algoritmom, sustav ga odbija.

Cijeli OAuth tok može biti konfiguriran kroz datoteke okruženja, a jedan Zitadel korisnik može biti član osoblja ili vlasnik u više dućana, što olakšava upravljanje više brendova iz istog računa.

Nema poslovnog događaja bez zapisa u bazi

Jedna od osnovnih odluka WebShopHR-a je da se poslovni događaji ne šalju nakon uspješne operacije, nego unutar iste transakcije. Ako baza potvrdi zapis, webhookovi se također bilježe kao spremni za slanje. Ako transakcija otpadne, nema ni događaja. To eliminira rupu u kojoj bi se novčana transakcija odigrala, a obavijest sustavu za knjigovodstvo izgubila.

Integracije su dio istog sigurnosnog modela

API se ni na koji način ne izuzima od RLS-a (sigurnosnog pravila baze koje odvaja dućane), rate limita, CSP-a, HTTPS-a i audit loga. Integracijski klijenti vide točno one resurse za koje imaju prava, a ograničenja na broj poziva rade jednako i za interfejs i za API. Ta ograničenja nisu jedna zajednička brojka za cijeli API, nego se postavljaju po značajki: primjerice izvoz podataka smije se pokrenuti deset puta na sat po dućanu, dok druge rute imaju vlastite, zasebne granice. Ne postoji poseban „backdoor“ pristup koji bi bio manje zaštićen od administracijskog sučelja.

Integracije omogućuju da WebShopHR postane središte više kanala, a da pritom svaka poruka ostane potpisana, ograničena i bilježena.

Više o temi: Sigurnost i infrastruktura.