Javni API
Sve što radiš kroz CMS (katalog, narudžbe, postavke, izgled trgovine) dostupno je i kao REST API, koji možeš koristiti za vlastite integracije i automatizacije mimo CMS-a. To je doslovno isti API kojim se služi i sam CMS, ne odvojena, osiromašena javna verzija.
Gdje je dokumentacija
Puna dokumentacija je javno dostupna na /api/docs, interaktivno
sučelje gdje vidiš svaki poziv, njegove parametre i odgovore, i pozive
možeš isprobati izravno iz preglednika. Sirovi OpenAPI 3 opis (YAML) je na
/api/docs/openapi.yaml, ako ga želiš učitati u vlastiti alat ili
generator koda.
Sama dokumentacija je javna i ne traži prijavu: opis sučelja ne otkriva nikakve tajne, isti pristup kao kod Stripea ili GitHuba. Autorizacija je potrebna tek za stvarne pozive, ne za čitanje dokumentacije.
Dokumentacija opisuje svaki poziv posebno: putanju, metodu, koje parametre prima i kakav odgovor vraća, uključujući moguće greške, sve na jednom mjestu, umjesto da pogađaš iz koda.
Rute nose prefiks /api/v1/, a spec navodi verziju 1.0.0. Objavljene
politike o tome što se smatra promjenom koja lomi kompatibilnost nema:
oslanjaj se na dokumentaciju na /api/docs za trenutno stanje svakog
poziva, ne na pretpostavku da v1 znači zamrznut ugovor.
Kako se autoriziraš
Svaki stvarni poziv API-ja nosi Authorization: Bearer <token> header s
JWT tokenom. Token dobivaš prijavom kroz Zitadel, isti sustav identiteta
koji koristi i sam CMS. Svaka trgovina ima svoju organizaciju, pa token
vrijedi samo za tvoju trgovinu i tvoju ulogu u njoj. Tuđe podatke njime ne
možeš dohvatiti.
Zitadel uz ljudsku prijavu podržava i strojne (machine, client_credentials) tokene, prikladne za automatizacije koje ne pokreće čovjek uživo. Svaki poziv koji nešto mijenja upisuje se u audit trag trgovine: za strojni token tamo piše naziv tvoje API veze u Zitadelu (njezin client_id), ne ime osobe, jer je to za takav poziv i jedini točan podatak o tome tko ga je uputio.
Uloge i dozvole
Uloga se čita isključivo iz baze, po identitetu iz tokena. Ništa iz tijela zahtjeva ni iz zaglavlja na nju ne utječe. Tri su uloge, poredane: djelatnik (narudžbe, katalog, kategorije, sadržaj, uvoz), upravitelj (uz to povrat novca, kupci, postavke, naplata, teme, webhookovi) i vlasnik (uz to paket, domene, mail domena, osoblje). Svaka viša uloga smije sve što smije niža.
Ruta koja u pravilima nije izrijekom navedena zadano traži najvišu razinu (vlasnik), ne najnižu: nova ruta koja se zaboravi uvrstiti u pravila ostaje zatvorena, umjesto da se tiho otvori svima. Poziv tokenom bez dovoljne uloge vraća 403.
Što možeš raditi
API pokriva praktički sve što i CMS: katalog artikala i kategorija, narudžbe i njihove statuse, postavke trgovine, izgled i teme, statistiku, i izvoz podataka: katalog, kupci i narudžbe zajedno, u JSON-u ili CSV-u u ZIP datoteci.
Koristan je kad ti treba nešto što CMS sučelje ne prikazuje izravno, ili kad želiš automatizirati redovitu zadaću (na primjer redovit izvoz podataka u vlastiti sustav), umjesto da to radiš ručno.
Ograničenje broja poziva na sat postoji za pojedine rute, ne za cijeli API odjednom. Izvoz je jedan takav primjer: namjerno je ograničen na 10 poziva na sat, da slučajni skript koji zapne u petlji ne preoptereti tvoju trgovinu. Ostale rute takvo ograničenje nemaju.
Odgovori i format
Većina odgovora je JSON, isti oblik podataka koji koristi i sam CMS. Integracija koju napraviš vidi iste podatke i istu strukturu kao sučelje kojim se svakodnevno služiš. Izvoz je iznimka: uz JSON nudi i CSV, spakiran u ZIP datoteku, praktičniji za tablične alate poput Excela.
Greška dolazi kao JSON s poljem error (npr. {"error": "..."}), uz
odgovarajući HTTP status. Jedna iznimka kvari taj obrazac: pošalješ li
tijelo koje se ne da raščlaniti kao JSON, poruka je mješavina hrvatskog i
engleskog, jer joj se na kraj lijepi sirova Go poruka o grešci (npr. "json:
cannot unmarshal..."). Na sadržaj takve poruke se ne oslanjaj kao na
stabilan ugovor. HTTP status (400) jest pouzdan.
Veza s webhookovima
API i webhookovi rješavaju obrnute smjerove istog problema. API-jem TI dohvaćaš podatke kad ti zatrebaju: povlačenje. Webhook je obrnuto: WebShopHR TEBI odmah javi kad se nešto dogodi u tvojoj trgovini, guranje, bez da moraš stalno provjeravati. Sama registracija webhook adrese radi se kroz ovaj isti API, pa možeš koristiti jedno, drugo, ili oboje zajedno, ovisno što ti integraciji treba.
Povezane stranice
