Kako izvesti cjelokupni katalog, kupce i narudžbe?

Trgovac mora uvijek moći doći do vlastitih podataka: za knjigovodstvo, GDPR zahtjev, arhivu ili premještaj na drugu platformu. WebShopHR sve te podatke izvozi kroz jedan endpoint, u dva formata, bez skrivanja lozinki i bez zaključavanja podataka.

Jedan endpoint, dva formata

Export se pokreće GET zahtjevom na /api/v1/export s parametrima what i format. Parametar what može biti items, customers, orders ili all, a format može biti json ili csv. Ako parametri nisu navedeni, zadana vrijednost je all u JSON formatu.

U CMS sučelju jednim klikom ide izvoz kupaca, ostalo API pozivom

CMS trenutno na sučelju nudi jedan gotov gumb za izvoz, u pregledu kupaca, koji preuzima ZIP s popisom kupaca (what=customers). Izvoz kataloga, narudžbi ili kompletnog presjeka (items, orders, all) taj gumb ne pokriva. Za te podatke treba pozvati isti /api/v1/export endpoint izravno, s odgovarajućim parametrom what i valjanim autentifikacijskim tokenom. To nije korak koji trgovac obavlja klikom u sučelju, nego zahtijeva tehničko znanje ili pomoć nekoga tko zna pozvati API, primjerice knjigovođe ili razvojnog tima. Sam endpoint podržava sve kombinacije opisane gore.

Export je dostupan samo ovlaštenim korisnicima

Export podataka nije javni endpoint. Pokretanje zahtijeva prijavu u CMS, pa ga mogu pokrenuti samo trgovac ili član osoblja s pravima upravitelja. Na taj se način štiti da pristup cjelokupnim poslovnim podacima, dakle katalogu, kupcima i financijama, ne može dobiti bilo tko s internetom.

JSON s ugniježđenim odnosima

JSON izlaz vraća jedan objekt s tri grane: items, customers i orders. Artikli nose popis svojih varijanti, a narudžbe nose popis stavki. Time se zadržavaju odnosi iz baze bez da se moraju naknadno spajati po identifikatorima. Ovakav oblik pogodan je za migraciju, vlastite skripte ili arhivu.

CSV dolazi kao ZIP s četiri datoteke

CSV izlaz se šalje kao ZIP arhiva koja sadrži četiri datoteke: items.csv, customers.csv, orders.csv i order_items.csv. Svaka datoteka ima svoj zaglavni redak, a iznosi su uvijek u centima. Prazne vrijednosti ostaju prazne, tako da se ne uvodi nula umjesto praznog polja.

UTF-8 BOM za ispravne hrvatske znakove u Excelu

Svaki CSV unutar ZIP-a počinje UTF-8 BOM oznakom. Bez te oznake Excel na Windowsu često pretpostavlja Windows-1250 enkodiranje i hrvatski znakovi poput č, ć, š, ž i đ bi se prikazali pogrešno. S BOM-om datoteka se otvara ispravno odmah nakon preuzimanja, bez dodatnog podešavanja enkodiranja.

Konzistentan snapshot iz jedne transakcije

Cijeli izvoz čita podatke iz jedne bazne transakcije. To znači da je narudžba kreirana usred izvoza ili cijela unutra, ili je nema. Nikad neće završiti u polovičnom stanju između dvije datoteke. Time se osigurava da brojevi u orders.csv i order_items.csv uvijek odgovaraju jedni drugima, bez obzira na to tko je upravo kupovao u trgovini.

Datumi u RFC3339, iznosi u centima

Datumi su zapisani u standardnom RFC3339 obliku, što je jednoznačno i Excelu i svim programskim jezicima. Prazni datumi, primjerice anonymized_at kod kupca koji još nije anonimiziran, ostaju prazni. Iznosi su uvijek cijeli brojevi centi, što eliminira greške zaokruživanja pri naknadnoj obradi.

Narudžbe s R1 podacima i financijama

CSV s narudžbama sadrži sve relevantne podatke za knjigovodstvo: status, način plaćanja, podatke o kupcu, R1 oznaku, naziv tvrtke i OIB tvrtke, zatim subtotal, poštarinu, popust, kupon, ukupni iznos i iznos povrata. Stavke narudžbi idu u zasebnu order_items.csv datoteku, gdje se vide naziv artikla, naziv varijante, cijena po komadu, količina i ukupna cijena stavke.

Kupci bez lozinke, s tragom anonimizacije

Izvoz kupaca nikad ne sadrži lozinku ili njezin hash. Umjesto toga, za svakog kupca se izvozi identifikator, e-mail, ime, datum kreiranja i eventualni datum anonimizacije. To pokriva GDPR obvezu da se zna kad su osobni podaci anonimizirani, a istovremeno se ne izvoze osjetljiva sigurnosna polja.

Ograničenje na deset izvoza po satu, ali bez zagušivanja

Export je ograničen na deset pokretanja po satu po trgovini, kako se resursi ne bi trošili na neprekidno generiranje istih datoteka. Ako dođe do kvara u sustavu za ograničavanje, sustav nastavlja raditi umjesto da potajno blokira pristup vlastitim podacima. To znači da trgovac rijetko mora brinuti o tome hoće li moći izvući podatke baš kad mu zatrebaju.

Zaključak

Izvoz je stvoren kao sigurna kopija cijelog poslovanja: jedan endpoint, dva formata, konzistentan snapshot, hrvatski znakovi ispravno pročitani u Excelu i bez skrivenih lozinki. Trgovac može podatke koristiti za knjigovodstvo, vlastitu arhivu ili migraciju bez straha da će mu ih netko uskratiti.

Više o temi: Katalog i zalihe.