Doku Berichte und Daten

Die API

Studien, Ergebnisse, Maschinen und den Katalog aus Ihren eigenen Werkzeugen lesen oder Betriebsdaten hineinschieben, mit einem Schlüssel je Integration.

5 Min. Lesezeit7 Abschnitte

Die API ist für den Moment, in dem ein Angebotswerkzeug Durchsatz und Amortisation einer Studie will, ohne dass jemand Zahlen aus einem Bericht abschreibt, oder ein Flottenmanager tägliche Betriebsdaten ohne Tabellenkalkulation einsenden will. Sie ist in Team und Enterprise verfügbar, auf auddomate.com wie auf selbst gehosteten Installationen. Alles, was sie zurückgibt, ist das, was Sie in der App sehen: dieselbe Flotte, dieselben Annahmen, dieselbe Arithmetik.

#Schlüssel

Inhaber erstellen Schlüssel unter Einstellungen → API-Schlüssel. Benennen Sie jeden nach dem System, das ihn verwenden wird, haken Sie an, was er darf, und kopieren Sie den Schlüssel, wenn er erscheint — er wird einmal angezeigt und gehasht gespeichert. Ein Schlüssel hat einen oder mehrere Bereiche:

read: Studien, Ergebnisse, Maschinen und der Katalog. Jeder Schlüssel hat dies.
telemetry: Telemetriezeilen in eine Studie schreiben.
audit: Das Audit-Protokoll lesen.

Ziehen Sie einen Schlüssel auf derselben Seite zurück; alles, was ihn noch verwendet, erhält ab diesem Moment 401. Das Erstellen und Zurückziehen von Schlüsseln wird selbst ins Audit-Protokoll geschrieben. Bis zu zwanzig aktive Schlüssel je Organisation.

#Aufrufen

Jede Anfrage trägt den Schlüssel als Bearer-Token. Die Basisadresse ist Ihre Auddomate-Adresse gefolgt von /api/v1.

bash

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

Wenn etwas zwischen Ihnen und dem Server den Authorization-Header entfernt, senden Sie ihn stattdessen als X-Api-Key: aud_…. Antworten sind JSON mit stabiler Form:

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

Listen blättern mit ?page= und ?per_page= (bis 200). Zeiten sind die Ortszeit des Servers als YYYY-MM-DD HH:MM:SS; Längen sind Millimeter, Strecken Meter, Raten je Stunde oder je Tag, genau wie in der App. Jeder Schlüssel darf 300 Anfragen pro Minute stellen; darüber erhalten Sie 429 mit einem Retry-After-Header.

#Endpunkte

GET /api/v1/me: Die Organisation, Name und Bereiche des Schlüssels, die Edition und das Ratenlimit. Damit prüfen Sie, ob ein Schlüssel funktioniert.
GET /api/v1/studies: Jede Studie: Referenz, Name, Standort, Kunde, Status, das Durchsatzurteil und die Reserve des aktuellen Szenarios sowie die Anzahl der Einheiten in ihrer Flotte. Filtern mit ?status=, ?client= oder ?updated_since=2026-09-01.
GET /api/v1/studies/{ref}: Eine Studie vollständig, nach Referenz (ST-1001) oder ID: der Plan (Datei, Maßstab, Ausdehnung, wie viele Regale, Gänge, Rampen und Hindernisse) und jedes Szenario mit seinen Flottenzeilen, Annahmen, dem Durchsatzergebnis Zeile für Zeile, der Gangprüfung gegen die anspruchsvollste Maschine und welche Maschine das war.
GET /api/v1/studies/{ref}/telemetry: Die Betriebsdaten einer Studie, eine Zeile je Maschine und Tag.
GET /api/v1/studies/{ref}/pdf: Der Bericht als PDF-Datei, auf dem Server erzeugt. ?lang= und ?units=imperial wählen Sprache und Einheiten. /versions/{n}/pdf für eine gespeicherte Version.
GET /api/v1/studies/{ref}/versions: Die gespeicherten Versionen einer Studie, neueste zuerst; /versions/{n} liefert eine vollständig in derselben Form wie die Studie selbst, und ?diff=1 ergänzt, was sich seitdem geändert hat.
POST /api/v1/studies/{ref}/telemetry: Betriebsdaten schreiben. Braucht den Bereich telemetry. Senden Sie {"rows": [...]}, bis zu 5 000 Zeilen; jede Zeile benennt die Maschine per machine_id oder machine (ihr exakter Name), einen day und beliebige von moves, run_minutes, idle_minutes, distance_km, faults. Eine Zeile für eine bereits vorhandene Maschine und einen bereits vorhandenen Tag wird ersetzt. Die Antwort sagt, wie viele geschrieben wurden, und listet die ersten fünfzig übersprungenen Zeilen mit Begründung.
GET /api/v1/machines: Ihre Maschinenbibliothek, jedes Profil mit seinen Werten und, bei Katalogmodellen, das Datenblatt, aus dem es stammt. /machines/{id} für eines.
GET /api/v1/catalogue: Der Katalog echter Marken und Modelle mit ihren Quelldatenblättern. Filtern mit ?vendor= oder ?class=.
GET /api/v1/audit: Das Audit-Protokoll, neueste zuerst. Braucht den Bereich audit. Filtern mit ?group=, ?from=, ?to=, ?q=.

#Wie eine Studie aussieht

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 ist eines von meets, short, nofleet, nodistance oder notarget; aisles.verdict eines von pass, fail, noplan, noscale, noaisles oder none. distance_source sagt, ob die Fahrstrecke eingetippt oder aus dem Plan abgeleitet wurde, wie es die Simulationsseite tut.

#Betriebsdaten senden

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": [] } }

#Fehler

401 unauthorised: Kein Schlüssel, oder einer, den wir nicht kennen.
401 revoked: Der Schlüssel wurde zurückgezogen; die Meldung sagt wann.
403 plan: Die Organisation ist auf Kostenlos oder Studio.
403 scope: Dem Schlüssel fehlt der Bereich, den der Endpunkt braucht.
404 not_found: Keine solche Studie, Maschine oder kein solcher Endpunkt.
400 json / empty: Der Body war kein JSON-Objekt oder hatte keine Zeilen.
413 too_many: Mehr als 5 000 Zeilen in einer Telemetrieanfrage.
429 rate_limited: Über 300 Anfragen in einer Minute. Warten Sie Retry-After Sekunden.

#Versionierung

Der Pfad trägt die Version. Felder werden v1 im Laufe der Zeit hinzugefügt, aber nie umbenannt oder entfernt; alles, was einen Client brechen würde, wird zu v2, wobei v1 mindestens ein Jahr lang parallel weiterläuft. Änderungen stehen wie alles andere im Changelog.

Die API liest und schreibt die Organisation, zu der der Schlüssel gehört, und sonst nichts — es gibt keine Möglichkeit, mit irgendeinem Schlüssel die Studien einer anderen Organisation zu erreichen. Behandeln Sie einen Schlüssel wie ein Passwort: einer je System, zurückgezogen, wenn dieses System stillgelegt wird.