文档报告与数据

API

从你自己的工具读取研究、结果、设备和目录，或推送运行数据，每个集成一把密钥。

1 分钟阅读7 个章节

API 用于这样的时刻：报价工具想要研究的吞吐量和回收期，而不用有人从报告里抄数字；或者车队经理想不用表格就把每日运行数据送进来。它在 Team 和 Enterprise 提供，auddomate.com 和自托管安装皆可。它返回的一切就是你在应用里看到的：同一支车队，同样的假设，同样的算术。

密钥

所有者在设置 → API 密钥创建密钥。以将要使用它的系统命名，勾选它可以做什么，并在密钥出现时复制 — 只显示一次，并以哈希形式存储。一把密钥有一个或多个范围：

read: 研究、结果、设备和目录。每把密钥都有。
telemetry: 向研究写入遥测行。
audit: 读取审计日志。

在同一页面撤销密钥；仍在使用它的任何东西从那一刻起会收到 401。创建和撤销密钥本身也会写入审计日志。每个组织最多二十把有效密钥。

调用

每个请求以 bearer 令牌形式携带密钥。基础地址是你的 Auddomate 地址加上 /api/v1。

bash

curl -H "Authorization: Bearer aud_…" https://auddomate.com/api/v1/me

如果你和服务器之间有什么剥离了 Authorization 头，改用 X-Api-Key: aud_… 发送。响应是结构稳定的 JSON：

json

{ "ok": true, "data": …, "meta": { "page": 1, "per_page": 50, "total": 132, "pages": 3 } }
{ "ok": false, "error": "not_found", "message": "No study ST-9999 in this organisation." }

列表用 ?page= 和 ?per_page=（最多 200）分页。时间是服务器本地时间，格式 YYYY-MM-DD HH:MM:SS；长度是毫米，距离是米，速率是每小时或每天，与应用中完全一致。每把密钥每分钟可发 300 个请求；超出后得到带 Retry-After 头的 429。

端点

GET /api/v1/me: 组织、密钥的名称和范围、版本类型和速率限制。用它检查密钥是否可用。
GET /api/v1/studies: 每份研究：参考编号、名称、场地、客户、状态、当前方案的吞吐量判定和余量，以及其车队的台数。用 ?status=、?client= 或 ?updated_since=2026-09-01 筛选。
GET /api/v1/studies/{ref}: 一份完整的研究，按参考编号（ST-1001）或 id：图纸（文件、比例、范围、货架、通道、月台和障碍物数量），以及每个方案的车队行、假设、逐行吞吐量结果、针对要求最高设备的通道检查，以及那是哪台设备。
GET /api/v1/studies/{ref}/telemetry: 一份研究的运行数据，每台设备每天一行。
GET /api/v1/studies/{ref}/pdf: 在服务器生成的 PDF 报告文件。?lang= 和 ?units=imperial 选择语言和单位。已保存版本用 /versions/{n}/pdf。
GET /api/v1/studies/{ref}/versions: 一份研究的已保存版本，最新在前；/versions/{n} 以与研究本身相同的结构返回完整的一个，?diff=1 附加此后的变化。
POST /api/v1/studies/{ref}/telemetry: 写入运行数据。需要 telemetry 范围。发送 {"rows": [...]}，最多 5 000 行；每行用 machine_id 或 machine（其确切名称）指定设备，一个 day，以及 moves、run_minutes、idle_minutes、distance_km、faults 中的任意项。已存在的设备与日期的行会被替换。响应说明写入了多少，并列出前五十个被跳过的行及原因。
GET /api/v1/machines: 你的设备库，每个档案及其数字，对目录型号还有其来源规格表。单个用 /machines/{id}。
GET /api/v1/catalogue: 真实品牌与型号的目录及其来源规格表。用 ?vendor= 或 ?class= 筛选。
GET /api/v1/audit: 审计日志，最新在前。需要 audit 范围。用 ?group=、?from=、?to=、?q= 筛选。

研究的结构

json

{
  "ref": "ST-1002", "name": "Cold store aisle audit", "status": "review",
  "plan": { "file": "cold-store.dxf", "scale": { "mm_per_unit": 1, "source": "dxf" },
            "extent_mm": { "width": 61000, "height": 45000 },
            "shapes": { "rack": 6, "aisle": 5, "dock": 1, "block": 3 } },
  "scenarios": [ {
    "name": "Base", "current": true,
    "fleet": [ { "machine": "VNA turret, 1.0 t", "class": "vna", "qty": 3, "shifts": 2 } ],
    "assumptions": { "moves_required": 2110, "hours_per_shift": 8, "days_per_year": 300,
                     "distance_m": 14, "distance_source": "plan", "handling_s": 55 },
    "throughput": { "verdict": "meets", "moves_per_day": 3024.6, "required_per_day": 2110,
                    "headroom_per_day": 914.6, "utilisation_pct": 69.8, "lines": [ … ] },
    "aisles": { "verdict": "fail", "aisle_min_mm": 2100, "narrowest_mm": 1800, "aisles": 5, "below": 5 },
    "checked_against": { "machine": "Pallet truck, pedestrian 1.6 t", "aisle_min_mm": 2100 }
  } ]
}

throughput.verdict 是 meets、short、nofleet、nodistance 或 notarget 之一；aisles.verdict 是 pass、fail、noplan、noscale、noaisles 或 none 之一。distance_source 说明行驶距离是输入的还是从图纸推导的，与模拟页面一致。

发送运行数据

bash

curl -X POST https://auddomate.com/api/v1/studies/ST-1002/telemetry \
  -H "Authorization: Bearer aud_…" -H "Content-Type: application/json" \
  -d '{"rows": [
        {"machine": "VNA turret, 1.0 t", "day": "2026-09-01", "moves": 412, "run_minutes": 480, "idle_minutes": 60, "distance_km": 18.4, "faults": 1},
        {"machine_id": 327, "day": "2026-09-02", "moves": 390}
      ]}'

json

{ "ok": true, "data": { "written": 2, "skipped": 0, "errors": [] } }

错误

401 unauthorised: 没有密钥，或我们不认识的密钥。
401 revoked: 密钥已被撤销；消息说明何时。
403 plan: 组织处于免费或 Studio 方案。
403 scope: 密钥缺少端点所需的范围。
404 not_found: 没有这样的研究、设备或端点。
400 json / empty: 正文不是 JSON 对象，或没有行。
413 too_many: 一次遥测请求超过 5 000 行。
429 rate_limited: 一分钟内超过 300 个请求。等待 Retry-After 秒。

版本管理

路径携带版本。字段会随时间加入 v1，但绝不重命名或移除；任何会破坏客户端的改动都会成为 v2，v1 至少并行保留一年。变更与其他一切一样列在更新日志中。

API 只读写密钥所属的组织，别无其他 — 没有任何密钥能触及另一个组织的研究。像对待密码一样对待密钥：每个系统一把，系统退役时撤销。