Werkspur Docs
Zur Website

Aufträge & Produktionslinie

Offene Aufträge lesen

Die Seite „Aufträge“ zeigt ausschließlich Aufträge mit dem Status open. Wählen Sie einen Eintrag, um seine Produktionslinie zu öffnen. Die Liste und die Detailseite sind reine Leseansichten. In der aktuellen Oberfläche gibt es keinen Editor zum Anlegen, Ändern oder Stornieren eines Auftrags.

Ein Auftrag besteht aus einer eindeutigen Nummer, mindestens einer Position und einer geordneten Folge von Schritten. Jeder Schritt nennt eine benötigte Maschinenfähigkeit. Er verweist damit nicht auf eine einzelne Maschine. Bereits angelegte Lose behalten eine Kopie ihrer Schritte. Eine spätere Auftragsänderung verändert ihren Weg deshalb nicht.

Aufträge über die API anlegen und ändern

Das Anlegen und Ändern ist derzeit nur über die JSON-API möglich. Beide Operationen benötigen mindestens die Rolle planner. Die folgenden Aufrufe setzen die Serveradresse in WERKSPUR und ein gültiges Sitzungstoken in WERKSPUR_TOKEN voraus.

Ein einzelner Auftrag entsteht mit POST /api/orders:

curl -sS -X POST "$WERKSPUR/api/orders" \
  -H "Authorization: Bearer $WERKSPUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "BEISPIEL-1001",
    "item": "Bauteil-A",
    "quantity": 100,
    "due_date": "2026-08-01T12:00:00Z",
    "material_cost_cents": 275,
    "steps": [
      {
        "seq": 1,
        "name": "Sägen",
        "capability": "sawing",
        "setup_s": 300,
        "run_per_unit_s": 10,
        "output": "passthrough"
      },
      {
        "seq": 2,
        "name": "Fräsen",
        "capability": "milling",
        "setup_s": 600,
        "run_per_unit_s": 30,
        "output": "passthrough"
      }
    ]
  }'

Für mehrere Positionen verwenden Sie statt item und quantity ein Feld items. Die Zeilen beginnen bei 1 und müssen ohne Lücke aufeinander folgen:

{
  "number": "BEISPIEL-1002",
  "items": [
    {"line": 1, "item": "Baugruppe-A", "product_id": "PRODUKT-A", "quantity": 40},
    {"line": 2, "item": "Baugruppe-B", "product_id": "PRODUKT-B", "quantity": 20}
  ],
  "steps": [
    {"seq": 1, "name": "Prüfen", "capability": "inspection", "setup_s": 0, "run_per_unit_s": 15}
  ]
}

Mit PUT /api/orders/{id} ersetzen Sie alle veränderlichen Auftragsfelder. Die Auftragsnummer gehört nicht in diesen Body und bleibt unveränderlich:

curl -sS -X PUT "$WERKSPUR/api/orders/$ORDER_ID" \
  -H "Authorization: Bearer $WERKSPUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "item": "Bauteil-A",
    "quantity": 120,
    "due_date": "2026-08-03T12:00:00Z",
    "material_cost_cents": 290,
    "steps": [
      {"seq": 1, "name": "Sägen", "capability": "sawing", "setup_s": 300, "run_per_unit_s": 10},
      {"seq": 2, "name": "Fräsen", "capability": "milling", "setup_s": 600, "run_per_unit_s": 30}
    ]
  }'

Die API prüft dabei:

Ein bereits stornierter Auftrag lässt sich nicht mehr ändern.

Artikel-Routings für den Auftragsimport

Ein anbindendes ERP kennt oft nur Auftragsnummer, Artikel, Menge und Liefertermin, aber keine Werkspur-Arbeitsschritte. Für diesen Fall gibt es Artikel-Routings: eine Vorlage, die einem Artikel eine feste Schrittfolge zuordnet. Ein Admin legt eine Vorlage unter Administration → Artikel-Routings an oder ändert eine bestehende dort.

Sendet der Aufruf an POST /api/orders keine steps, sucht der Server die Vorlage zum Artikel der einzigen Position und übernimmt deren Schritte als Kopie in den neuen Auftrag. Enthält der Aufruf eigene steps, gewinnen immer diese, unabhängig davon, ob eine Vorlage existiert:

curl -sS -X POST "$WERKSPUR/api/orders" \
  -H "Authorization: Bearer $WERKSPUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "BEISPIEL-1003",
    "item": "Kugelbolzen K7",
    "quantity": 500,
    "due_date": "2026-08-05T12:00:00Z"
  }'

Für diesen vierfeldigen Aufruf braucht der Artikel eine passende Vorlage. Fehlt sie, antwortet der Server mit 422 und dem Fehlercode orders.no_routing_for_article:

{
  "error": "orders: no routing template for article \"Kugelbolzen K7\"",
  "code": "orders.no_routing_for_article",
  "params": {"article": "Kugelbolzen K7"}
}

Legen Sie in diesem Fall die fehlende Vorlage an, oder schicken Sie steps gleich mit dem Auftrag mit.

Ein Auftrag mit mehreren Positionen (items) hat keinen einzelnen Artikel, an dem eine Vorlage ansetzen könnte. Ohne eigene steps antwortet der Server hier mit 422 und dem Fehlercode orders.routing_multi_item. Solche Aufträge müssen ihre Schritte immer selbst mitschicken.

Schickt ein Client denselben gültigen Auftrag zweimal, antwortet der Server beim zweiten Versuch mit 409. Der Auftrag entsteht dabei nicht doppelt. Eine Wiederholung nach einem Verbindungsabbruch ist deshalb gefahrlos.

Der CSV-Import nutzt dieselbe Ableitung für Zeilen ohne Schrittspalten (siehe unten).

Aufträge als CSV importieren

Auch der CSV-Import ist derzeit nur über die API möglich. Senden Sie die Datei als Body des HTTP-Requests an POST /api/orders/import. Die Rolle planner reicht aus.

Jede Datenzeile beschreibt einen Auftragsschritt. Zeilen mit derselben Auftragsnummer bilden gemeinsam einen Auftrag. Der Header ist nicht an eine feste Reihenfolge gebunden. Diese Spalten sind Pflicht:

number, item, quantity

Die Spalten step_seq, step_name und capability gehören zusammen: Setzen Sie in einer Zeile entweder alle drei, oder lassen Sie alle drei leer. Eine Zeile ohne diese drei Spalten trägt keinen eigenen Schritt bei. Für eine Auftragsgruppe, deren Zeilen durchgehend so schrittlos bleiben, leitet der Server die Schritte stattdessen aus dem Artikel-Routing ab, genau wie beim vierfeldigen Aufruf über die JSON-API. Eine Gruppe, die Zeilen mit und ohne diese drei Spalten mischt, wird nicht angelegt; der Import meldet sie einzeln in errors.

Diese Spalten sind zusätzlich optional:

due_date, output, setup_s, run_per_unit_s, batchable, batch_min, batch_max, tooling, skill

Ein vollständiges Beispiel:

number,item,quantity,due_date,step_seq,step_name,capability,output,setup_s,run_per_unit_s,batchable,batch_min,batch_max,tooling,skill
BEISPIEL-2001,Teil-X,80,2026-08-10,1,Sägen,sawing,passthrough,300,10,false,,,,
BEISPIEL-2001,Teil-X,80,2026-08-10,2,Fräsen,milling,passthrough,600,30,false,,,fraeser-8mm;schraubstock,cnc
BEISPIEL-2002,Teil-Y,40,,1,Härten,hardening,passthrough,0,20,true,5,40,,

Eine schrittlose Zeile lässt die drei Spalten einfach leer:

number,item,quantity,due_date,step_seq,step_name,capability
BEISPIEL-2003,Kugelbolzen K7,500,2026-08-12,,,

curl -sS -X POST "$WERKSPUR/api/orders/import" \
  -H "Authorization: Bearer $WERKSPUR_TOKEN" \
  -H 'Content-Type: text/csv' \
  --data-binary @orders.csv

due_date akzeptiert ein Datum im Format YYYY-MM-DD oder einen RFC-3339-Zeitstempel. batchable akzeptiert leer, false, 0 oder no sowie true, 1 oder yes. Mehrere Werkzeuge in tooling trennen Sie mit einem Semikolon.

Die CSV-Form unterstützt genau eine Auftragsposition über item und quantity. Mehrere Positionen legen Sie über die JSON-API an. Fehler im Header, in einer Zahl, in einem Datum oder in einem booleschen Wert brechen die gesamte Anfrage mit Status 400 ab. Nach erfolgreichem Parsen legt der Server jeden Auftrag unabhängig an. Die Antwort enthält die Listen created und errors. Dadurch kann ein Auftrag erfolgreich sein, während ein anderer etwa wegen einer bereits vergebenen Nummer oder einer falschen Schrittfolge abgelehnt wird.

Aufträge stornieren und Lose anlegen

In der Oberfläche gibt es weder eine Schaltfläche zum Stornieren noch eine Schaltfläche zum Anlegen eines Loses. Beide Vorgänge sind derzeit nur über die API möglich.

Ein Planer storniert einen Auftrag mit DELETE /api/orders/{id}. Der optionale Body kann einen Grund enthalten:

curl -sS -X DELETE "$WERKSPUR/api/orders/$ORDER_ID" \
  -H "Authorization: Bearer $WERKSPUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Planung zurückgezogen"}'

Der Auftrag wechselt von open zu cancelled und verschwindet aus „Aufträge“. Ein zweiter Storno ist ohne zusätzliche Änderung erfolgreich. Der Storno beendet bereits vorhandene Lose nicht. Er verhindert jedoch, dass weitere Lose für diesen Auftrag entstehen.

Ein angemeldeter Benutzer ab der Rolle operator legt ein Los für einen offenen Auftrag mit POST /api/orders/{id}/lots an:

curl -sS -X POST "$WERKSPUR/api/orders/$ORDER_ID/lots" \
  -H "Authorization: Bearer $WERKSPUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"quantity":100,"uom":"pcs"}'

Die Menge muss positiv sein. Fehlt uom, verwendet der Server pcs. Die API vergibt die Los-ID. Bei einem Auftrag mit mehreren Positionen verwendet dieser Endpunkt derzeit die erste Position.

Lebenszyklus von Auftrag und Los

flowchart LR
    O["Auftrag: open"] -->|"Los per API anlegen"| Q["Los: queued"]
    O -->|"Auftrag per API stornieren"| C["Auftrag: cancelled"]
    Q -->|"Einscannen"| P["Los: in_process"]
    P -->|"Schritt abschließen, weitere Schritte"| Q
    P -->|"Letzter Schritt oder Gutmenge 0"| D["Los: done"]
    Q -->|"Sperren mit Grund"| B["Los: blocked"]
    P -->|"Sperren mit Grund"| B
    B -->|"Planer gibt frei"| R["Vorheriger Zustand"]
    R --> Q
    R --> P
    Q -->|"Aufteilen"| S["Los: split"]
    Q -->|"Zusammenführen"| M["Los: merged"]
    Q -->|"Umwandeln"| T["Los: transformed"]
    P -->|"Abziehen bis leer"| T

Aufteilen, Zusammenführen und Umwandeln akzeptieren nur Quell-Lose mit queued. Die betroffenen Quell-Lose enden dabei als split, merged oder transformed. Beim schrittweisen Abziehen darf das Quell-Los auch in_process sein, wenn es an derselben Maschine aktiv ist. Erst das vollständige Leeren setzt es auf transformed; nach einer Teilmenge behält es seinen bisherigen Zustand.

done, split, merged und transformed sind Endzustände des jeweiligen Loses. Bei split, merged und transformed läuft das Material in neu erzeugten Losen weiter. blocked ist dagegen eine Quarantäne. Nur Lose mit queued oder in_process lassen sich sperren. Ein Planer gibt sie über POST /api/lots/{id}/unblock frei. Der Server stellt dann den Zustand wieder her, den das Los vor der Sperre hatte.

Die Produktionslinie lesen

Die Detailseite eines Auftrags ordnet die Schritte nach seq. Zu jedem Schritt sehen Sie den Namen, die benötigte Fähigkeit und alle aktiven Maschinen mit genau dieser Fähigkeit. Gibt es keine passende Maschine, erscheint „keine Maschine“. Ist mindestens eine passende Maschine im Zustand down, erscheint „⚠ Maschine ausgefallen“.

Jede Loszeile zeigt den Weg durch die Schritte:

In der Spalte „Status“ stehen eine aus dem Zustand abgeleitete Anzeige, Gutmenge und gegebenenfalls Ausschuss. „Genealogie“ führt zur Herkunft und zu den Nachfolgern des Loses. Wenn noch kein Los zum Auftrag gehört, erscheint „Für diesen Auftrag wurden noch keine Lose gestartet.“

Die Seite verbindet zwei Live-Datenströme, einen für Losereignisse und einen für Maschinenereignisse. Der Wert hinter „Feed:“ ist open, wenn beide Verbindungen offen sind, connecting während des Aufbaus und error, sobald mindestens eine Verbindung fehlschlägt. Nach einem Ereignis oder einer Wiederverbindung lädt die Seite Lose und Maschinen neu.

Blockierte und beendete Lose

Ein Bediener kann am Scan-Terminal ein Los mit queued oder in_process über „Sperrgrund“ und „Sperren“ auf blocked setzen. Der Grund ist Pflicht. Ein gesperrtes Los lässt sich weder einscannen noch abschließen. Die Freigabe ist derzeit nur über die API möglich und benötigt mindestens die Rolle planner:

curl -sS -X POST "$WERKSPUR/api/lots/$LOT_ID/unblock" \
  -H "Authorization: Bearer $WERKSPUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"note":"Prüfung abgeschlossen"}'

Beendete Lose bleiben in der Produktionslinie und in der Genealogie sichtbar. Sie erscheinen aber nicht mehr unter „Warteschlange“ am Scan-Terminal und akzeptieren keinen weiteren Scan.

ZurückDatenmodell WeiterMaschinen & Werkzeuge