Autentifikácia

Kľúč vám vystaví Ragnetiq. Každý produkt má vlastné kľúče a kľúč platí iba pre API svojho produktu; rozoznáte ich podľa predpony:

Produkt	Predpona kľúča	Základná adresa API
AI asistent	`as_`	`https://asistent.ragnetiq.com/api/stats/v1`
Smart Search	`ss_`	`https://search.ragnetiq.com/api/stats/v1`
SmartBox	`sb_`	`https://smartbox.ragnetiq.com/api/stats/v1`

Kľúč má tvar predpona a 64 hexadecimálnych znakov. Posielajte ho v hlavičke Authorization pri každej požiadavke:

Authorization: Bearer sb_9f2c1a7e…

Kľúč je tajný ako heslo. Používajte ho len zo servera (cron, backend, ETL), nikdy nie v prehliadači ani v mobilnej aplikácii. Ak unikne, napíšte nám: starý kľúč odvoláme a vystavíme nový; odvolaný kľúč prestane fungovať okamžite.

Neplatný, chýbajúci alebo odvolaný kľúč dostane odpoveď 401 unauthorized. Kľúč, ktorý nemá prístup k požadovaným dátam (obchodu, pri SmartBoxe a AI asistentovi aj jazykovej mutácii), dostane 403 forbidden.

Požiadavky a odpovede

Požiadavky sú iba GET; API nič nemení.
Odpovede sú JSON v UTF-8 s hlavičkou cache-control: no-store.
Časy záznamov (occurred_at) sú ISO 8601 v UTC.
Tržby v rôznych menách sa nikdy nesčítavajú, sú rozdelené podľa meny.
Neukladáme osobné údaje zákazníkov: identifikátory návštevníka a relácie sú náhodné.

Obdobie

Dáta za obdobie si vyberáte parametrami v adrese:

Parameter	Hodnota	Význam
`from`	`YYYY-MM-DD`, voliteľný	Prvý deň obdobia (vrátane). Predvolene 29 dní pred `to`.
`to`	`YYYY-MM-DD`, voliteľný	Posledný deň obdobia (vrátane). Predvolene dnes. Obdobie môže mať najviac 366 dní.
`after`, `limit`	celé čísla	Stránkovanie surových dát, pozri nižšie.

Deň začína a končí o polnoci v Bratislave (Europe/Bratislava), rovnako ako v administrácii; každá odpoveď to uvádza v poli timezone.

Stránkovanie

Endpointy so surovými dátami (Smart Search /events a /purchases, SmartBox /events a /orders) vracajú najviac 1 000 záznamov naraz, zoradených od najstaršieho. Odpoveď obsahuje next: id posledného záznamu strany, alebo null, keď už ďalšia strana nie je. Ďalšiu stranu si vyžiadate parametrom after=<next>. Veľkosť strany určuje limit (1 – 1 000, predvolene 1 000).

Id záznamov sú stále a rastú s časom, takže after môžete použiť aj na prírastkové sťahovanie: zapamätajte si posledné id a nabudúce začnite od neho.

Výnimka: konverzácie AI asistenta (/conversations) majú najviac 200 záznamov na stranu a next je nepriehľadný kurzor, nie číslo; posielate ho späť rovnako v after. Pozri AI asistent.

Limity

Najviac 120 požiadaviek za minútu na jeden kľúč; pri prekročení dostanete 429 rate_limited.
Obdobie najviac 366 dní; dlhšiu históriu stiahnete po častiach.
Dáta sú dostupné do niekoľkých sekúnd po tom, čo sa udalosť stala, takže čísla za dnešný deň sa priebežne menia. Pre uzavreté čísla sťahujte včerajší deň a staršie.

Chyby

Chybová odpoveď má vždy rovnaký tvar: HTTP stavový kód, pole error so strojovým kódom a message s vysvetlením.

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

{ "error": "forbidden", "message": "Kľúč nemá prístup k niektorému z požadovaných obchodov." }

HTTP	`error`	Kedy
400	`invalid_period`	`from`/`to` nie sú dátumy, `to` je pred `from`, alebo obdobie presahuje 366 dní.
400	`invalid_shop`, `invalid_param`, …	Nesprávny tvar niektorého parametra. Zoznam kódov pre konkrétne API je na jeho stránke.
401	`unauthorized`	Chýbajúci, neplatný alebo odvolaný kľúč.
403	`forbidden`	Kľúč nepokrýva niektorý z požadovaných obchodov (pri SmartBoxe a AI asistentovi aj jazykových mutácií).
429	`rate_limited`	Viac ako 120 požiadaviek za minútu. Počkajte a skúste znova.
502, 503	`upstream`, `unavailable`	Dočasný výpadok na našej strane. Zopakujte požiadavku neskôr.

Verzie a zmeny

Verzia je v adrese (/v1). Nové polia môžeme pridávať kedykoľvek; existujúce polia a ich význam v rámci verzie nemeníme. O prípadnej novej verzii vás vopred informujeme.

Verzia je súčasťou cesty API (/api/stats/v1), nie adresy dokumentácie: stránka vždy popisuje aktuálnu verziu. Zoznam zmien má každé API na svojej stránke: AI asistent, Smart Search, SmartBox.

Základy API