API

Un magazzino da cui i dati possono uscire

Un’API REST sullo stesso magazzino che vedi nell’app. Collegaci un e-commerce, un ERP, Make.com o uno script tuo. C’è in tutti i piani, Free compreso: un magazzino che non puoi provare a collegare prima di iniziare a pagare è un salto nel buio.

Una chiave per azienda

La chiave la genera l’amministratore dell’azienda nelle Impostazioni. Si vede una sola volta: da noi resta solo la sua impronta, quindi non possiamo rileggerla nemmeno noi.

Vedi ogni chiamata

Uno storico con indirizzo IP, stato, durata e risposta. Quando un’integrazione va in pezzi non devi indovinare perché.

Il codice dall’etichetta

Una chiamata dice cos’è il codice scansionato e dove si trova. Il tuo lettore lo colleghi così in un pomeriggio.

Autenticazione

La chiave in un header, nient’altro

Niente OAuth, niente token con scadenza. La chiave sta su un server, non nel browser né in un’app mobile, dove chiunque può leggerla.

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

Chi non riesce a impostare l’header Authorization (alcuni strumenti low-code) manda la chiave in X-Api-Key.

La risposta ha sempre la stessa forma

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

Così l’integrazione non deve guardare lo stato HTTP per sapere se ha avuto successo: basta ok. Gli elenchi hanno in più strankovanie con limit, offset e celkom.

Gli stati che ti possono arrivare

200 / 201 — tutto a posto
401 — chiave mancante o non valida
402 — il piano è pieno, una nuova posizione non ci sta
404 — la cosa non esiste o non appartiene alla tua azienda
422 — parametro mancante o privo di senso
429 — tetto di chiamate superato; riprova tra un minuto

Endpoint

15 chiamate che coprono quasi tutto

La base è https://www.cloudstrg.sk/api/v1. Le scritture sono volutamente solo due: creare un contenitore e dire dov’è andato. Cambiare la struttura del magazzino via API non si può: è una decisione che spetta a una persona davanti allo scaffale.

Metodo	Percorso	Che cosa fa
GET	`/info`	Chi sono, che piano ho e quante chiamate mi restano.
GET	`/sklady`	Elenco dei magazzini.
GET	`/sklady/{id}`	Un magazzino.
GET	`/regaly?sklad_id=`	Scaffali di un magazzino.
GET	`/police?regal_id=`	Ripiani di uno scaffale.
GET	`/kontajnery`	Scatole e raccoglitori. Filtri: sklad_id, polica_id, typ, stav, q, nezaradene, limit, offset.
GET	`/kontajnery/{id}`	Un contenitore, con l’elenco delle cose all’interno.
POST	`/kontajnery`	Crea un contenitore e gli assegna un codice. Corpo: nazov, typ, popis, polica_id.
POST	`/kontajnery/{id}/presun`	Sposta un contenitore su un ripiano. Corpo: polica_id (null = toglierlo dal ripiano).
GET	`/kod/{kod}`	Cos’è questo codice dall’etichetta e dove si trova.
GET	`/hladat?q=`	Ricerca tra le scatole e le cose al loro interno.
GET	`/grafana/metriky`	Lo stato del magazzino adesso come array piatto — per i pannelli Stat.
GET	`/grafana/rad?metrika=`	Serie temporale giornaliera senza buchi: hladania, otvorenia, pohyby, api.
GET	`/grafana/tabulka?co=`	Righe pronte per un pannello Table: najhladanejsie, bez-vysledku, najziadanejsie, police, sklady.
GET	`/grafana/prometheus`	Gli stessi numeri nel formato testuale di Prometheus.

Esempi

Le tre cose che farai più spesso

Cos’è questo codice dall’etichetta

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"
  }
}

Trovare una scatola da qualcosa che c’è dentro

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

Creare una scatola e collocarla subito

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

Il codice viene assegnato da solo e torna nella risposta: l’etichetta la stampi poi nell’app. Sui codici decide l’app di proposito, perché non possano nascerne due uguali.

Grafana

Una dashboard senza accesso al database

Grafana al nostro database non arriva, e non serve: riceve numeri già pronti via HTTPS. Le bastano una chiave API e un datasource.

Prima via: datasource Infinity (senza Prometheus)

In Grafana aggiungi un datasource Infinity, tipo JSON → URL, e negli header Authorization: Bearer cstrg_…. Le risposte sono array nudi di oggetti, quindi non c’è nessun root selector da impostare.

# Pannelli Stat — lo stato del magazzino adesso
https://www.cloudstrg.sk/api/v1/grafana/metriky

# Time series — ricerche per giorno (anche otvorenia, pohyby, api)
https://www.cloudstrg.sk/api/v1/grafana/rad?metrika=hladania&dni=30

# Table — a cosa si ricorre di più
https://www.cloudstrg.sk/api/v1/grafana/tabulka?co=najziadanejsie&dni=30

La serie ha sempre una riga al giorno, anche nei giorni in cui non è successo nulla. Senza, Grafana unirebbe il terzo e il settimo giorno con una retta, come se nel frattempo si fosse lavorato.

Seconda via: Prometheus (se lo scrape ce l’hai già)

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']

Entrambe le vie restituiscono gli stessi numeri, quindi si possono anche combinare.

Una cosa a cui fare attenzione

Le chiamate per Grafana rientrano nello stesso tetto delle altre. Un aggiornamento ogni 10 secondi fa 360 chiamate all’ora per pannello: con dieci pannelli esauriresti anche il piano Free in otto minuti. Imposta l’intervallo a un minuto; i numeri del magazzino non cambiano più in fretta.

Limiti

L’API ce l’ha ogni piano

Cambia solo il tetto di chiamate all’ora. Ogni risposta porta X-RateLimit-Limit e X-RateLimit-Remaining, così l’integrazione sa come sta messa senza doverlo indovinare.

Free

500 chiamate all’ora — gratis

Start

2.000 chiamate all’ora

Profi

10.000 chiamate all’ora

Sklad

50.000 chiamate all’ora

Il tetto è per azienda, non per chiave: più chiavi le crei per chiarezza, non per margine. Al superamento arriva un 429 e l’header Retry-After; non si cancella nulla e dopo un minuto tutto riparte.