Una clave por empresa
La clave la genera el administrador de la empresa en Ajustes. Se muestra una sola vez: nosotros guardamos solo su huella, así que ni siquiera nosotros podemos leerla.
API
Un almacén del que puedes sacar los datos
Una API REST sobre el mismo almacén que ves en la aplicación. Conéctale una tienda online, un ERP, Make.com o tu propio script. Está en todos los planes, incluido el Free: un almacén que no puedes probar a conectar antes de empezar a pagar es comprar a ciegas.
Ves cada llamada
Un historial con la dirección IP, el estado, la duración y la respuesta. Cuando una integración se rompe, no tienes que adivinar por qué.
El código de la etiqueta
Una llamada te dice qué es el código escaneado y dónde está. Puedes conectar tu propio lector en una tarde.
Autenticación
La clave en una cabecera, nada más
Sin OAuth, sin tokens que caducan. La clave va en un servidor, no en el navegador ni en una aplicación móvil, donde cualquiera puede leerla.
curl -H "Authorization: Bearer cstrg_ab12cd34_…" \
https://www.cloudstrg.sk/api/v1/infoQuien no pueda poner la cabecera Authorization (algunas herramientas low-code) envía la clave en X-Api-Key.
La respuesta siempre tiene la misma forma
{ "ok": true, "data": … }
{ "ok": false, "chyba": { "kod": "nenajdene", "sprava": "…" } }Así la integración no necesita mirar el estado HTTP para saber si ha funcionado: basta con ok. Las listas llevan además strankovanie con limit, offset y celkom.
Los estados que pueden llegarte
200/201— todo correcto401— clave ausente o no válida402— el plan está lleno, no cabe una nueva posición404— la cosa no existe o no pertenece a tu empresa422— parámetro ausente o sin sentido429— tope de llamadas superado; inténtalo en un minuto
Endpoints
15 llamadas que cubren casi todo
La base es https://www.cloudstrg.sk/api/v1. Las escrituras son a propósito solo dos: crear un contenedor y decir adónde ha ido. Cambiar la estructura del almacén por API no es posible: esa es una decisión para una persona delante de la estantería.
| Método | Ruta | Qué hace |
|---|---|---|
| GET |
/info
|
Quién soy, qué plan tengo y cuántas llamadas me quedan. |
| GET |
/sklady
|
Lista de almacenes. |
| GET |
/sklady/{id}
|
Un almacén. |
| GET |
/regaly?sklad_id=
|
Estanterías de un almacén. |
| GET |
/police?regal_id=
|
Baldas de una estantería. |
| GET |
/kontajnery
|
Cajas y archivadores. Filtros: sklad_id, polica_id, typ, stav, q, nezaradene, limit, offset. |
| GET |
/kontajnery/{id}
|
Un contenedor, con la lista de cosas de dentro. |
| POST |
/kontajnery
|
Crea un contenedor y le asigna un código. Cuerpo: nazov, typ, popis, polica_id. |
| POST |
/kontajnery/{id}/presun
|
Mueve un contenedor a una balda. Cuerpo: polica_id (null = sacarlo de la balda). |
| GET |
/kod/{kod}
|
Qué es este código de la etiqueta y dónde está. |
| GET |
/hladat?q=
|
Búsqueda entre cajas y las cosas que contienen. |
| GET |
/grafana/metriky
|
El estado del almacén ahora mismo como array plano, para paneles Stat. |
| GET |
/grafana/rad?metrika=
|
Serie temporal diaria sin huecos: hladania, otvorenia, pohyby, api. |
| GET |
/grafana/tabulka?co=
|
Filas listas para un panel Table: najhladanejsie, bez-vysledku, najziadanejsie, police, sklady. |
| GET |
/grafana/prometheus
|
Los mismos números en el formato de texto de Prometheus. |
Ejemplos
Las tres cosas que harás más a menudo
Qué es este código de la etiqueta
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"
}
}Encontrar una caja por algo que hay dentro
curl -H "Authorization: Bearer $KLUC" \
"https://www.cloudstrg.sk/api/v1/hladat?q=vŕtačka"Crear una caja y archivarla al momento
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/kontajneryEl código se asigna solo y vuelve en la respuesta; la etiqueta la imprimes después en la aplicación. De los códigos decide la aplicación a propósito, para que no puedan surgir dos iguales.
Grafana
Un panel sin acceso a la base de datos
Grafana no llega a nuestra base de datos, ni le hace falta: recibe cifras ya calculadas por HTTPS. Solo necesita una clave de API y un datasource.
Vía uno: datasource Infinity (sin Prometheus)
En Grafana añade un datasource Infinity, tipo JSON → URL, y en las cabeceras Authorization: Bearer cstrg_…. Las respuestas son arrays planos de objetos, así que no hay ningún root selector que configurar.
# Paneles Stat: el estado del almacén ahora mismo
https://www.cloudstrg.sk/api/v1/grafana/metriky
# Time series: búsquedas por día (también otvorenia, pohyby, api)
https://www.cloudstrg.sk/api/v1/grafana/rad?metrika=hladania&dni=30
# Table: a qué se recurre más
https://www.cloudstrg.sk/api/v1/grafana/tabulka?co=najziadanejsie&dni=30La serie siempre tiene una fila por día, también los días en que no pasó nada. Sin eso, Grafana uniría el día tres y el día siete con una recta, como si entre medias se hubiera trabajado.
Vía dos: Prometheus (si ya tienes scrape)
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']Ambas vías devuelven las mismas cifras, así que se pueden combinar.
Una cosa a tener en cuenta
Las llamadas de Grafana cuentan para el mismo tope que las demás. Refrescar cada 10 segundos son 360 llamadas por hora por panel: con diez paneles agotarías incluso el plan Free en ocho minutos. Pon el intervalo en un minuto; las cifras del almacén no cambian más rápido.
Límites
Todos los planes tienen API
Solo cambia el tope de llamadas por hora. Cada respuesta lleva X-RateLimit-Limit y X-RateLimit-Remaining, así que la integración sabe cómo va sin tener que adivinarlo.
Free
500 llamadas por hora — gratis
Start
2.000 llamadas por hora
Profi
10.000 llamadas por hora
Sklad
50.000 llamadas por hora
El tope es por empresa, no por clave: creas varias claves por claridad, no por margen. Al superarlo llega un 429 y la cabecera Retry-After; no se borra nada y en un minuto todo sigue.
Empieza por una sola estantería
En una hora tienes numerada la primera estantería. En una tarde, todo el almacén.
El plan Free es gratuito y sin límite de tiempo: 30 posiciones bastan para una estantería y para comprobar si te encaja. El plan de pago lo eliges cuando se te acabe el sitio.