Skip to content

2 · uGo-Server — unsere eigene Schnittstelle unter /api/**

Gilt für uGo 1.0.16 (06.10.2026). Port 5301, siehe Porttabelle § 5.1.

Für IT, Techniker und Integrationspartner

Technische Referenz für IT-Abteilungen, URG-Techniker und geschulte Partner. Keine Bedienungsanleitung für Endanwender.

Note

Der Bauplan in einem Satz: Der Browser auf dem Tablett spricht ausschließlich mit dem eigenen Server, dieser spricht mit dem Fahrgestell. Drei Gründe, alle drei tragend:

  1. Das Fahrgestell setzt keine CORS-Kopfzeilen. Ein unmittelbarer Zugriff aus dem Browser scheitert.
  2. Die Geräteadresse steht damit an genau einer Stelle in der Betriebsumgebung (CHASSIS_BASIS) und nicht im ausgelieferten Javascript. Beim Kunden stehen mehrere Geräte, jedes mit eigener Adresse.
  3. Kein Zugriff nach draußen: die Oberfläche kennt nur den eigenen Server.

Alle Antworten sind application/json mit cache-control: no-store, außer wo unten etwas anderes steht.

2.1 Anmeldemodell

Punkt Wie es ist Warum
Träger Sitzungskeks, httpOnly, sameSite: strict, Keks-Laufzeit 8 Stunden; die Sitzung selbst gilt bis 10 Minuten nach der letzten Handlung httpOnly: ein eingeschleustes Skript in der Oberfläche kommt nicht an den Keks heran
secure ausdrücklich false SvelteKit setzt secure von sich aus auf true, außer bei localhost. Am Tablett über HTTP warf die Webansicht den Keks stillschweigend weg: die Anmeldung meldete 200, angemeldet war niemand. Der Roboter spricht im eigenen Netz HTTP; der Schutz kommt aus dem Netz, nicht aus dem Keks
Rolle ergibt sich aus dem Kennwort —
Bremse 5 Fehlversuche je Absender, danach 60 Sekunden Sperre → 429 Ein vierstelliges Kennwort ist in Sekunden geraten, wenn man beliebig oft raten darf
Automaten Dienstschlüssel in der Kopfzeile x-urg-dienstschluessel, auf der Technikerseite erzeugt; gilt als Bedienersitzung: Anstoßen ja, Anlegen und Ändern nein (403) Ein Standortrechner oder ein Fremdsystem kann kein Kennwort eintippen
Kein Servicekennwort eingerichtet (Werkszustand) vom Gerät bleiben die Bedienwege offen; aus dem Netz sind nur Einrichtung und Anmeldung erreichbar, jede andere Schnittstelle antwortet 401. POST /api/anmeldung antwortet 409 Ein frisch aufgesetztes Gerät soll am Gerät bedienbar sein, aber nicht aus dem Netz

Anfragen aus fremden Browserseiten. Ab der uGo-Fassung mit CR-036 (Web-Services für den Bediener) beantwortet der uGo-Server jede Anfrage an /api/**, die eine fremde Seite im Browser stellt, mit 403 und {"fehler": "Anfragen aus einer fremden Seite sind gesperrt.", "schluessel": "api.fremde-herkunft"} — vor dem Türsteher und vor jedem Endpunkt, mit Sitzung oder Dienstschlüssel genauso wie ohne. Erkannt wird das an den Kopfzeilen, die der Browser selbst setzt: Sec-Fetch-Site: cross-site oder same-site, oder Origin: null (eingebettete Seite ohne eigenen Ursprung). Die uGo-Oberfläche selbst (same-origin) und eine von Hand eingegebene Adresse (none) sind nicht betroffen, ebenso wenig Automaten, die keine dieser Kopfzeilen schicken (Ruftaster, Standortrechner, Fremdsysteme mit Dienstschlüssel). Ein Fremdsystem ruft die Schnittstelle deshalb von seinem Server aus auf, nicht aus Javascript in einer Browser-Anwendung.

Zwei Prüfungen hintereinander. Seit dem Zugriffsschutz verlangt der Türsteher aus dem Netz für jede Route eine Sitzung (Bediener oder Techniker) oder den Dienstschlüssel — ausgenommen nur /api/anmeldung, /api/kennwort, /api/leben und /api/hochlauf. Dahinter prüft jede Route ihr Recht selbst (Spalte „Recht im Endpunkt“ unten); vom Gerät gilt nur diese zweite Prüfung. Einzelheiten zu Herkunft, Sitzungen, Dienstschlüssel und Bremse: Zugriffsschutz.

2.2 Alle Routen

Die letzte Spalte nennt das Recht, das die Route selbst prüft. Aus dem Netz kommt die Sitzungspflicht des Türstehers davor (2.1). „ja“ heißt: Techniker.

Route Verf. Zweck / Rumpf Antwort Recht im Endpunkt
/api/anmeldung GET Anmeldezustand {kennwortEingerichtet, angemeldet, rolle} — nie Kennwort oder Kennung nein
POST {kennwort} 200 {rolle} · 401 falsch · 409 kein Kennwort eingerichtet · 429 gesperrt nein
DELETE abmelden {abgemeldet: true} nein
/api/auftraege POST Einzelauftrag eines Fremdsystems anlegen, Rumpf siehe 2.5.3 200 {neu, …Auftrag} · 400/409/503 mit schluessel Sitzung oder Dienstschlüssel
/api/auftraege/<kennung> GET Stand eines Einzelauftrags (2.5.4) 200 Auftrag · 404 unbekannt Sitzung oder Dienstschlüssel
DELETE wartenden Einzelauftrag zurücknehmen 200 Auftrag (abgebrochen) · 404 · 409 läuft schon / abgeschlossen Sitzung oder Dienstschlüssel
/api/chassis/<pfad> GET Durchleitung zum Fahrgestell, Pfad und Suchteil unverändert Antwort des Gerätes, durchgereicht nein
POST Durchleitung, Rumpf unverändert dito nein
PATCH Durchleitung, Rumpf unverändert dito nein
DELETE eng begrenzt: nur maps/<Zahl> und mappings/<Zahl> 403 bei jedem anderen Pfad ja
/api/einstellungen GET Einstellungen lesen Objekt nein — die Oberfläche muss wissen, wann sie ins Ruhebild geht
POST Teilmenge setzen. Anerkannt: ruhebildSekunden, zweitanzeige, medien, medienTon, medienLautstaerke, zweitanzeigeAdresse, fahrstuhlumgang, anstellart, uiotAdresse, ab CR-036 webdienste (2.6), ab uGo 1.0.30 rueckkehrZeitAn, rueckkehrMinuten, rueckkehrAkkuAn, rueckkehrAkkuProzent (2.7); ab der nächsten Fassung (in Vorbereitung): gesicht (2.8) der gespeicherte Stand · 400 mit schluessel bei ungültiger webdienste-Liste oder ungültigem Wert der Rückkehr zur Ladestation, dann wird nichts gespeichert; 400 bei unbekanntem Wert von gesicht (2.8) ja
/api/fahrtenbuch GET Auswertung, bewusst alle Tage auf einmal 365 Zeilen mit drei Zahlen sind wenige Kilobyte; die Anzeige rechnet jeden Zeitraum ohne erneute Frage, und es gibt keine Datumsangaben in der Adresse, die man falsch verstehen kann nein
/api/funk GET Dauerverbindung zum Fahrgestell, als SSE weitergereicht text/event-stream. Ereignisse: lage ({verbunden, grund?}) und meldung (Rohtext des Gerätes). Herzschlag alle 15 s. 501, wenn der Server keinen WebSocket kann nein
/api/karte-aus-aufnahme POST {aufnahmeId, name} — aus einer fertigen Kartenfahrt eine Karte machen 200 {karte} · 409 mit Klartextgrund ja
/api/kartenarchiv GET Abgleich Gerät ↔ Archiv Stand · 502 wenn das Gerät nicht antwortet ja
POST {aktion} ∈ sichern (karteId), alleSichern, zurueckspielen (archivId, zweitname), entfernen (archivId) 200 je Aktion · 400 unbekannte Aktion · 409 mit Klartextgrund ja
/api/medien GET Liste {medien:[{datei, art, bytes}]} nein
POST mehrteiliges Formular, Feld datei 200 · 413 über 200 MB · 415 keine anzeigbare Art ja
/api/medien/<datei> GET Datei ausliefern, mit Bereichsanfragen 200 / 206 / 416 · cache-control: public, max-age=3600 nein
/api/protokolle GET alle Betriebsdaten in einem Zip application/zip. Enthalten: Serverprotokoll (aktuell + vorher), Fahrtenbuch, Einstellungen, Touren, Regeln, /device/info, /chassis/current-map, /mappings/. Nicht enthalten: Kennwörter, Sitzungsmarken, Mediendateien ja
/api/protokolle/zeilen?anzahl=N GET letzte Protokollzeilen aus dem Ringspeicher, N zwischen 5 und 500, Vorgabe 80 {zeilen:[…]} ja — im Protokoll stehen Geräteadressen und Fehlertexte
/api/punkte GET Punkte der aktiven Karte für Fremdsysteme (2.5.2) 200 {karteId, punkte} · 503 Karte nicht lesbar Sitzung oder Dienstschlüssel
/api/punkte/extern GET externe Kennungen (Regalplatz/Lagerplatz/Fach) mit Stand gegenüber der aktiven Karte (2.5.1) 200 {karteId, eintraege} ja
PUT {punktId, extern} — setzen, ändern, mit leerem extern entfernen 200 {karteId, eintrag} · 400 mit schluessel · 503 ja
/api/regeln GET Regeln und Warteschlange {regeln, planer} nein — der Bedienbildschirm zeigt an, was ansteht; das ist Auskunft
PUT {regeln} {regeln, planer} ja — eine Regel legt fest, wann der Roboter von allein losfährt
/api/regeln/aktion POST {aktion} ∈ ausloesen (regelId), taster (kennung), alarm (an, grund), weiter, entfernen (auftragId), alles-anhalten {text, planer} · 400 unbekannte Anweisung · 409 mit Grund nein, bewusst (aus dem Netz: Sitzung oder Dienstschlüssel, hier auch als ?schluessel=) — siehe unten
/api/sprache POST Einstellungen der Sprachbedienung an die Kiosk-Hülle durchreichen: {kennwort, wakePhrases?, sttChunkEndpoint?, wakeConfidence?, robotId?, enabled?}; nur die genannten Felder gehen weiter, enabled nur als echter Wahrheitswert (Entwicklungsstand 23.10.2026) Antwort der Hülle · 400 · 401 · 409 keine Adresse · 502 keine Antwort ja
/api/sprachziele GET Schlüsselwörter je Ziel und Sprache (Entwicklungsstand 23.10.2026) {fassung: 1, eintraege: [{kartenId, punktId, sprache, worte}]} nein — die Bedienoberfläche gleicht das Gehörte damit ab
PUT {kartenId, sprache, eintraege: [{punktId, worte}], weckworte?} ersetzt die Wörter einer Karte in einer Sprache 200 der gespeicherte Stand · 400 mit Schlüssel api.sprachziele-* (leer, doppelt, Weckwort, Sprache, zu lang, zu viele, ungültig) · 500 nicht abgelegt ja — ein Schlüsselwort öffnet nur eine Rückfrage am Bildschirm, gefahren wird erst nach „Ja“
/api/persona GET Persona des Sprachassistenten nach URG-Standard (Entwicklungsstand 23.10.2026) Techniker: das ganze Dokument; sonst nur {name} · 404 api.persona-keine nein — der Name erscheint an der Sprachwolke und in der Rückfrage
PUT Persona nach Schema 1.0, product: "ugo-mobility"; revision und updatedAt setzt das Gerät 200 {persona, uebertragung, schluessel?} · 400 api.persona-ungueltig (werte.feld), api.persona-fassung, api.persona-produkt · 500 api.persona-ablage ja (403 auch mit Dienstschlüssel) — Speichern startet keine Fahrt und schaltet die Sprachbedienung nicht
/api/persona/uebertragen POST gespeicherte Persona erneut als Systemkontext an den Sprachdienst geben 200 {uebertragung, schluessel?} · 404 api.persona-keine ja
/api/touren GET Touren lesen {touren} nein
PUT {touren} {touren} ja
/api/touren/lauf GET Stand des Laufs Laufzustand + planer; die Laufmeldung steht als meldung (deutscher Text, für Protokoll und ältere Oberflächen) und als meldungTeile (Liste von {schluessel, werte?} der Textablage, CR-034); ab uGo 1.0.30 zusätzlich rueckkehr und, während an einem Tour-Halt die Rückkehr-Uhr läuft, rueckkehrSekunden (2.7) nein
POST {aktion} ∈ start (tourId), stop, pause, fortsetzen, bestaetigen, ab uGo 1.0.30 hier-bleiben (2.7) Laufzustand + planer; bei hier-bleiben zusätzlich rueckkehr und hierGeblieben · 409 mit Grund nein, bewusst (aus dem Netz: Sitzung oder Dienstschlüssel) — siehe unten
/api/tuersperre/einschaetzung GET ab uGo 1.0.29 (in Abnahme): Einschätzung, ob eine Einzelfahrt des Browsers nach einem Abbruch an einer Tür mit u-IoT-Brücke neu abgesetzt wird — dieselbe Regel wie bei Touren (Türen über die u-IoT-Brücke). Abfrage: neustarts (bisherige automatische Neustarts dieser Fahrt), fahrt (Kennung der abgebrochenen Fahrt); beim Warten zusätzlich der zuletzt erhaltene Wartezustand seit, frei, wenn vorhanden ohne. Läuft ein Tourenlauf oder meldet das Fahrgestell eine andere laufende Fahrt als fahrt, lautet die Antwort immer pause mit anderer-auftrag. Der Server liest dafür die Brücke (Einstellung „Adresse der u-IoT-Brücke“), den Zustand des Fahrgestells (Not-Halt, Laden) und die Türpunkte der aktiven Karte; die Türpunkte merkt sich der Endpunkt je Karte und Fassung der Überlagerungen höchstens 60 s (der Tourenlauf liest sie weiter frisch). Nur lesend: setzt keinen Fahrbefehl ab immer 200: {einschaetzung: "neu-absetzen", wartezeitMs} · {einschaetzung: "warten", stand: {seit, frei, ohne?}} · {einschaetzung: "pause", grund, wartezeitMs?} mit grund ∈ keine-tuersperre (Abbruch nicht durch die Brücke), anderer-auftrag (Tourenlauf aktiv oder andere Fahrt am Fahrgestell), nothalt, nothalt-unbekannt, neustarts (5 Neustarts), zeit (60 s ohne Freigabe). Der Browser liest zusätzlich unmittelbar vor dem erneuten Absetzen /chassis/status; nicht lesbar gilt als belegt (Pause). Ohne Adresse und ohne Gerätekennung in der Antwort; cache-control: no-store nein (aus dem Netz: Sitzung oder Dienstschlüssel)
/api/uiotfreigabe GET u-IoT-Adressen, die die Technikerseite der Kiosk-Hülle für den Rahmen der Moduloberfläche übergibt: gespeicherte uiotAdresse und Adressen der Module aus den Gebäudeeinstellungen, je als Ursprung, ohne Doppel, höchstens 64 (Entwicklungsstand 23.10.2026, siehe Voice and Language Models 4.1) 200 {adressen} ja (403 auch mit Dienstschlüssel)
/api/webdienstfreigabe GET Ursprünge der gespeicherten, aktiven http-Web-Services (nur private Adressen als Zahl), aus denen die Web-Service-Ansicht den Ursprung des geöffneten Web-Service an die Kiosk-Hülle übergibt; ohne Adressen des Roboters und seiner Module (Fahrgestell, u-IoT, Gebäudemodule, Basis, Sprachdienste, uGo-Rechner; Namen werden aufgelöst und nach Adresse verglichen), ohne Doppel, höchstens 64 (Entwicklungsstand 23.10.2026, Nachbesserung 24.10.2026, kommt mit dem Web-Service-Paket CR-036; siehe Voice and Language Models 4.1) 200 {adressen} nein (lesend wie /api/einstellungen)
/api/uiot/<pfad> GET nur lesende Durchleitung zum u-IoT-Modul; Ziel aus einstellungen.uiotAdresse Antwort des Moduls im Rohtext · 403 gesperrter Pfad · 409 keine/ungültige Adresse · 502 keine Antwort ja
/api/webdienste/rahmen GET ab CR-036: Hüllendokument, in das die Web-Service-Ansicht der Oberfläche einen freigegebenen Web-Service einbettet (2.6) text/html mit Content-Security-Policy · cache-control: no-store nein (vom Gerät lesend offen; aus dem Netz Sitzung wie jede Route)
/api/zonen GET ?karte=<id> — Zonen einer Karte {karteId, kartenname, fassung, zonen} · 502 wenn das Gerät nicht antwortet ja
POST {aktion: "anlegen", karteId, name, ecken} oder {aktion: "entfernen", karteId, kennung} {zone} mit kennung, ecken, zonenNachher, fassungVorher, fassungNachher ja
/api/wolke HINWEIS GET Stand der Cloud-Anbindung {wolke, identitaet} — Verbindung, Puffer, Sperre, letzte Fassungsfreigabe, Umgebung, Thing-Name, Kunde ja
POST {aktion: "anmelden", beitrittscode} 200 {angemeldet, thingName, kunde, seriennummer} · 409 mit Grund ja

Angelegt wird über /api/zonen ausschließlich die Langsamzone (regionType 2). Sperrzonen bietet dieser Endpunkt bewusst nicht an, weil ihre Kennzahl nicht belegt ist (siehe 1.8). Ein doppelter Zonenname in derselben Karte wird abgewiesen — technisch wäre er zulässig, aber der Techniker unterscheidet zwei Zonen „Treppenhaus" hinterher nur noch an 24 Hexzeichen und entfernt dann die falsche.

Warning

Warum zwei Routen am Gerät bewusst OHNE Kennwort arbeiten.

/api/touren/lauf: Das Anlegen einer Tour ist Technikerarbeit und verlangt ein Kennwort. Das Starten und vor allem das Anhalten ist Bedienung. Wer neben einem fahrenden Roboter steht und ihn stoppen will, hat kein Kennwort dabei und soll auch keins brauchen. Ein Halteknopf, der erst eine Anmeldung verlangt, ist kein Halteknopf. stop leert deshalb auch die Warteschlange: wer hält, will einen stehenden Roboter, nicht einen, der gleich mit dem nächsten Auftrag weitermacht. Aus dem Netz verlangt der Türsteher auch hier eine Sitzung oder den Dienstschlüssel.

/api/regeln/aktion: Hier kommen die Anstöße aus der Umgebung an — ein Ruftaster an der Wand, der Alarmkontakt des Hauses, der Standortrechner. Aus dem Netz gilt seit dem Zugriffsschutz: ohne Sitzung oder Dienstschlüssel antwortet die Route 401. Ein Automat weist sich mit dem Dienstschlüssel in der Kopfzeile x-urg-dienstschluessel aus. Weil ein Ruftaster- oder u-IoT-Modul in aller Regel keine Kopfzeile setzen kann, nimmt genau diese Route den Schlüssel zusätzlich als Abfrageparameter an (POST /api/regeln/aktion?schluessel=…) — keine andere. Der Schlüssel gilt als Bediener: Anstoßen ja, Regeln anlegen nein (403). Das Anlegen von Regeln verlangt weiterhin die Technikeranmeldung — dort entscheidet sich, was ein Tasterdruck überhaupt bewirken darf.

2.3 Die Durchleitung /api/chassis/** im Einzelnen

Verhalten Wert Warum
Fehlerbild 504 Zeitüberschreitung, 502 nicht erreichbar Genau diese beiden Nummern wertet die Oberfläche als Verbindungsverlust — alles andere ist eine Gerätestörung
Zeitgrenzen 5 s im Regelfall, 45 s für mappings und maps sowie schreibend für chassis/pose und chassis/current-map Lesen bleibt schnell, Schreiben darf dauern. GET /chassis/pose wird im Takt abgefragt; bekäme es 45 s, stünde die Oberfläche bei einem hängenden Gerät eine Dreiviertelminute still
Weiterleitungen redirect: 'manual'. Verfolgt wird genau eine: derselbe Ursprung, derselbe Suchteil, nur ein Schrägstrich angehängt Die Schnittstelle des Fahrgestells hat keine Anmeldung. Wer im Netz antwortet, soll unseren Server nicht auf eine fremde Adresse schicken können. Der relative Verweis Djangos wird vorher zu einer vollständigen Adresse aufgelöst — fetch in Node wirft sonst „Failed to parse URL"
Schrägstrich export const trailingSlash = 'ignore', und der Pfad wird aus url.pathname genommen, nicht aus params SvelteKit schneidet den Schrägstrich sonst ab und leitet mit 308 um, bevor die Handhabung läuft. Beim Fahrgestell käme wieder /maps ohne Schrägstrich an — und POST scheitert dann am APPEND_SLASH-Fehler
Kopfzeilen durchgelassen werden nur content-type, content-length, cache-control, etag —
Größe Antworten über 4 MB (CHASSIS_GROESSTANTWORT_BYTES) werden verworfen Ein Gerät, das Megabytes liefert, soll weder das Tablett noch den Server beschäftigen
Fehlermeldung enthält nie die Geräteadresse Sie ist der einzige Wert, den der Server vor dem Browser voraushat; in einer Fehlermeldung stünde sie in jedem Fehlerbericht

2.4 Die Durchleitung /api/uiot/** — drei Riegel

  1. Nur GET. Kein POST, kein PUT, kein DELETE. Was das Modul verändert — Türen öffnen, Aufzüge rufen — kommt erst dazu, wenn die Schnittstelle feststeht und jede Handlung eine Rückfrage bekommt.
  2. Gesperrte Pfade (auch lesend): config, wifi, cmd, reboot, export, password, passwd, secret. Der Grund ist belegt: das Modul bietet ein „Export Config JSON", und darin stehen Kennwörter im Klartext. Ein Leserecht darauf wäre ein Leserecht auf die WLAN-Zugangsdaten des Kunden.
  3. Nur mit Anmeldung.

Die Antwort wird unverändert durchgereicht — hier wird nichts gedeutet. Was das Modul meldet, soll der Techniker im Rohtext sehen; alles andere wäre Ratenwerk, solange die Schnittstellenbeschreibung des Moduls aussteht. Das ist der Platzhalter, der ersetzt wird, sobald diese Beschreibung vorliegt.

Fehlerantworten mit Textschlüssel (CR-034)

Fehlerantworten tragen neben dem deutschen Text fehler einen Schlüssel der Textablage schluessel und, wo nötig, Werte werte für dessen Platzhalter. Die Oberfläche zeigt den Schlüssel in der gewählten Sprache; fehler bleibt unverändert für Protokoll und ältere Oberflächen. Ein Fehler ohne eigenen Schlüssel kommt mit allgemein.fehler-mit-geraetetext und dem Wortlaut in werte.geraetetext.

Mit CR-034 tragen zusätzlich einen eigenen Schlüssel: die Absagen der Aufzug-Probefahrt (server.probefahrt.*), der Ruftaster (server.rufe.*), des Standortrechners (server.standortrechner.*) und des Türdienstes (server.tuer.*), die Absagen beim Zeichnen, Prüfen, Schreiben und Entfernen von Zonen (server.zone.*), die Gründe, aus denen ein Tourlauf endet (server.tour.*, server.laden.*, touren.start.*, Palettenschritte touren.palette.*) sowie der Sperrgrund der Fahrwerte (GET /api/fahrwerte: grundSchluessel).

2.5 Fremdsysteme: Punkte, Regalplätze und Einzelaufträge

Neu mit CR-036

Gilt ab der uGo-Fassung, die CR-036 enthält; die Fassungsnummer wird beim Einspielen eingetragen. Ein Lager-, Labor- oder Leitsystem im Kundennetz kann damit Punkte über seine eigene Kennung (Regalplatz, Lagerplatz, Fach) ansprechen und Einzelaufträge anlegen, abfragen und zurücknehmen. Touren und Regeln anlegen oder ändern bleibt Technikerarbeit — dafür gibt es für Fremdsysteme kein Schreibrecht.

Zugang. Das Fremdsystem schickt den Dienstschlüssel in der Kopfzeile x-urg-dienstschluessel (2.1). Als Abfrageparameter wird er auf diesen Routen nicht angenommen. Ohne Sitzung oder Schlüssel: 401. Fahrgestell- und u-IoT-Schnittstellen haben keine Anmeldung und gehören deshalb in ein geschütztes Netzsegment; ein Fremdsystem spricht nur mit dem uGo-Server. Aufrufe aus Javascript einer Browser-Anwendung beantwortet der uGo-Server mit 403 api.fremde-herkunft (2.1); das Fremdsystem ruft vom eigenen Server aus auf.

Fehlerantworten tragen wie überall fehler (deutscher Satz) und schluessel (Textschlüssel, sechs Sprachen), wo nötig werte.

Beispielaufruf (Adresse und Schlüssel aus der eigenen Umgebung, hier als Umgebungsvariablen):

curl -s -H "x-urg-dienstschluessel: $UGO_DIENSTSCHLUESSEL" "http://$UGO_ADRESSE:5301/api/punkte"

2.5.1 Externe Kennung je Punkt

Der Techniker ordnet einem Punkt der aktiven Karte eine externe Kennung zu (PUT /api/punkte/extern, Technikersitzung).

Regel Wert
Form 1 bis 64 Zeichen; am Anfang ein Buchstabe oder eine Ziffer, danach Buchstaben, Ziffern, Leerzeichen und . _ : / # -; keine Steuerzeichen
Eindeutig je Karte, ohne Unterschied von Groß- und Kleinschreibung und mehrfachen Leerzeichen. Dieselbe Kennung auf einer anderen Karte ist erlaubt
Entfernen extern leer oder null
Ablage an genau einer Stelle im uGo-Server, Bezug Kartennummer + Punktkennung. Koordinaten werden nicht kopiert: gefahren wird immer zum Punkt, wie er beim Start auf der Karte liegt
Kartenwechsel Einträge bleiben gespeichert, sind aber inaktiv und markiert: andere-karte, punkt-fehlt (Punkt gelöscht) oder karte-unlesbar. Nur aktive Einträge lösen ein Auftragsziel auf
PUT /api/punkte/extern
{ "punktId": "<24 Hexzeichen>", "extern": "A-01-03" }

200 { "karteId": 7, "eintrag": { "karteId": 7, "punktId": "<24 Hexzeichen>", "extern": "A-01-03", "punktName": "Platz A", "geaendert": "<ISO-Zeit>" } }

Absagen: 400 api.extern.ungueltig, api.extern.doppelt, api.extern.punkt-unbekannt, api.anfrage-ungueltig · 401/403 ohne Technikerrecht · 503 api.karte-unlesbar.

2.5.2 Punktliste für Fremdsysteme

GET /api/punkte liest die aktive Karte frisch vom Fahrgestell und liefert je Punkt Kennung, Name, Punktart, ob er ein Palettenplatz ist (Punktart der Einstellung „Palettenplatz“, Vorgabe 34) und die externe Kennung — ohne Koordinaten.

200 {
  "karteId": 7,
  "punkte": [
    { "id": "<24 Hexzeichen>", "name": "Platz A", "art": "34", "palettenplatz": true, "extern": "A-01-03" },
    { "id": "<24 Hexzeichen>", "name": "Empfang", "art": "11", "palettenplatz": false, "extern": null }
  ]
}

503 api.karte-unlesbar, wenn keine Karte aktiv ist oder das Fahrgestell nicht antwortet.

2.5.3 Einzelauftrag anlegen

POST /api/auftraege

Feld Pflicht Wert
kennung ja Auftragskennung des Fremdsystems, 1 bis 64 Zeichen aus A–Z a–z 0–9 . _ : -
ziel ja genau eines: { "punktId": "<24 Hexzeichen>" } oder { "extern": "<externe Kennung>" }
palette nein aufnehmen oder ablegen — nur an einem Palettenplatz, Halt und Platz höchstens 0,1 m auseinander, nur bei einem Gerät mit Hubwerk (dieselben Regeln wie beim Speichern einer Tour)
aufBestaetigungWarten nein true: am Ziel warten, bis am Gerät bestätigt wird (oder POST /api/touren/lauf {"aktion":"bestaetigen"}). Ab uGo 1.0.30, mit eingeschalteter Rückkehr zur Ladestation: ohne Bestätigung in der eingestellten Zeit endet der Auftrag dort mit erledigt, und der Roboter fährt zur Ladestation (2.7). erledigt heißt dann nicht „bestätigt“ (2.7, Einzelaufträge)
wartenSekunden nein ganze Zahl 0 bis 3600, Vorgabe 0
prioritaet nein 1 (höchste) bis 5, Vorgabe 3
beiFahrt nein anstellen (Vorgabe), vorziehen oder verwerfen — wie bei einer Regel

Wie der Auftrag läuft. Er reiht sich in dieselbe Warteschlange wie die Regeln ein (Priorität, dann Eingang) und fährt über denselben Fahrweg wie eine Tour mit genau einem Halt — mit allen Sperren und Prüfungen des Tourstarts. Ein gescheiterter Palettenschritt endet wie in einer Tour im Palettenstopp, den nur der Techniker freigibt.

Sofort abgelehnt (409, nichts eingereiht), solange der Roboter einer Person folgt (server.hub.sperre.folgen-laeuft) oder der Fahrweg gesperrt ist: Wiederherstellung eines Speicherpunkts, Palettenstopp (api.auftrag.palettenstopp), Alarm (api.auftrag.alarm), Planer nach Fehlschlägen angehalten (api.auftrag.planer-angehalten), Hublage nach einem Neustart unbekannt (server.hub.sperre.hub-unbekannt), Störung am Fahrgestell — Not-Halt gedrückt oder Rad überlastet (api.auftrag.stoerung) —, sowie bei beiFahrt: "verwerfen" und laufender Fahrt (api.auftrag.verworfen).

Laufende Fahrt heißt jede Fahrt des Fahrgestells, nicht nur eine Tour oder ein anderer Auftrag: auch eine Fahrt, die am Gerät mit „Nur hinfahren“ oder über die Zielseite gestartet wurde. Der uGo-Server fragt dafür das Fahrgestell; kann er den Fahrzustand nicht lesen, gilt das wie eine laufende Fahrt. Bei anstellen und vorziehen wartet der Auftrag dann in der Warteschlange (zustand: "wartet") und startet erst nach dem Ende dieser Fahrt; vorziehen bricht eine solche Fahrt nicht ab. Bei verwerfen: 409 api.auftrag.verworfen.

Weitere Absagen: 400 api.auftrag.kennung-ungueltig, api.auftrag.ziel-fehlt, api.auftrag.feld-ungueltig (mit werte.feld), api.extern.punkt-unbekannt, api.auftrag.extern-unbekannt, api.auftrag.palette · 503 api.karte-unlesbar.

Wiederholen ist sicher. Dieselbe kennung mit demselben Inhalt liefert denselben Auftrag zurück ("neu": false) und reiht nichts ein. Dieselbe kennung mit anderem Inhalt: 409 api.auftrag.kennung-vergeben. Wurde ein Auftrag abgelehnt, ist die Kennung nicht verbraucht.

POST /api/auftraege
{ "kennung": "WMS-4711", "ziel": { "extern": "A-01-03" }, "palette": "aufnehmen", "prioritaet": 2 }

200 {
  "neu": true, "kennung": "WMS-4711", "zustand": "wartet", "platz": 1,
  "ziel": { "punktId": "<24 Hexzeichen>", "name": "Platz A", "extern": "A-01-03" },
  "palette": "aufnehmen", "aufBestaetigungWarten": false, "wartenSekunden": 0,
  "prioritaet": 2, "beiFahrt": "anstellen", "angelegt": "<ISO-Zeit>"
}

2.5.4 Stand abfragen und zurücknehmen

GET /api/auftraege/<kennung> liefert denselben Aufbau wie die Antwort beim Anlegen (ohne neu). Es gibt keine Benachrichtigung an das Fremdsystem; es fragt den Stand ab.

zustand Bedeutung
wartet in der Warteschlange, platz ab 1
faehrt unterwegs (auch während eines Palettenschritts oder einer Pause)
am-ziel am Ziel, die Wartezeit läuft
wartet-auf-bestaetigung am Ziel, wartet auf die Bestätigung
erledigt fertig
abgebrochen zurückgenommen, mit dem Halteknopf angehalten oder aus der Warteschlange entfernt
fehler gescheitert; meldung, schluessel und werte sagen warum

DELETE /api/auftraege/<kennung> nimmt einen wartenden Auftrag zurück (200, Zustand abgebrochen). Läuft er schon: 409 api.auftrag.laeuft-schon — angehalten wird ein laufender Auftrag wie jede Fahrt mit dem Halteknopf oder POST /api/touren/lauf {"aktion":"stop"}; das leert auch die Warteschlange. Abgeschlossen: 409 api.auftrag.abgeschlossen. Unbekannt: 404 api.auftrag.unbekannt.

Lebensdauer. Aufträge liegen wie die Warteschlange nur im Arbeitsspeicher. Nach einem Neustart des uGo-Servers sind sie weg, und die Abfrage antwortet 404 — ein Roboter arbeitet nach einem Neustart keine alten Aufträge ab. Gespeichert werden höchstens 500 Aufträge; die ältesten abgeschlossenen gehen zuerst.

2.6 Web-Services für den Bediener

Neu mit CR-036

Gilt ab der uGo-Fassung, die CR-036 enthält; die Fassungsnummer wird beim Einspielen eingetragen. Bedienung und Pflege beschreibt das Technikerhandbuch „Web services“.

Feld webdienste in den Einstellungen. GET /api/einstellungen liefert die Freigabeliste, POST /api/einstellungen mit dem Feld webdienste ersetzt sie (Technikerrecht, Bediener und Dienstschlüssel: 403). Vorgabe ist eine leere Liste, auch für eine Einstellungsdatei aus einer älteren Fassung.

Feld je Eintrag Wert
id Kennung, vom uGo-Server vergeben (Kleinbuchstaben, Ziffern, -, höchstens 40 Zeichen); eine gültige mitgeschickte Kennung bleibt erhalten
name Anzeigename, Pflicht, wird auf 60 Zeichen gekürzt
adresse Startadresse, Pflicht, nur https://, höchstens 300 Zeichen
aktiv nur true schaltet ein; nur aktive Einträge bietet die Oberfläche dem Bediener an
POST /api/einstellungen
{ "webdienste": [ { "name": "Lagerverwaltung", "adresse": "https://lager.example.test/start", "aktiv": true } ] }

Höchstens 10 Einträge. Eine ungültige Liste wird als Ganzes mit 400 abgelehnt; dann wird nichts aus der Anfrage gespeichert. werte.nr nennt den Eintrag (ab 1), werte.max die Höchstzahl.

schluessel Grund
webdienste.fehler.liste kein Feld (Array) oder ein Eintrag ist kein Objekt
webdienste.fehler.zu-viele mehr als 10 Einträge
webdienste.fehler.name-leer Anzeigename fehlt
webdienste.fehler.adresse-leer Startadresse fehlt
webdienste.fehler.nur-https Adresse beginnt nicht mit https:// (auch http:, javascript:, data:, file:)
webdienste.fehler.adresse-ungueltig Adresse zu lang oder nicht lesbar
webdienste.fehler.zugangsdaten Benutzername oder Kennwort in der Adresse
webdienste.fehler.roboteradresse Adresse des Geräts selbst (Loopback, Link-local) oder des Roboters und seiner Module: Fahrgestell, u-IoT, Basis, Standortrechner, Kiosk-Konfigurationsdienst, uGo-Server

GET /api/webdienste/rahmen liefert ein kleines Hüllendokument (text/html, ohne Skript), in das die Web-Service-Ansicht der Oberfläche den gewählten Web-Service in einem abgeschotteten Rahmen einbettet. Seine Content-Security-Policy wird bei jeder Anfrage aus der aktuellen Liste berechnet: frame-src nennt nur die Ursprünge aktiver Einträge (ohne aktiven Eintrag 'none'); alles andere ist gesperrt (default-src 'none', script-src 'none', img-src 'none', form-action 'none', base-uri 'none'). Dazu Permissions-Policy ohne Kamera, Mikrofon, Standort und Vollbild, Referrer-Policy: no-referrer, cache-control: no-store. Die Route ist für die Oberfläche gedacht, nicht für Fremdsysteme.

Schutz der Schnittstelle. Eine eingebettete Seite erreicht /api/** nicht: solche Anfragen enden mit 403 api.fremde-herkunft (2.1). Das schützt den uGo-Server. Fahrgestell- und u-IoT-Schnittstellen haben keine Anmeldung und bleiben deshalb im geschützten Netzsegment.

2.7 Rückkehr zur Ladestation

Ab uGo 1.0.30 (freigegeben am 03.11.2026)

Gilt ab uGo 1.0.30, freigegeben am 03.11.2026. Bedienung, Auslöser und Sperren beschreibt das Technikerhandbuch — Rückkehr zur Ladestation.

Felder in den Einstellungen. GET /api/einstellungen liefert vier Felder; POST /api/einstellungen setzt sie (Technikerrecht, Bediener und Dienstschlüssel: 403).

Feld Wert Neue Einstellungsdatei Bestehende Datei ohne diese Felder (Update)
rueckkehrZeitAn true / false — Auslöser „Am Ziel ohne Bestätigung“ true false
rueckkehrMinuten ganze Zahl 1 bis 60 10 10
rueckkehrAkkuAn true / false — Auslöser „Bei niedrigem Akku“ true false
rueckkehrAkkuProzent ganze Zahl 5 bis 80 20 20

„Neue Einstellungsdatei“ heißt: Es gibt keine Datei (Neuinstallation, beide Auslöser an). Ist eine Datei vorhanden, aber nicht lesbar, gelten die Werte der rechten Spalte: beide Auslöser aus.

Geprüft wird streng: keine Rundung, kein Text als Zahl (1.5, "10", "zehn" sind ungültig), Schalter nur als echter Wahrheitswert. Ein ungültiger Wert wird als Ganzes mit 400 abgelehnt; dann wird nichts aus der Anfrage gespeichert. Die Antwort trägt fehler (deutscher Satz), schluessel und werte.feld (das abgelehnte Feld).

schluessel Grund
einstellungen.rueckkehr.minuten-ungueltig rueckkehrMinuten keine ganze Zahl von 1 bis 60
einstellungen.rueckkehr.akku-ungueltig rueckkehrAkkuProzent keine ganze Zahl von 5 bis 80
einstellungen.rueckkehr.schalter-ungueltig rueckkehrZeitAn oder rueckkehrAkkuAn nicht true oder false
POST /api/einstellungen
{ "rueckkehrZeitAn": true, "rueckkehrMinuten": 10, "rueckkehrAkkuAn": true, "rueckkehrAkkuProzent": 20 }

400 { "fehler": "Bitte ganze Minuten von 1 bis 60 eingeben.", "schluessel": "einstellungen.rueckkehr.minuten-ungueltig", "werte": { "feld": "rueckkehrMinuten" } }

rueckkehrAkkuProzent ist ein eigener Wert und nicht ladeSchwelleProzent (Schwelle, ab der ein ladender Roboter die Station für einen schwächeren freimacht).

Feld rueckkehr in GET /api/touren/lauf. Die Restzeit kommt vom uGo-Server; die Oberfläche zählt nicht selbst.

Inhalt Bedeutung
{ "art": "halt", "restSekunden": n } an einem Tour-Halt läuft die Uhr; dieselbe Zahl steht im Laufzustand als rueckkehrSekunden
{ "art": "einzelfahrt", "restSekunden": n } nach einer Einzelfahrt der Bedienoberfläche läuft die Uhr
{ "art": "tourende", "restSekunden": n } nach dem Ende einer Tour an einem Halt ohne Bestätigungswarten läuft die Uhr
{ "meldung": { "schluessel": "…" } } (werte nur, wenn vorhanden) der Roboter ist nicht gefahren oder die Rückkehr ist gescheitert: rueckkehr.meldung.last, rueckkehr.meldung.gesperrt oder rueckkehr.meldung.gescheitert; die Meldung bleibt bis zum nächsten Auftrag
{} keine Uhr, keine Meldung

restSekunden ist eine ganze Zahl ab 0 (aufgerundet). Die Oberfläche zeigt sie als Fährt in mm:ss zur Ladestation.

„Hier bleiben“: POST /api/touren/lauf {"aktion": "hier-bleiben"}. Hebt die Rückkehr für diesen Halt oder diese Ankunft auf; der Roboter bleibt stehen, ein Halt auf Bestätigung wartet weiter wie bisher. Wie bestaetigen ein Bedienweg ohne Kennwort (aus dem Netz: Sitzung oder Dienstschlüssel); die Anweisung setzt keinen Fahrbefehl ab. Antwort 200: Laufzustand, planer, rueckkehr (danach ohne restSekunden) und hierGeblieben — true, wenn eine Uhr lief, sonst false (dann geschieht nichts).

POST /api/touren/lauf
{ "aktion": "hier-bleiben" }

200 { "…": "Laufzustand", "planer": { "…": "…" }, "rueckkehr": {}, "hierGeblieben": true }

Einzelaufträge (/api/auftraege). Endet ein Einzelauftrag mit aufBestaetigungWarten: true durch die Rückkehr, meldet GET /api/auftraege/<kennung> zustand: "erledigt" — auch wenn die Rückkehr danach scheitert oder wegen Last oder Sperre nicht fährt. Die Antwort trägt dann keine meldung; dass am Ziel nicht bestätigt wurde, ist am Auftrag nicht zu erkennen. Sichtbar ist es im Fahrtenbuch (Tour „…“: „…“ nach … min nicht bestätigt — zur Ladestation.) und bei einem Scheitern als Störung. Ein Fremdsystem, das die Bestätigung braucht, wertet erledigt deshalb nicht als Bestätigung.

Grenzen. Es gibt keinen Endpunkt, der die Rückkehr auslöst; gefahren wird nur über den vorhandenen Ladefahrtweg mit allen Sperren. Die Uhr liegt nur im Arbeitsspeicher: Nach einem Neustart des uGo-Servers gibt es keine Rückkehr aus einer alten Uhr. „Fertig“ auf der Fahrtseite schickt nichts an den Server und hebt die Rückkehr deshalb nicht auf. Eine gescheiterte Rückkehr wird als Störung erfasst.

2.8 Gesicht: Posen oder Standard

Ab uGo 1.0.37

Gilt ab uGo 1.0.37 (freigegeben am 12.11.2026); fehlt das Feld, gilt "posen". Stand siehe Versionshinweise. Bedienung, Momente, Prüfweg und Rückweg beschreibt das Technikerhandbuch — Gesicht.

Feld in den Einstellungen. GET /api/einstellungen liefert das Feld, auch ohne Technikersitzung: Es steht in der verkürzten Antwort für die Bedienoberfläche, weil der Rahmen daraus das Gesicht wählt (kein Geheimnis, keine Adresse). POST /api/einstellungen setzt es (Technikerrecht, Bediener und Dienstschlüssel: 403).

Feld Wert Fehlt das Feld (Update, ältere Einstellungsdatei)
gesicht "posen" — bisheriges Gesicht aus Bildposen, unverändert · "standard" — Vektorgesicht „Gesicht und Momente“ (uGo-Augen) "posen"

Ein anderer Wert als "posen" oder "standard" wird mit 400 abgelehnt; dann wird nichts aus der Anfrage gespeichert. Die Antwort trägt fehler, schluessel und werte.feld. Die Änderung wirkt sofort auf einer schon geöffneten Bedienoberfläche und nur auf diesem Roboter; das Feld geht weder an die uSuite noch an andere Roboter.

schluessel Grund
einstellungen.gesicht.ungueltig gesicht ist weder "posen" noch "standard"
POST /api/einstellungen
{ "gesicht": "standard" }

400 { "fehler": "Unbekanntes Gesicht.", "schluessel": "einstellungen.gesicht.ungueltig", "werte": { "feld": "gesicht" } }

Momente. Es gibt keinen Endpunkt, der einen Moment auslöst. Die Knöpfe der Technikerseite und die Sprachauslösung wirken nur in der Bedienoberfläche des Roboters; sie senden nichts an das Fahrgestell.

Dateien des Standard-Gesichts. Sie liegen unter /gesicht-standard/ und sind wie /gesicht/ ohne Sitzung erreichbar (Zugriffsschutz); sie enthalten nur öffentliche Gestaltungsdateien. Fehlen sie oder lassen sie sich nicht laden, zeigt die Bedienoberfläche für diesen Aufruf posen und schreibt [uGo] Standard-Gesicht fehlt - es werden die Posen gezeigt (…) ins Protokoll des Tabletts.