API

一个能把数据取出来的仓库

这是建立在你在应用里看到的同一个仓库之上的 REST API。你可以把网店、ERP、Make.com 或自己写的脚本接上去。所有套餐都有，包括 Free——一个在付费之前都没法试着对接的仓库，无异于买椟还珠。

每家公司一把密钥

密钥由公司管理员在「设置」里生成，只显示一次——我们这边只保存它的指纹，所以连我们自己也读不出来。

每一次调用你都看得见

历史记录里有 IP 地址、状态、耗时和响应。对接出问题时，不用靠猜。

标签上的编号

一次调用就能告诉你扫到的编号是什么、在哪里。自己的扫描枪一个下午就能接上。

身份验证

请求头里放密钥，仅此而已

没有 OAuth，也没有会过期的令牌。密钥应该放在服务器上——不要放进浏览器或手机应用，那里谁都能读到。

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

如果设不了 Authorization 请求头（某些低代码工具就是如此），可以把密钥放在 X-Api-Key 里。

响应的结构始终一致

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

这样对接方不必看 HTTP 状态码就能知道是否成功——看 ok 就够了。列表还会带上 strankovanie，其中包含 limit、offset 和 celkom。

你可能收到的状态码

200 / 201 — 一切正常
401 — 缺少密钥或密钥无效
402 — 套餐已满，放不下新的货位
404 — 该对象不存在，或者不属于你的公司
422 — 参数缺失或不合理
429 — 超出调用上限；过一分钟再试

接口

15 个调用，足以覆盖大部分场景

基础地址是 https://www.cloudstrg.sk/api/v1。写操作刻意只有两个——创建容器，以及说明它去了哪里。通过 API 改动仓库结构是不行的：那应该由站在货架前的人来决定。

方法	路径	作用
GET	`/info`	我是谁、用的哪个套餐、还剩多少次调用。
GET	`/sklady`	仓库列表。
GET	`/sklady/{id}`	单个仓库。
GET	`/regaly?sklad_id=`	某个仓库里的货架。
GET	`/police?regal_id=`	某个货架上的层板。
GET	`/kontajnery`	纸箱和文件夹。筛选：sklad_id、polica_id、typ、stav、q、nezaradene、limit、offset。
GET	`/kontajnery/{id}`	单个容器，连同里面的物品清单。
POST	`/kontajnery`	创建容器并分配编号。请求体：nazov、typ、popis、polica_id。
POST	`/kontajnery/{id}/presun`	把容器移到某个层板。请求体：polica_id（null = 从层板取下）。
GET	`/kod/{kod}`	标签上的这个编号是什么、放在哪里。
GET	`/hladat?q=`	跨箱子及其内部物品的查找。
GET	`/grafana/metriky`	仓库此刻的状态，扁平数组形式——供 Stat 面板使用。
GET	`/grafana/rad?metrika=`	按天的时间序列，没有空缺：hladania、otvorenia、pohyby、api。
GET	`/grafana/tabulka?co=`	给 Table 面板准备好的行：najhladanejsie、bez-vysledku、najziadanejsie、police、sklady。
GET	`/grafana/prometheus`	同样的数字，以 Prometheus 文本格式输出。

示例

你最常做的三件事

标签上的这个编号是什么

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

根据箱子里的东西找到箱子

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

创建一个箱子并立刻归位

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

编号会自动分配，并在响应里返回——标签随后在应用里打印。编号由应用决定是有意为之，这样才不会出现两个相同的编号。

Grafana

不碰数据库的仪表盘

Grafana 接触不到我们的数据库，也不需要——它通过 HTTPS 拿到算好的数字。只要一把 API 密钥和一个数据源就够了。

第一条路：Infinity 数据源（不用 Prometheus）

在 Grafana 里添加 Infinity 数据源，类型选 JSON → URL，请求头填 Authorization: Bearer cstrg_…。返回的就是裸的对象数组，所以不需要设置任何 root selector。

# Stat 面板——仓库此刻的状态
https://www.cloudstrg.sk/api/v1/grafana/metriky

# Time series——按天的查找次数（otvorenia、pohyby、api 同理）
https://www.cloudstrg.sk/api/v1/grafana/rad?metrika=hladania&dni=30

# Table——哪些东西被取用得最多
https://www.cloudstrg.sk/api/v1/grafana/tabulka?co=najziadanejsie&dni=30

这个序列每天都有一行——包括什么都没发生的日子。否则 Grafana 会把第三天和第七天用一条直线连起来，看上去像是中间一直在作业。

第二条路：Prometheus（如果你已经在 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']

两条路返回的是同样的数字，所以也可以混着用。

有一点要注意

Grafana 的调用和其他调用共用同一个上限。每 10 秒刷新一次，每个面板每小时就是 360 次调用——十个面板的话，连 Free 套餐都能在八分钟内用完。把刷新间隔设成一分钟；仓库的数字本来也变不了那么快。

限额

每个套餐都有 API

区别只在每小时的调用上限。每个响应都带有 X-RateLimit-Limit 和 X-RateLimit-Remaining，所以对接方不用猜就知道自己用到哪儿了。

Free

每小时 500 次调用 — 免费

Start

每小时 2,000 次调用

Profi

每小时 10,000 次调用

Sklad

每小时 50,000 次调用

上限是按公司算的，不是按密钥——所以多建几把密钥是为了分得清楚，而不是为了多拿额度。超限时会返回 429 和 Retry-After 响应头；什么都不会被删除，一分钟后照常继续。