API

API jest na moment, gdy narzędzie ofertowe chce przepustowości i zwrotu ze studium bez przepisywania liczb z raportu przez człowieka, albo gdy zarządzający flotą chce wysyłać dzienne dane eksploatacyjne bez arkusza. Jest dostępne w Team i Enterprise, zarówno na auddomate.com, jak i w instalacjach na własnym serwerze. Wszystko, co zwraca, to to, co widzisz w aplikacji: ta sama flota, te same założenia, ta sama arytmetyka.

#Klucze

Właściciele tworzą klucze w Ustawienia → Klucze API. Nazwij każdy od systemu, który będzie go używał, zaznacz, co może robić, i skopiuj klucz, gdy się pojawi — jest pokazywany raz i przechowywany jako skrót. Klucz ma jeden lub więcej zakresów:

read

Studia, wyniki, maszyny i katalog. Każdy klucz to ma.

telemetry

Zapis wierszy telemetrii do studium.

audit

Odczyt dziennika audytu.

Odwołaj klucz z tej samej strony; cokolwiek nadal go używa, dostaje od tej chwili 401. Tworzenie i odwoływanie kluczy samo jest zapisywane w dzienniku audytu. Do dwudziestu aktywnych kluczy na organizację.

#Wywoływanie

Każde żądanie niesie klucz jako token bearer. Adres bazowy to twój adres Auddomate z dopisanym /api/v1.

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

Jeśli coś między tobą a serwerem usuwa nagłówek Authorization, wyślij go zamiast tego jako X-Api-Key: aud_…. Odpowiedzi to JSON o stałym kształcie:

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

Listy stronicują się przez ?page= i ?per_page= (do 200). Czasy są w czasie lokalnym serwera w formacie YYYY-MM-DD HH:MM:SS; długości to milimetry, odległości metry, tempa na godzinę lub na dzień, dokładnie jak w aplikacji. Każdy klucz może wykonać 300 żądań na minutę; powyżej dostajesz 429 z nagłówkiem Retry-After.

#Punkty końcowe

GET /api/v1/me

Organizacja, nazwa i zakresy klucza, edycja i limit żądań. Użyj, by sprawdzić, czy klucz działa.

GET /api/v1/studies

Każde studium: referencja, nazwa, obiekt, klient, status, werdykt przepustowości i zapas bieżącego scenariusza oraz liczba jednostek w jego flocie. Filtruj przez ?status=, ?client= lub ?updated_since=2026-09-01.

GET /api/v1/studies/{ref}

Jedno studium w całości, po referencji (ST-1001) lub id: plan (plik, skala, zasięg, ile regałów, korytarzy, ramp i przeszkód) oraz każdy scenariusz z wierszami floty, założeniami, wynikiem przepustowości wiersz po wierszu, kontrolą korytarzy wobec najbardziej wymagającej maszyny i tym, która to była maszyna.

GET /api/v1/studies/{ref}/telemetry

Dane eksploatacyjne studium, jeden wiersz na maszynę na dzień.

GET /api/v1/studies/{ref}/pdf

Raport jako plik PDF, wygenerowany na serwerze. ?lang= i ?units=imperial wybierają język i jednostki. /versions/{n}/pdf dla zapisanej wersji.

GET /api/v1/studies/{ref}/versions

Zapisane wersje studium, najnowsze najpierw; /versions/{n} zwraca jedną w całości w tym samym kształcie co samo studium, a ?diff=1 dodaje to, co zmieniło się od tego czasu.

POST /api/v1/studies/{ref}/telemetry

Zapis danych eksploatacyjnych. Wymaga zakresu telemetry. Wyślij {"rows": [...]}, do 5 000 wierszy; każdy wiersz wskazuje maszynę przez machine_id lub machine (dokładną nazwę), day oraz dowolne z moves, run_minutes, idle_minutes, distance_km, faults. Wiersz dla maszyny i dnia, które już istnieją, jest zastępowany. Odpowiedź mówi, ile zapisano, i wymienia pierwsze pięćdziesiąt pominiętych wierszy wraz z powodem.

GET /api/v1/machines

Twoja biblioteka maszyn, każdy profil z jego wartościami i, dla modeli z katalogu, kartą katalogową, z której pochodzi. /machines/{id} dla jednego.

GET /api/v1/catalogue

Katalog prawdziwych marek i modeli z ich źródłowymi kartami katalogowymi. Filtruj przez ?vendor= lub ?class=.

GET /api/v1/audit

Dziennik audytu, najnowsze najpierw. Wymaga zakresu audit. Filtruj przez ?group=, ?from=, ?to=, ?q=.

#Jak wygląda studium

{
  "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 to jedno z meets, short, nofleet, nodistance lub notarget; aisles.verdict jedno z pass, fail, noplan, noscale, noaisles lub none. distance_source mówi, czy odległość przejazdu została wpisana, czy wyprowadzona z planu, tak jak na stronie Symulacja.

#Wysyłanie danych eksploatacyjnych

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

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

#Błędy

401 unauthorised

Brak klucza albo klucz, którego nie rozpoznajemy.

401 revoked

Klucz został odwołany; komunikat mówi kiedy.

403 plan

Organizacja jest na planie Darmowym lub Studio.

403 scope

Kluczowi brakuje zakresu, którego wymaga punkt końcowy.

404 not_found

Nie ma takiego studium, maszyny ani punktu końcowego.

400 json / empty

Treść nie była obiektem JSON albo nie miała wierszy.

413 too_many

Ponad 5 000 wierszy w jednym żądaniu telemetrii.

429 rate_limited

Ponad 300 żądań w ciągu minuty. Odczekaj Retry-After sekund.

#Wersjonowanie

Ścieżka niesie wersję. Pola są z czasem dodawane do v1, ale nigdy nie są przemianowywane ani usuwane; wszystko, co zepsułoby klienta, staje się v2, a v1 działa równolegle przez co najmniej rok. Zmiany są wymienione w dzienniku zmian jak wszystko inne.