API

Sklad, z ktorého sa dajú dostať dáta von

REST API nad tým istým skladom, ktorý vidíte v appke. Napojíte naň e-shop, ERP, Make.com alebo vlastný skript. Je vo všetkých balíkoch vrátane Free — sklad, ktorý si nemôžete vyskúšať napojiť ešte predtým, než začnete platiť, je mačka vo vreci.

Kľúč na firmu

Kľúč vygeneruje admin firmy v Nastaveniach. Vidí sa raz — u nás je uložený len jeho odtlačok, takže ho ani my prečítať nevieme.

Vidíte každé volanie

História s IP adresou, stavom, trvaním aj odpoveďou. Keď sa integrácia sype, nemusíte hádať prečo.

Kód zo štítku

Jedno volanie povie, čo je naskenovaný kód a kde leží. Vlastnú čítačku tak napojíte za popoludnie.

Overenie

Kľúč v hlavičke, nič iné

Žiadne OAuth, žiadne tokeny s expiráciou. Kľúč patrí na server — nie do prehliadača ani do mobilnej appky, odkiaľ si ho ktokoľvek prečíta.

curl -H "Authorization: Bearer cstrg_ab12cd34_…" \
  https://www.cloudstrg.sk/api/v1/info

Kto hlavičku Authorization nastaviť nevie (niektoré low-code nástroje), pošle kľúč v X-Api-Key.

Odpoveď má vždy rovnaký tvar

{ "ok": true,  "data": … }
{ "ok": false, "chyba": { "kod": "nenajdene", "sprava": "…" } }

Integrácia sa tak nemusí pozerať na HTTP stav, aby vedela, či uspela — stačí ok. Zoznamy majú navyše strankovanie s limit, offset a celkom.

Stavy, ktoré vám môžu prísť

200 / 201 — v poriadku
401 — chýbajúci alebo neplatný kľúč
402 — balík je plný, nová pozícia sa doň nezmestí
404 — vec neexistuje alebo nepatrí vašej firme
422 — chýbajúci či nezmyselný parameter
429 — prekročený strop volaní; skúste o minútu

Koncové body

15 volaní, ktoré pokryjú väčšinu

Základ je https://www.cloudstrg.sk/api/v1. Zápisy sú zámerne len dva — založiť kontajner a povedať, kam putoval. Meniť štruktúru skladu cez API nejde: to je rozhodnutie, ktoré má urobiť človek pri regáli.

Metóda	Cesta	Čo robí
GET	`/info`	Kto som, aký mám balík a koľko volaní mi zostáva.
GET	`/sklady`	Zoznam skladov.
GET	`/sklady/{id}`	Jeden sklad.
GET	`/regaly?sklad_id=`	Regály v sklade.
GET	`/police?regal_id=`	Police v regáli.
GET	`/kontajnery`	Krabice a šanóny. Filtre: sklad_id, polica_id, typ, stav, q, nezaradene, limit, offset.
GET	`/kontajnery/{id}`	Jeden kontajner aj so zoznamom vecí vnútri.
POST	`/kontajnery`	Založí kontajner a pridelí mu kód. Telo: nazov, typ, popis, polica_id.
POST	`/kontajnery/{id}/presun`	Presunie kontajner na policu. Telo: polica_id (null = vyradiť z police).
GET	`/kod/{kod}`	Čo je tento kód zo štítku a kde to leží.
GET	`/hladat?q=`	Hľadanie naprieč krabicami aj vecami v nich.
GET	`/grafana/metriky`	Okamžitý stav skladu ako ploché pole — pre Stat panely.
GET	`/grafana/rad?metrika=`	Časový rad po dňoch bez dier: hladania, otvorenia, pohyby, api.
GET	`/grafana/tabulka?co=`	Hotové riadky pre Table panel: najhladanejsie, bez-vysledku, najziadanejsie, police, sklady.
GET	`/grafana/prometheus`	Tie isté čísla v textovom formáte Prometheusa.

Ukážky

Tri veci, ktoré budete robiť najčastejšie

Čo je tento kód zo štítku

curl -H "Authorization: Bearer $KLUC" \
  https://www.cloudstrg.sk/api/v1/kod/K-9WZ2QK

{
  "ok": true,
  "data": {
    "typ": "kontajner",
    "kod": "K-9WZ2QK",
    "id": 412,
    "nazov": "Účtovníctvo 2023",
    "popis": "Košice · R1 · R1-2"
  }
}

Nájsť krabicu podľa veci v nej

curl -H "Authorization: Bearer $KLUC" \
  "https://www.cloudstrg.sk/api/v1/hladat?q=vŕtačka"

Založiť krabicu a rovno ju zaradiť

curl -X POST -H "Authorization: Bearer $KLUC" \
  -H "Content-Type: application/json" \
  -d '{"nazov":"Faktúry 2026","typ":"sanon","polica_id":12}' \
  https://www.cloudstrg.sk/api/v1/kontajnery

Kód sa pridelí sám a vráti sa v odpovedi — štítok si naň potom vytlačíte v appke. O kódoch rozhoduje appka zámerne, aby nemohli vzniknúť dva rovnaké.

Grafana

Dashboard bez prístupu do databázy

Grafana sa k našej databáze nedostane a ani nemá — dostane hotové čísla cez HTTPS. Stačí jej API kľúč a jeden datasource.

Cesta prvá: Infinity datasource (bez Prometheusa)

V Grafane pridajte datasource Infinity, typ JSON → URL, a do hlavičiek Authorization: Bearer cstrg_…. Odpovede sú holé polia objektov, takže sa nenastavuje žiadny root selector.

# Stat panely — stav skladu práve teraz
https://www.cloudstrg.sk/api/v1/grafana/metriky

# Time series — hľadania po dňoch (aj otvorenia, pohyby, api)
https://www.cloudstrg.sk/api/v1/grafana/rad?metrika=hladania&dni=30

# Table — po čom sa najviac siaha
https://www.cloudstrg.sk/api/v1/grafana/tabulka?co=najziadanejsie&dni=30

Rad má vždy jeden riadok na deň — aj za dni, keď sa nič nedialo. Bez toho by Grafana spojila tretí a siedmy deň priamkou, akoby sa medzitým pracovalo.

Cesta druhá: Prometheus (keď scrape už máte)

scrape_configs:
  - job_name: cloudstrg
    scrape_interval: 60s
    metrics_path: /api/v1/grafana/prometheus
    scheme: https
    authorization:
      credentials: cstrg_ab12cd34_…
    static_configs:
      - targets: ['www.cloudstrg.sk']

Obe cesty vracajú tie isté čísla, takže sa dajú aj kombinovať.

Jedna vec, na ktorú pozor

Volania pre Grafanu sa počítajú do rovnakého stropu ako ostatné. Obnova každých 10 sekúnd je 360 volaní za hodinu na jeden panel — pri desiatich paneloch aj Free balík vyčerpáte za osem minút. Nastavte interval na minútu; skladové čísla sa rýchlejšie nemenia.

Limity

API má každý balík

Líši sa len strop volaní na hodinu. Každá odpoveď nesie X-RateLimit-Limit a X-RateLimit-Remaining, takže integrácia vie, ako je na tom, bez toho aby to musela hádať.

Free

500 volaní za hodinu — zadarmo

Štart

2 000 volaní za hodinu

Profi

10 000 volaní za hodinu

Sklad

50 000 volaní za hodinu

Strop je na firmu, nie na kľúč — viac kľúčov si teda vytvoríte kvôli prehľadu, nie kvôli limitu. Pri prekročení príde 429 a hlavička Retry-After; nič sa nemaže a o minútu ide všetko ďalej.

Začnite jedným regálom

Za hodinu máte očíslovaný prvý regál. Za popoludnie celý sklad.

Free balík je zadarmo a bez časového obmedzenia — 30 pozícií stačí na jeden regál aj na to, aby ste zistili, či vám to sadne. Platený balík si vyberiete až keď vám miesto dôjde.

Vyskúšať zadarmo Chcem to prebrať s vami