Integrationen und Datenaustausch

Katalogdaten aus einem anderen System

MetronQ speichert die Preisliste eines Betriebs als eine Konfiguration: die eingekauften Werkstoffe, die Maschinen, die angebotenen Oberflächenbehandlungen und die Parameter, mit denen die Engine rechnet. Diese Konfiguration lässt sich auch außerhalb des Panels lesen und schreiben. Werte, die bereits in einem ERP, einem CRM oder einer Tabelle stehen, müssen daher nicht erneut eingegeben und nicht in zwei Kopien parallel gepflegt werden.

• Werkstoffe - Bezeichnung, EN- und DIN-Nummer, Dichte, Preis je Kilogramm, Zeitspanvolumen beim Schruppen und beim Drehen, Schlichtleistung, Aufmaß, Schnittgeschwindigkeit.
• Maschinen - Bezeichnung, Technologie, Stundensatz, Arbeitsraum, Achsen, Spindelleistung und Höchstdrehzahl, Werkzeugplätze, Mindestlosgröße sowie Hersteller, Modell, Steuerung, Baujahr, Seriennummer und Inventarnummer.
• Oberflächen- und Wärmebehandlungen - Bezeichnung, Art, Kosten je Kilogramm, Kosten je Quadratdezimeter, feste Gebühr je Los, zusätzliche Arbeitstage zur Lieferzeit und ob der Kunde sie sieht.
• Kalkulationsregeln - Marge, Rüst- und Handhabungsminuten, Mindestzykluszeit, Lieferzeiten, Express-Faktor, Versand, Steuersatz sowie die Faktortabellen für Toleranzklasse, Geometrieklasse und Oberflächengüte.

Es gibt zwei Formate. Welches passt, hängt vom System auf der anderen Seite ab:

• Tabelle (CSV), eine Datei je Katalog. Dieses Format erzeugen die meisten ERP-Exporte, und es lässt sich von Hand bearbeiten.
• JSON, ein Dokument mit der gesamten Konfiguration. Dieses Format ist für ein System gedacht, das MetronQ automatisch aktuell hält.

Import und Export im Panel

1. 1Öffnen Sie im Panel den Reiter Kalkulationsregeln.
2. 2Wählen Sie in der linken Leiste „Import und Export“.
3. 3Der Export erzeugt eine Datei im unten beschriebenen Format. Der Import nimmt eine Datei in diesem Format entgegen.

Tabellenformat (CSV)

Eine Datei je Katalog: Werkstoffe, Maschinen, Oberflächen. Die erste Zeile enthält die Spaltennamen. Die Spaltennamen sind in jeder Sprache englische Bezeichner. Das Mapping im anderen System verwendet diese Namen, und MetronQ liest sie beim Import.

• Zeilen werden nur über die Spalte key zugeordnet. Einen Schlüssel, den MetronQ kennt, aktualisiert der Import. Einen unbekannten Schlüssel legt er als neuen Eintrag an.
• Gelesen werden nur die Spalten, die in der Datei stehen. Fehlt eine Spalte, behält das Feld in jeder Zeile seinen Wert.
• Eine leere Zelle lässt den Wert unverändert und leert das Feld nicht. Teilexporte sind daher zulässig, zum Beispiel nur die aktuell geführten Werkstoffe oder nur die Sätze eines Quartals.
• Ein Import löscht keine Einträge. Werkstoffe und Maschinen werden im Panel entfernt.
• Das Dezimalzeichen hängt vom Spaltentrenner ab: Semikolon mit Dezimalkomma (1234,56), Komma mit Dezimalpunkt (1234.56). Der Import liest beide Varianten. Der Export verwendet die Trenner-Einstellung des Kontos.
• Zeichenkodierung: UTF-8 mit oder ohne Byte Order Mark sowie die mitteleuropäische Codepage Windows-1250, die Excel unter Windows schreibt.
• Grenzen je Datei: höchstens 20 000 Zeilen und 2 MB.

Die Werkzeugliste einer Maschine ist nicht in der Tabelle enthalten, weil eine Zeile keine Liste aufnehmen kann. Eine per Tabelle importierte Maschine behält ihre bestehende Werkzeugliste. Ein Import über die Tabelle ändert daher nicht, welche Teile die Maschine fertigen kann.

Gesamte Konfiguration als JSON-Dokument

Der JSON-Export enthält die vollständige Kalkulationskonfiguration in der Form, in der das Panel sie speichert. Der Import nimmt dieses Dokument unverändert entgegen. Das Dokument enthält die drei Kataloge, alle Kalkulationsparameter, die Einstellungen der Prüf-Gates, die Strategien für Maschinen- und Rohteilwahl und die Währung. Das Format ist für ein System gedacht, das eine eigene Kopie der Preisliste führt.

• Zusammenführen (Voreinstellung): übernimmt nur die Werte, die das Dokument angibt. Eine Datei mit drei Werkstoffen und einer Marge ändert drei Werkstoffe und die Marge. Alle Werte, die das Dokument nicht nennt, bleiben unverändert.
• Ersetzen: übernimmt das Dokument vollständig, einschließlich Löschungen. Für den Fall, dass das andere System der führende Datenbestand ist.
• Kataloge werden über die Spalte key zusammengeführt, wie im Tabellenformat. Beide Formate identifizieren einen Werkstoff über denselben Schlüssel.

Vorschau vor dem Import

Jeder Import beginnt mit einem Probelauf. Bevor ein Wert geschrieben wird, zeigt das Panel die Zahl der neuen und der aktualisierten Einträge, die Änderungen Feld für Feld zwischen der aktuellen Preisliste und der Preisliste nach dem Import, jede Zeile, die nicht gelesen werden konnte, und jede Spalte, die MetronQ nicht erkannt hat. Übernommen wird erst mit „Anwenden“.

• Weist die Preisliste eine Zeile zurück, etwa wegen einer fehlenden Dichte oder eines Preises, der keine Zahl ist, wird die gesamte Datei nicht übernommen. Ein Import wird nie teilweise angewendet, weil eine teilweise importierte Preisliste unbemerkt falsche Preise erzeugt.
• Nicht erkannte Spalten werden mit Namen aufgeführt. Damit fallen verschobene Spalten und Tippfehler in der Kopfzeile auf, die sonst ohne Wirkung blieben.
• Wird die Preisliste gespeichert, während die Vorschau offen ist, lehnt MetronQ den Import ab, weil die angezeigten Änderungen nicht mehr stimmen. Führen Sie den Import dann erneut aus.

Jeder angewendete Import wird im Änderungsprotokoll der Einstellungen als Import eingetragen, Feld für Feld. Jede Preisänderung lässt sich so der Datei zuordnen, die sie verursacht hat.

API-Schlüssel

Die Funktionen oben sind auch ohne Panel über die Integrations-API verfügbar. Dafür erstellt der Betrieb einen API-Schlüssel für sein ERP, CRM oder Automatisierungswerkzeug. Der API-Zugang wird mit jedem Betrieb einzeln vereinbart; nennen Sie uns in einer kurzen Nachricht das eingesetzte System. Der Schlüssel gehört dem Betrieb, nicht einer Person. Er bleibt gültig, wenn die Person, die ihn erstellt hat, nicht verfügbar ist.

1. 1Öffnen Sie im Panel Einstellungen und dort den Reiter Integrationen. Diesen Reiter sieht nur der Kontoinhaber.
2. 2Klicken Sie auf „Neuer Schlüssel“. Tragen Sie unter „Wofür er ist“ das System ein, das den Schlüssel erhält, und wählen Sie unter „Was er darf“ die Berechtigungen.
3. 3Kopieren Sie den Schlüssel sofort. Er wird nur einmal angezeigt und von uns nicht gespeichert. Geht er verloren, widerrufen Sie ihn und erstellen Sie einen neuen.

Erste Integration in sechs Schritten

Sechs Aufrufe in der Reihenfolge, in der sie üblicherweise implementiert werden. Alle Aufrufe verwenden denselben Header Authorization: Bearer mit dem Schlüssel. Die Pfade beziehen sich auf die Basisadresse https://app.metronq.com mit dem Präfix /api/v1/integration. Antworten sind JSON; Ausnahmen sind Pfade, die auf .csv enden, das PDF, die hochgeladene Datei und die 3D-Vorschauen.

1. Schlüssel prüfen

GET /whoami erfordert keine Berechtigung. Die Antwort nennt den Betrieb, zu dem der Schlüssel gehört, die Berechtigungen des Schlüssels und seine Limits. Antwortet der Aufruf mit 200, ist der Schlüssel gültig.

curl https://app.metronq.com/api/v1/integration/whoami \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "tenant": { "name": "Musterwerk GmbH", "slug": "musterwerk", "currency": "EUR" },
  "key": {
    "name": "ERP sync",
    "prefix": "a1b2c3d4",
    "scopes": ["config:read", "quotes:read"],
    "expires_at": "2027-09-16T10:12:00+00:00"
  },
  "rate_limit": {
    "requests_per_minute": 120,
    "requests_per_day": 20000,
    "day_resets": "00:00 UTC",
    "requests_total": 1000,
    "requests_total_used": 3,
    "requests_total_remaining": 997
  }
}

2. Katalog lesen

Ein Aufruf je Katalog: materials, machines oder treatments. GET /config liefert das gesamte Preisdokument in einem Aufruf.

curl https://app.metronq.com/api/v1/integration/catalog/materials \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "catalog": "materials",
  "count": 12,
  "items": [
    {
      "key": "alu_6061",
      "name": "Aluminium 6061",
      "kind": "metal",
      "en_number": "EN AW-6061",
      "din_number": "3.3211",
      "density_g_cm3": 2.7,
      "price_per_kg": 6.4,
      "mrr_rough_cm3_min": 50.0,
      "mrr_turning_cm3_min": 60.0,
      "finishing_rate_cm2_min": 90.0,
      "stock_allowance_mm": 3.0,
      "cutting_speed_m_min": 250.0
    }
  ]
}

3. Neue Kalkulationen abrufen

since= liefert die Kalkulationen, deren created_at gleich dem angegebenen Zeitpunkt (ISO 8601) oder später ist. Setzen Sie since auf das neueste created_at, das Ihr System bereits hat; diese Kalkulation kommt dabei erneut zurück. Die API führt keinen Cursor. limit: 1 bis 200. offset: blättert durch weitere Ergebnisse.

curl "https://app.metronq.com/api/v1/integration/quotes?since=2026-09-16T00:00:00Z&limit=50" \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "items": [
    {
      "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
      "number": 1042,
      "ref": "WID-1042",
      "status": "priced",
      "created_at": "2026-09-16T08:41:12+00:00",
      "filename": "bracket.step",
      "material_key": "alu_6061",
      "quantity": 25,
      "unit_price": 41.5,
      "total_price": 1037.5,
      "discount_pct": null,
      "customer_unit_price": 41.5,
      "currency": "EUR",
      "customer_email": "einkauf@example.com",
      "customer_data_visible": true,
      "external_ref": "",
      "source": "widget"
    }
  ],
  "limit": 50,
  "offset": 0
}

4. Messwerte der Analyse lesen

Dieser Aufruf liefert die Geometrie des Teils, nicht den Preis. Ein Aufruf je Kalkulation.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/metrics \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "quote_id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
  "analyzed_at": "2026-09-16T08:41:29+00:00",
  "file_extension": ".step",
  "status": "priced",
  "gate_status": "instant",
  "gate_reasons": [],
  "complexity": 34.2,
  "material_key": "alu_6061",
  "quantity": 25,
  "tolerance_class": "m",
  "surface_finish": "ra_3_2",
  "confirmed_threads": ["M8"],
  "geometry_metrics": {
    "bounding_box": { "x": 120.0, "y": 80.0, "z": 18.0 },
    "volume": 74210.5,
    "surface_area": 31890.2,
    "face_count": 46,
    "holes": [
      { "diameter": 8.2, "depth": 18.0, "through": true, "direction": [0, 0, 1] }
    ],
    "pockets": [
      { "depth": 6.0, "floor_area": 1840.0, "corner_radius": 5.0, "open": false }
    ],
    "min_wall_thickness": 3.1,
    "derived": { "volume_ratio": 0.43, "area_ratio": 1.71 }
  },
  "parts": []
}

5. Eigene Nummer und Auftragsstatus zurückschreiben

Geändert werden nur die Felder, die im Body stehen.

curl -X PATCH https://app.metronq.com/api/v1/integration/orders/ORDER_ID \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ref": "WO-2026-0912", "status": "in_production"}'

{
  "id": "1b7a44c0-9d2e-4e51-8a10-64d1f0a2e777",
  "quote_id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
  "status": "in_production",
  "payment_status": "unpaid",
  "external_ref": "WO-2026-0912",
  "quantity": 25,
  "unit_price": 41.5,
  "total_price": 1062.5,
  "currency": "EUR",
  "customer": { "name": "Anna Muster", "email": "einkauf@example.com", "city": "Musterstadt", "...": "..." },
  "...": "..."
}

6. Preisliste aus dem ERP aktualisieren

Zwei Aufrufe: Vorschau (POST /config/import/preview) und Übernahme (POST /config/import). Die Vorschau schreibt nichts und liefert einen base_hash. Die Übernahme muss diesen base_hash mitsenden.

Berechtigungen (Scopes)

• config:read - Katalog und Kalkulationsregeln lesen.
• config:write - Katalog und Kalkulationsregeln aktualisieren, über denselben Ablauf aus Vorschau und Übernahme wie im Panel.
• quotes:read - Kalkulationen und Aufträge lesen: Teil, Werkstoff, Menge, Preis und Auslesebericht. Kontaktdaten der Kunden sind nicht enthalten; dafür ist zusätzlich customers:read nötig. Ein Schlüssel mit quotes:read sieht jede Kalkulation, die der Betrieb erhalten hat. Vergeben Sie ihn an ein System, das die Aufträge benötigt.
• customers:read - Kontaktdaten des Kunden auf Kalkulationen und Aufträgen lesen. Ergänzt quotes:read und wirkt nur zusammen damit. Ohne customers:read liefert die API dieselben Datensätze, aber customer_email, der gesamte Block customer und die Notiz des Kunden (note) sind null. Lassen Sie customers:read für ein System aus, dem Teil, Menge und Preis genügen. Ein Schlüssel ohne diese Berechtigung kann keine Namen und keine Kundenliste auslesen.
• quotes:write - die eigene Nummer (external_ref) zurückschreiben und den Status eines Auftrags ändern. Kalkulieren oder freigeben kann dieser Schlüssel nicht.
• quotes:create - Teiledateien zur Kalkulation senden und die Parameter jeder Kalkulation des Betriebs ändern, bis über sie entschieden ist. Den Preis berechnet die Engine. Der Schlüssel kann keinen Preis eintragen, nicht freigeben, nicht ablehnen und keinen Rabatt gewähren. Jede gesendete Datei ist eine Kalkulation im Tarif des Betriebs; vergeben Sie diese Berechtigung nur an Systeme, die Dateien senden sollen. quotes:read ist nicht enthalten, damit ein System, das nur Dateien einliefert, nicht jede Kalkulation lesen kann.
• files:read - die hochgeladenen Dateien der Kunden und die 3D-Vorschauen herunterladen und den Zugangscode einer Kalkulation lesen. Ergänzt quotes:read wie customers:read. Die Berechtigung ist getrennt, weil ein Auslesebericht aus Zahlen besteht, aus denen sich das Teil nicht nachbauen lässt, die Datei dagegen die Konstruktion des Kunden ist.

Kein Schlüssel kann einen Schlüssel erstellen, einen Schlüssel widerrufen oder Berechtigungen ändern. Das kann nur der angemeldete Kontoinhaber. Ein gestohlener Schlüssel kann daher seine Gültigkeit nicht verlängern. Ein Schlüssel ist standardmäßig 365 Tage gültig; das Ablaufdatum steht in der Spalte „Gültig bis“. Ein Widerruf wirkt ab der nächsten Anfrage.

Lesbare Daten

Die API liefert alles, was das Panel zum Katalog und zu den Kalkulationen dieses Betriebs zeigt, und keine Daten anderer Betriebe. Jede Abfrage hat einen Endpunkt:

• Werkstoffe - GET /catalog/materials: der gesamte Katalog mit den Bezeichnungen für den Konstrukteur (EN-Nummer und Werkstoffnummer), Dichte, Preis je Kilogramm, Zeitspanvolumina, Schlichtleistung und Schnittgeschwindigkeit.
• Maschinen - GET /catalog/machines: Technologie, Stundensatz, Arbeitsraum, Achsenzahl, Spindelleistung und Höchstdrehzahl, Werkzeugplätze, maximales Werkstückgewicht sowie der Datenblatt-Block (Hersteller, Modell, Steuerung, Baujahr, Inventarnummer).
• Werkzeuge - GET /tools: die Werkzeugbibliothek als flache Liste. Jede Zeile nennt die Maschine, in der das Werkzeug sitzt, und den Eckenradius, den die Engine daraus ableitet.
• Schnittdaten - GET /cutting-data: je Werkstoff die Schnittgeschwindigkeit und die Zeitspanvolumina, aus denen eine Kalkulation gerechnet wird; je Maschine die Spindeldaten, mit denen diese Werte skaliert werden.
• Behandlungen - GET /catalog/treatments: Oberflächen- und Wärmebehandlungen mit Kosten und Durchlaufzeiten.
• Kalkulationen und Aufträge - GET /quotes und GET /orders, neueste zuerst, filterbar mit since=. Eine einzelne Kalkulation enthält die Preisaufschlüsselung, ein Auftrag die Kundendaten für Rechnung und Versand.
• Auslesebericht einer Datei - GET /quotes/{id}/metrics: die Messwerte der Analyse (Abmaße, Gewicht, Bohrungen, Taschen, Gewinde, Flächen und Toleranzen), bei einer Baugruppe je Teil.

Hinweise zu zwei dieser Endpunkte:

• Ein Werkzeug gehört immer zu einer Maschine: Es ist ein Werkzeug, das die Spindel dieser Maschine einsetzen kann. Deshalb nennt jede Zeile von GET /tools ihre Maschine. Die Katalogtabelle (CSV) enthält keine Werkzeuge, weil eine Zeile keine Liste aufnehmen kann.
• GET /cutting-data ist keine Schnittwerttabelle. MetronQ verwendet weder Vorschub je Zahn noch Schnitttiefe, weil das Zeitmodell mit Zeitspanvolumina je Werkstoff rechnet. Der Endpunkt liefert alle Werte hinter einem Preis: die Werte des Betriebs und die zwei, die die Engine daraus ableitet. Ein angebundenes System sieht einen Werkstoff damit mit denselben Werten wie die Engine.

Feldbeschreibungen

Wo eine Einheit nicht eindeutig ist, steht sie im Feldnamen: _mm, _kg, _cm3_min, _m_min. Alle Werte sind JSON-Zahlen oder -Zeichenketten; kein Betrag ist formatiert. Alle Preise stehen in der Währung des Betriebs, die GET /whoami liefert.

Werkstoff (GET /catalog/materials)

• key - Kennung des Werkstoffs. Eine Kalkulation verweist mit material_key darauf. Über diesen Schlüssel identifizieren Ihr System und MetronQ denselben Werkstoff. Ein geänderter Schlüssel ist ein neuer Werkstoff, keine Umbenennung.
• name - die Bezeichnung, wie sie im Katalog gespeichert ist; der Kunde des Betriebs liest sie im Widget und im Angebot. Eine vom Betrieb geschriebene Bezeichnung wird nicht übersetzt. Eine von MetronQ vorgegebene Bezeichnung zeigen Widget und Angebot in der Sprache des Lesers.
• kind - metal oder plastic. Legt fest, welche Toleranzen, Passungen und Oberflächen angeboten werden.
• en_number, din_number - die Normbezeichnungen (EN AW-6061, 1.0503). Für den Konstrukteur; die Engine verwendet sie nicht.
• density_g_cm3 - Dichte in g/cm3. Bestimmt das Teilegewicht und damit die Materialkosten.
• price_per_kg - Einkaufspreis je Kilogramm in der Währung des Betriebs. Das am häufigsten aus einem ERP geschriebene Feld.
• mrr_rough_cm3_min - Zeitspanvolumen beim Schruppen in cm3/min, bezogen auf die Referenzspindel mit 15 kW. Über diesen Wert wird ein Werkstoff, der sich langsamer zerspanen lässt, teurer kalkuliert.
• mrr_turning_cm3_min - Zeitspanvolumen beim Drehen in cm3/min. null: Es gilt das Zeitspanvolumen beim Schruppen.
• finishing_rate_cm2_min - Schlichtleistung: die Fläche, die ein Schlichtgang je Minute bearbeitet, in cm2/min.
• stock_allowance_mm - Aufmaß je Seite bei der Rohteilwahl, in mm.
• cutting_speed_m_min - Schnittgeschwindigkeit vc in m/min. null: Der Wert wird aus dem Zeitspanvolumen beim Schruppen abgeleitet; GET /cutting-data zeigt den verwendeten Wert.

Maschine (GET /catalog/machines)

Felder, die den Preis oder eine Ablehnung bestimmen:

• key, name - Kennung und Bezeichnung der Maschine im Betrieb.
• technology - milling, turning, bar_turning oder mill_turn. Legt fest, welche Teile die Maschine annimmt und welches Zeitspanvolumen gilt.
• hourly_rate - Maschinenstundensatz in der Währung des Betriebs. Die Übernahme eines Modells aus dem Maschinenkatalog schreibt dieses Feld nie; den Stundensatz legt der Betrieb fest.
• envelope_mm - Arbeitsraum. Fräsmaschine: drei Werte (x, y, z). Drehmaschine: erster Wert Drehdurchmesser, zweiter Wert Drehlänge.
• axes - Achsenzahl, beim Fräsen 3 bis 5. Mit mehr als 3 Achsen braucht ein Teil weniger Aufspannungen.
• spindle_power_kw - Spindelleistung. Unter der Referenz von 15 kW werden die Zeitspanvolumina proportional gesenkt, darüber nicht erhöht. Eine angegebene Spindelleistung kann eine Kalkulation daher nur verteuern.
• max_spindle_rpm - Höchstdrehzahl. Wirkt nur bei kleinen Werkzeugen, bei denen die für die Schnittgeschwindigkeit nötige Drehzahl nicht erreicht wird.
• min_tool_radius_mm - der kleinste Innenradius, den die Maschine fertigen kann. Enthält die Werkzeugbibliothek der Maschine ein eckenschneidendes Werkzeug (Schaftfräser auf einer Fräsmaschine, Wendeschneidplatte auf einer Drehmaschine), wird dieses Feld nicht mehr gelesen; dann gilt das kleinste dieser Werkzeuge. Eine Bibliothek nur aus Bohrern und Gewindebohrern ändert nichts.
• tool_stations, max_workpiece_kg, through_spindle_coolant - Magazinplätze, zulässige Tischlast, Innenkühlung durch die Spindel.
• datasheet - maker, model, control, year, serial, inventory_no, notes. Nur zur Identifikation; die Engine liest keinen Wert aus diesem Block.

Werkzeug (GET /tools)

{
  "count": 2,
  "items": [
    {
      "key": "e12",
      "kind": "endmill",
      "name": "12 mm Hartmetall, 4 Schneiden",
      "diameter_mm": 12.0,
      "nose_radius_mm": null,
      "flute_length_mm": 45.0,
      "designation": "",
      "machine_key": "dmu50",
      "machine_name": "DMU 50",
      "cut_radius_mm": 6.0
    }
  ]
}

• machine_key, machine_name - die Maschine, in der das Werkzeug sitzt. Jedes Werkzeug gehört zu einer Maschine.
• kind - drill, endmill, tap, thread_mill, reamer oder turning_insert.
• diameter_mm - Schneiddurchmesser. Bohrer und Reibahle: Durchmesser der erzeugten Bohrung. Schaftfräser: Durchmesser des Fräsers. Gewindebohrer: Gewindenenndurchmesser.
• nose_radius_mm - Eckenradius einer Wendeschneidplatte: die kleinste Rundung, die sie an einer gedrehten Kontur erzeugt.
• flute_length_mm - nutzbare Schneidenlänge in mm. null: keine Grenze angegeben; die Engine setzt dann keine Grenze.
• cut_radius_mm - der kleinste Innenradius, den dieses Werkzeug erzeugt, von MetronQ berechnet: halber Durchmesser oder Eckenradius der Platte. Der kleinste Wert unter den eckenschneidenden Werkzeugen (Schaftfräser auf einer Fräsmaschine, Wendeschneidplatten auf einer Drehmaschine) ist die Eckengrenze der Maschine. Bohrer und Gewindebohrer zählen dabei nicht.

Schnittdaten (GET /cutting-data)

Die von der Engine abgeleiteten Werte stehen neben den Werten des Betriebs:

{
  "reference": { "spindle_power_kw": 15.0, "cutting_speed_m_min": 250.0 },
  "materials": [
    {
      "key": "steel_c45",
      "name": "Stahl C45",
      "kind": "metal",
      "en_number": "1.0503",
      "din_number": "",
      "density_g_cm3": 7.85,
      "cutting_speed_m_min": null,
      "cutting_speed_effective_m_min": 156.2,
      "machinability_factor": 1.6,
      "mrr_rough_cm3_min": 19.5,
      "mrr_turning_cm3_min": null,
      "mrr_turning_effective_cm3_min": 19.5,
      "finishing_rate_cm2_min": 40.0,
      "stock_allowance_mm": 3.0
    }
  ],
  "machines": [
    {
      "key": "dmu50",
      "name": "DMU 50",
      "technology": "milling",
      "spindle_power_kw": 13.0,
      "max_spindle_rpm": 10000.0,
      "spindle_power_factor": 0.867,
      "min_tool_radius_mm": 1.0,
      "tool_radius_effective_mm": 6.0,
      "tool_count": 2
    }
  ]
}

• reference - Referenzspindel und Referenzschnittgeschwindigkeit, auf die die gesamte Preisliste bezogen ist: 15 kW und 250 m/min. Beide Werte werden mitgeliefert, damit sich die Ableitungen unten nachrechnen lassen.
• cutting_speed_effective_m_min - die verwendete Schnittgeschwindigkeit: der Wert des Betriebs, falls eingetragen, sonst reference / machinability_factor.
• machinability_factor - Zerspanbarkeit im Verhältnis zu Aluminium: 1,0 Aluminium, etwa 1,6 ein gewöhnlicher Stahl, etwa 3 ein nichtrostender Stahl. Berechnet als Wurzel aus dem Verhältnis der Aluminium-Basis (50 cm3/min) zu mrr_rough_cm3_min, begrenzt auf 1,0 bis 4,0.
• mrr_turning_effective_cm3_min - das Zeitspanvolumen beim Drehen nach Anwendung der Ersatzregel (bei mrr_turning_cm3_min null gilt das Schruppvolumen).
• spindle_power_factor - Skalierung der Zeitspanvolumina auf dieser Maschine: spindle_power_kw / 15, begrenzt auf höchstens 1,0 und mindestens 0,25.
• tool_radius_effective_mm - der geltende Eckenradius: der eingetragene min_tool_radius_mm oder, sobald eine Werkzeugbibliothek existiert, das kleinste eckenschneidende Werkzeug darin (Schaftfräser auf einer Fräsmaschine, Wendeschneidplatten auf einer Drehmaschine).

Kalkulation und Auftrag (GET /quotes, GET /orders)

• id - Kennung, die alle weiteren Aufrufe verwenden. number ist die fortlaufende Nummer der Kalkulation; ref ist die Referenz, die der Betrieb im Panel sieht, mit einem Präfix nach Herkunft (WID-1042, WYC-1042, API-1043).
• status - Stand der Kalkulation: created, uploaded, analyzing, analyzed, priced, approved, rejected, ordered, analysis_failed. Einen Preis haben Kalkulationen mit priced, approved und ordered.
• unit_price, total_price, currency - Stückpreis und Preis für das Los, in der Währung des Betriebs. Bei einer Kalkulation ohne Preis ist der Wert null.
• discount_pct, customer_unit_price - der Rabatt des Betriebs für diesen Kunden in Prozent und der Stückpreis nach Rabatt. unit_price bleibt der freigegebene Preis. Ein Auftrag enthält bereits den rabattierten Betrag. Ohne Rabatt ist discount_pct null.
• min_order_top_up, delivery_cost - nur beim Auftrag: der Aufschlag bis zum Mindestauftragswert und die Versandkosten. Beide sind in total_price des Auftrags enthalten, wie der Kunde sie im Widget und im Angebots-PDF gesehen hat. Bei Aufträgen, die vor Einführung dieser Felder erteilt wurden, ist beides 0.
• material_key, quantity - Werkstoff und Menge, die der Kunde gewählt hat. material_key verweist auf den Werkstoffkatalog.
• external_ref - Ihre eigene Nummer. Leer, bis Ihr System eine schreibt. Danach finden Sie den Datensatz mit ?external_ref=.
• source - Herkunft der Kalkulation: widget (Website des Betriebs), panel (im Panel hochgeladen) oder api (vom eigenen System des Betriebs gesendet). Leer bei Kalkulationen, die vor Einführung dieses Feldes angelegt wurden.
• customer_email - die einzige Kontaktangabe einer Kalkulation. Weitere Angaben zur Person enthält erst ein Auftrag.
• customer_email, customer, note - null, wenn der Schlüssel customers:read nicht hat. customer_data_visible unterscheidet die beiden Fälle: false bedeutet, dass der Schlüssel die Kontaktdaten nicht lesen darf; bei true bedeutet null, dass keine Angabe hinterlegt ist.
• Zusätzlich beim Auftrag: status (new, confirmed, in_production, shipped, cancelled), payment_status (unpaid, paid) sowie customer mit vollständiger Rechnungs- und Lieferanschrift.
• breakdown - nur bei GET /quotes/{id}: die gespeicherte Kostenaufschlüsselung hinter dem Preis, für die Nachkalkulation im eigenen System.

Auslesebericht einer Datei (GET /quotes/{id}/metrics)

Felder für die Arbeitsvorbereitung:

• geometry_metrics.bounding_box - Abmaße in mm. derived.bbox_sorted_dims enthält dieselben drei Werte sortiert; auf dieser Grundlage wird die Machbarkeit geprüft.
• geometry_metrics.volume, surface_area - Teilevolumen in mm3 und Oberfläche in mm2. derived.volume_ratio ist das Volumen geteilt durch das Volumen des Hüllquaders; ein niedriger Wert bedeutet viel Materialabtrag.
• holes[] - jede gezählte Bohrung: Durchmesser, Tiefe, ob durchgehend, Achse. Kriterium für das Zählen ist ein vollständiger Kreis, nicht die Größe der Bohrung.
• pockets[] - Tiefe, Bodenfläche, Eckenradius und ob die Tasche offen oder durchgehend ist.
• min_wall_thickness - die dünnste gefundene Wand in mm, oder null, wenn keine ausreichend dünne Wand gemessen wurde.
• gate_status, gate_reasons - ob die Kalkulation automatisch möglich war und, falls nicht, der Grund im Format code:machine:field:actual:limit mit der Messung, die zur Ablehnung geführt hat.

Teil zur Kalkulation senden

Das System eines Betriebs kann eine Teiledatei zur Kalkulation senden. Die Datei wird so kalkuliert wie ein Upload eines Kunden im Widget. Unterstützt werden STEP- und IGES-Modelle, DXF-Profile, PDF-Zeichnungen und Fotos von Zeichnungen. Erforderliche Berechtigung: quotes:create. Ablauf: Kalkulation anlegen, Datei hochladen, Upload bestätigen, Ergebnis lesen.

1. Kalkulation anlegen

POST /quotes mit Name und Größe der Datei und den Parametern, mit denen sie kalkuliert werden soll.

• Pflichtfelder: filename, file_size_bytes.
• Optionale Felder: quantity, material_key, tolerance_class, geometric_class, surface_finish, treatments, lead_time, thickness_mm und units_mm (für eine DXF), process, customer_email, locale, external_ref, label. process legt fest, wie ein flaches Teil in einem Betrieb mit einer Blechschneidmaschine gefertigt wird: machining (Fräs- oder Drehmaschine), sheet_cutting oder auto. auto, ebenso eine Anfrage ohne process, ist die Wahl der Engine: Jedes Teil, das eine Blechschneidmaschine des Betriebs schneiden kann, wird als geschnitten kalkuliert. In einem Betrieb ohne Blechschneidmaschine kalkuliert auto wie bisher.
• Ein Feld, das dieser Aufruf nicht kennt, wird mit 422 abgelehnt und nicht ignoriert. Ein Tippfehler führt damit nicht zu einer Kalkulation mit dem Standardwerkstoff.
• Ein unbekannter Werkstoff wird bereits bei diesem Aufruf abgelehnt, nicht erst nach der Analyse.

curl -X POST https://app.metronq.com/api/v1/integration/quotes \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "bracket.step", "file_size_bytes": 482113, "quantity": 25,
       "material_key": "alu_6061", "tolerance_class": "f", "external_ref": "RFQ-2026-0455"}'

{
  "quote": {
    "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
    "number": 1043,
    "ref": "API-1043",
    "status": "created",
    "filename": "bracket.step",
    "quantity": 25,
    "unit_price": null,
    "external_ref": "RFQ-2026-0455",
    "source": "api",
    "...": "..."
  },
  "release": { "state": "waiting", "customer_may_see_price": false },
  "upload": {
    "method": "PUT",
    "url": "https://OBJECT_STORAGE/...",
    "headers": {
      "x-amz-server-side-encryption-customer-algorithm": "AES256",
      "x-amz-server-side-encryption-customer-key": "...",
      "x-amz-server-side-encryption-customer-key-MD5": "..."
    },
    "content_length": 482113,
    "expires_at": "2026-09-25T10:15:00+00:00"
  }
}

2. Datei mit PUT an upload.url hochladen

Die Datei geht direkt in den Objektspeicher, nicht an den Anwendungsserver von MetronQ. Sie wird beim Eintreffen verschlüsselt, mit einem Schlüssel nur für diese Datei.

• Senden Sie jeden Header aus upload.headers unverändert mit, weil die Verschlüsselungs-Header Teil der Signatur sind.
• Content-Length muss der in Schritt 1 angegebenen Größe entsprechen.
• Die Adresse gilt bis expires_at, 15 Minuten.
• Erlaubt Ihr Netz ausgehenden Verkehr nur zu bekannten Hosts, geben Sie den Host des Objektspeichers frei.

curl -X PUT "UPLOAD_URL" \
  -H "x-amz-server-side-encryption-customer-algorithm: AES256" \
  -H "x-amz-server-side-encryption-customer-key: ..." \
  -H "x-amz-server-side-encryption-customer-key-MD5: ..." \
  --data-binary @bracket.step

3. Upload bestätigen

Die Bestätigung reiht die Analyse ein. Direkt nach der Analyse wird das Teil mit den Parametern aus Schritt 1 kalkuliert. Das Kontingent des Tarifs und die Grenze von fünf Dateien in Verarbeitung werden hier erneut geprüft, weil dieser Aufruf die Verarbeitung startet.

• 409 file_not_uploaded - der PUT ist nicht angekommen. Laden Sie die Datei erneut hoch, solange die Adresse gilt.
• 409 upload_expired - die Adresse ist seit mehr als 30 Minuten abgelaufen. Legen Sie die Kalkulation neu an.
• 409 quote_not_awaiting_upload - der Upload wurde bereits bestätigt. Eine zweite Bestätigung hat keine weitere Wirkung.

curl -X POST https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/confirm-upload \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "quote": { "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33", "ref": "API-1043", "status": "uploaded", "...": "..." },
  "release": { "state": "waiting", "customer_may_see_price": false },
  "poll_after_seconds": 10
}

4. Ergebnis abfragen

Fragen Sie etwa alle 10 Sekunden (poll_after_seconds) die kurze Antwort von GET /quotes/{id} ab, bis status weder uploaded noch analyzing ist. Lesen Sie danach die vollständige Kalkulation einmal mit GET /quotes/{id}/detail (unten beschrieben). Zum Lesen ist quotes:read nötig, eine eigene Berechtigung, damit ein System, das nur Dateien einliefert, nicht jede Kalkulation des Betriebs lesen kann.

• Jede Datei ist eine Kalkulation. Sie zählt gegen den Tarif wie eine Kalkulation aus dem Widget oder dem Panel, und das Tageslimit des Betriebs gilt. 403 quoting_blocked:<reason> nennt das erreichte Limit. Abgerechnet wird eine Kalkulation erst, wenn die Engine einen Preis für sie ermittelt hat.
• Höchstens fünf über die API gesendete Dateien eines Betriebs dürfen gleichzeitig in der Analyse sein. Kalkulationen aus dem Widget und dem Panel zählen nicht mit. Die sechste Datei wird mit 429 analysis_backlog und Retry-After: 30 abgelehnt. Eine Kalkulation, deren Upload-Adresse ungenutzt abgelaufen ist, zählt nicht mehr mit.
• Über die API gesendete Dateien werden nach den Dateien analysiert, auf die im Widget oder im Panel gerade jemand wartet. Ein einzelnes Teil dauert meist Sekunden, eine große Baugruppe einige Minuten.
• Die Referenz der Kalkulation beginnt mit API (API-1043). Das Panel nennt den Schlüssel, der sie gesendet hat, damit sie nicht für die Anfrage eines Kunden gehalten wird.
• Hat die Kalkulation eine customer_email, sendet die Freigabe im Panel diesem Kunden den Link per E-Mail, wie bei einer im Panel angelegten Kalkulation. Ohne customer_email erhält niemand außerhalb des Betriebs eine Nachricht von MetronQ.
• Ein POST /quotes, der in ein Timeout gelaufen ist, kann trotzdem eine Kalkulation angelegt haben. Senden Sie external_ref mit und suchen Sie nach einem Timeout mit GET /quotes?external_ref= danach, bevor Sie erneut anlegen. Eine Kalkulation, deren Datei nie ankommt, wird nicht abgerechnet. Eine hochgeladene, aber nicht bestätigte Datei wird nach sechs Stunden gelöscht. Die leere Kalkulation bleibt in der Liste und zählt gegen das Tageslimit des Betriebs.

Grenzen, die die API prüft:

• Datei: höchstens 50 MB.
• quantity: 1 bis 100 000.
• treatments: höchstens 10 Einträge.
• thickness_mm: bis 200; units_mm: bis 1000.
• external_ref: bis 80 Zeichen; label: bis 200 Zeichen.
• filename: bis 255 Zeichen, ohne Steuerzeichen.
• POST /quotes/{id}/drawing-inputs: scale_ratio 0,02 bis 50, thickness_mm 0,2 bis 500 mm.
• upload_expired gilt ab 45 Minuten nach dem Anlegen der Kalkulation: 15 Minuten Gültigkeit der Upload-Adresse und 30 Minuten Kulanz.

Neu kalkulieren

POST /quotes/{id}/reprice (quotes:create) ändert die Parameter einer Kalkulation, und die Engine kalkuliert sie neu. Der Aufruf gilt für jede Kalkulation des Betriebs, gleich auf welchem Weg sie hereinkam.

• 409 quote_closed - die Kalkulation ist freigegeben oder abgelehnt, oder der Kunde hat sie bestellt.
• 409 quote_in_review - die Arbeitsvorbereitung hat einen Preis für die Kalkulation oder eines ihrer Teile eingetragen. Eine Neukalkulation würde diesen Preis löschen.
• Jedes Feld ist optional; ein weggelassenes Feld behält seinen Wert: quantity, material_key, tolerance_class, geometric_class, surface_finish, confirmed_threads, confirmed_external_threads, hole_fits, face_tolerances, treatments, lead_time, process, countersinks. process nimmt dieselben Werte an wie in POST /quotes. countersinks markiert Durchgangsbohrungen eines geschnittenen Teils zum Senken: ein Bohrungsschlüssel aus choices.sheet_holes mit einem Winkel aus choices.countersink_angles ({"6.0": 90}); bei einer Schachtelung der Schlüssel des Teils (2:8.0). {} entfernt alle Markierungen. Für ein zerspantes Teil wird das Feld ignoriert.
• Welche Werte Gewinde und Passungen annehmen, steht im Block choices der Kalkulation.
• Bei einer Baugruppe können confirmed_threads, confirmed_external_threads und hole_fits ein einzelnes Teil benennen: "<Index>:<Bezeichnung>" für ein Gewinde (1:M16), "<Index>:<Durchmesser>" für eine Passung (2:80.0). GET /quotes/{id}/parts listet diese Schlüssel je Teil. Ein Wert ohne Index gilt für jedes Teil, das dieses Gewinde oder diesen Durchmesser hat.
• confirmed_threads, confirmed_external_threads und face_tolerances nehmen je höchstens 200 Einträge an.
• face_tolerances verwendet die Flächen der 3D-Vorschau als Schlüssel (face_3). Dafür braucht der API-Schlüssel files:read, weil nur damit die Vorschau abrufbar ist.

Zeichnungen

Konnte die Engine aus einer Zeichnung kein 3D-Modell erzeugen, bleibt die Kalkulation bei status analyzed mit release.state needs_input. drawing.reconstruction_declined nennt, was gefehlt hat. Für eine Zeichnung, die Ihr System gesendet hat, gibt es zwei Wege:

• POST /quotes/{id}/drawing-inputs liefert die fehlende Angabe nach: material_key, scale_ratio (1:2 auf dem Blatt ist 2.0) oder thickness_mm. Die Analyse läuft erneut und kalkuliert das Teil.
• POST /quotes/{id}/submit-drawing übergibt die Zeichnung der Arbeitsvorbereitung, die sie von Hand kalkuliert.
• Eine Zeichnung aus dem Widget prüft der Kunde selbst; für sie antworten beide Aufrufe mit 409 not_an_api_quote.

Vollständige Kalkulation

GET /quotes/{id}/detail (quotes:read) liefert alle Daten, die die Arbeitsvorbereitung in der Detailansicht der Kalkulation im Panel sieht. Ein System kann damit aus einer Kalkulation einen Auftrag anlegen, ohne dass Daten abgetippt werden. Die Antwort beginnt mit den Feldern von GET /quotes/{id}, mit denselben Namen und derselben Bedeutung, und ergänzt die übrigen Daten. Der Aufruf ändert nichts; die Kalkulation gilt im Panel danach nicht als geöffnet.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/detail \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
  "ref": "API-1043",
  "status": "priced",
  "unit_price": 41.5,
  "source": "api",
  "...": "...",
  "breakdown": { "machine_name": "DMU 50", "...": "..." },
  "release": { "state": "needs_review", "customer_may_see_price": false },
  "pricing": {
    "engine_unit_price": 41.5,
    "adjusted_unit_price": null,
    "customer_total": 1037.5,
    "min_order_top_up": 0.0,
    "delivery_cost": 25.0,
    "order_total": 1062.5,
    "vat_rate_pct": 19.0,
    "order_vat": 201.88,
    "order_gross": 1264.38,
    "lead_days": 10
  },
  "material": { "key": "alu_6061", "name": "Aluminium 6061", "en_number": "EN AW-6061", "din_number": "3.3211", "density_g_cm3": 2.7 },
  "part_mass_kg": 0.2004,
  "specification": {
    "tolerance_class": "f",
    "geometric_class": "K",
    "surface_finish": "ra_3_2",
    "lead_time": "standard",
    "treatments": [ { "key": "anodising", "name": "Anodising", "customer_visible": true } ],
    "confirmed_threads": null,
    "hole_fits": {},
    "...": "..."
  },
  "choices": {
    "thread_candidates": [ { "designation": "M8", "count": 4, "total_depth_mm": 72.0, "hole_key": "6.8" } ],
    "external_thread_candidates": [],
    "hole_fit_options": [ { "key": "8.0", "diameter": 8.0, "count": 2 } ],
    "section_candidate": null
  },
  "outcome": {
    "gate_status": "pending_review",
    "gate_reasons": [
      {
        "raw": "part_exceeds_envelope:vf2:part_size_y:350:310",
        "code": "part_exceeds_envelope",
        "machine_key": "vf2",
        "machine_name": "Haas VF-2",
        "field": "part_size_y",
        "actual": 350.0,
        "limit": 310.0
      }
    ],
    "dfm_reasons": [],
    "complexity": 34.2,
    "thresholds": { "complexity": 60.0, "thin_wall_mm": 1.0 },
    "analysis_error": null,
    "upload_abandoned": false,
    "review": { "note": null, "reviewed_at": null, "reviewed_by": null }
  },
  "drawing": { "is_drawing": false, "fallback": false, "reconstruction_declined": null },
  "readout": { "...": "exactly what GET /quotes/{id}/metrics returns" },
  "items": [],
  "order": null,
  "files": {
    "deleted_at": null,
    "original": { "available": true, "size_bytes": 482113, "path": "/quotes/6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33/file" },
    "preview": { "available": true, "path": "/quotes/6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33/preview.glb" },
    "readable": false
  },
  "customer_link": "https://quoting.metronq.com/precision-works/quote/1043?lang=en",
  "customer_link_shared_at": null,
  "access_code": null,
  "created_by_key": { "name": "PDM", "prefix": "a1b2c3d4" },
  "timestamps": { "analysis_queued_at": "...", "analyzed_at": "...", "billable_at": "...", "...": "..." }
}

• release.state - Stand des Preises: waiting (noch kein Preis), abandoned (die Datei ist nie angekommen), needs_input (eine Zeichnung wartet auf Angaben), failed (die Datei ließ sich nicht lesen), instant (kalkuliert, keine Prüfung erforderlich), needs_review (kalkuliert; die Arbeitsvorbereitung muss den Preis freigeben, bevor der Kunde ihn sieht), manual (die Engine konnte nicht kalkulieren, der Preis wird von Hand gesetzt), approved, rejected, ordered.
• release.customer_may_see_price - ob die Kundenseite dieser Kalkulation den Preis gerade anzeigt, nach derselben Regel, die die Kundenseite verwendet. Prüfen Sie dieses Feld, bevor Ihr System einen Preis an einen Kunden sendet: unit_price ist bei jeder Kalkulation mit Preis gefüllt, auch wenn sie noch auf die Freigabe durch die Arbeitsvorbereitung wartet.
• pricing.engine_unit_price - der von der Engine berechnete Preis. unit_price ist der geltende Preis: der Preis der Arbeitsvorbereitung, wenn sie ihn angepasst hat (pricing.adjusted_unit_price).
• pricing.order_total, order_vat, order_gross - der Betrag, zu dem ein Auftrag erteilt würde: die Teile nach dem Rabatt des Kunden, der Aufschlag bis zum Mindestauftragswert des Betriebs und der Versand, dazu die Umsatzsteuer zum Satz des Betriebs. Dieselbe Rechnung wie im Widget und im Angebots-PDF.
• material, part_mass_kg - der Werkstoff aus dem Katalog des Betriebs und das Gewicht des Teils (Volumen mal Dichte des Werkstoffs).
• specification - die Parameter, mit denen das Teil kalkuliert ist. confirmed_threads null: Die Frage nach Gewinden wurde nicht beantwortet. Leere Liste: Die Antwort war „keine“. Eine Behandlung mit customer_visible false berechnet der Betrieb, nennt sie dem Kunden aber nicht. price_overrides sind Korrekturen der Arbeitsvorbereitung für diese Kalkulation; sie sind hier lesbar und nur im Panel änderbar. process ist das für die Kalkulation gewählte Verfahren, null die Wahl der Engine; technologies nennt, wie das kalkulierte Teil gefertigt wird: milling, turning, laser, plasma oder waterjet. Ein aus Blech geschnittenes Teil hat zusätzlich edge_quality (Bezeichnung nach ISO 9013 und Grenzabmaß) und countersinks. Die ISO-2768-Klassen, surface_finish, hole_fits und face_tolerances gelten für ein geschnittenes Teil nicht.
• choices - die Werte, die POST /quotes/{id}/reprice für dieses Teil annimmt, aus der Analyse ermittelt: Gewindebezeichnungen, Außengewinde, die Bohrungen, die eine Passung nach ISO 286 aufnehmen können, und das erkannte Walzprofil, falls es eines gibt. part_kind ist sheet für ein Teil, das als aus Blech geschnitten kalkuliert wird, und processes nennt die Werte, die process für das Teil annimmt (zwei, wenn der Betrieb es schneiden und zerspanen kann). Für ein geschnittenes Teil: sheet_threads (Gewinde, für die das Blech dick genug ist), sheet_countersinks (im Modell gezeichnete Senkungen), sheet_holes und countersink_angles (was countersinks annimmt). Bei einer Baugruppe beschreibt choices das ganze Modell, die Bohrungen aller Teile zusammengezählt; die Optionen jedes einzelnen Teils liefert GET /quotes/{id}/parts.
• outcome.gate_reasons - die Gründe, aus denen die Prüf-Gates die Kalkulation angehalten haben. Jeder Grund steht als Rohstring (raw) und zerlegt: code, machine_key mit machine_name, field, actual und limit. Verwenden Sie die zerlegten Felder und zerlegen Sie raw nicht selbst, weil ein Maschinenschlüssel einen Doppelpunkt enthalten kann. dfm_reasons nennt die Codes, die bedeuten, dass das Teil selbst schwer herzustellen ist, im Unterschied zu einer eigenen Regel des Betriebs. outcome.review enthält die Notiz der Arbeitsvorbereitung, den Zeitpunkt der Entscheidung und die Person, die entschieden hat.
• readout - die Antwort von GET /quotes/{id}/metrics, oder null vor der Analyse.
• items - die Teile einer Baugruppe, jedes mit eigenem Preis, Status, eigenen Gründen und eigener Kostenaufschlüsselung. Die Geometrie steht in readout.parts unter demselben Index. label ist null, wenn die Datei das Teil nicht benennt.
• files - die API-Pfade der hochgeladenen Datei und der 3D-Vorschauen. Der Abruf erfordert files:read; readable gibt an, ob dieser Schlüssel die Berechtigung hat. Die Antwort enthält keinen Download-Link, sodass kein Eintrag in Ihren Logs die Datei eines Kunden öffnet.
• customer_link, access_code - die Kundenseite dieser Kalkulation und der Zugangscode, den sie abfragt. access_code kommt nur mit files:read zurück, weil die Kundenseite die Zeichnung und das 3D-Modell des Kunden zeigt.
• created_by_key - Name und Präfix des Schlüssels, der die Kalkulation gesendet hat, wenn sie über die API kam.

Vier weitere Aufrufe ergänzen die Detailansicht:

• GET /quotes/{id}/similar - die drei geprüften Teile des Betriebs, die diesem Teil am nächsten kommen, mit dem freigegebenen Preis und der Abweichung der Engine davon.
• GET /quotes/{id}/machine-options - die Kalkulation auf jeder Maschine des Parks, mit den Gründen, aus denen eine Maschine das Teil nicht annehmen kann, und der Maschine, die die Engine selbst wählt. Eine Maschine festlegen lässt sich nur im Panel.
• GET /quotes/{id}/parts - die Teile einer Baugruppe, jedes mit eigenen Gewinde- und Passungsoptionen und mit der Maschine, dem Werkstoff und der Rohteilbeschaffung, die die Arbeitsvorbereitung dafür gewählt hat.
• GET /quotes/{id}/pdf - das Angebotsdokument in der Sprache des Betriebs oder in einer anderen angebotenen Sprache (?locale=). Ohne customers:read fehlt die Empfängerzeile („Für“).

Alle Aufrufe mit Beispiel

Die Pfade beziehen sich auf die Basisadresse https://app.metronq.com mit dem Präfix /api/v1/integration. Der Schlüssel steht im Header Authorization: Bearer. Anfragen und Antworten sind JSON; Ausnahmen sind Pfade, die auf .csv enden, das PDF, die hochgeladene Datei und die 3D-Vorschauen. Bei jedem Aufruf steht die Berechtigung (Scope), die der Schlüssel haben muss; whoami braucht keine.

GET /whoami

Berechtigung: keine. Liefert den Betrieb, zu dem der Schlüssel gehört, die Berechtigungen des Schlüssels und seine Limits. Mit diesem Aufruf beginnt eine Integration; bei einem 403 zeigt er, welche Berechtigungen der Schlüssel hat.

curl https://app.metronq.com/api/v1/integration/whoami \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /config

Berechtigung: config:read. Liefert das gesamte Preisdokument: drei Kataloge, alle Kalkulationsparameter, die Prüf-Gates, die Auswahlstrategien und die Währung. POST /config/import/preview-json nimmt dieses Dokument unverändert und ohne Umhüllung entgegen. Der Modus replace, der auch löscht, was das Dokument nicht nennt, wird in einer Umhüllung angefordert: {"config": ..., "mode": "replace"}.

curl https://app.metronq.com/api/v1/integration/config \
  -H "Authorization: Bearer mq_live_YOUR_KEY" > pricing.json

GET /catalog/{name}

Berechtigung: config:read. Ein Katalog als JSON; {name} ist materials, machines oder treatments. Antwort: {catalog, count, items}. Fehler: 404 unknown_catalog.

curl https://app.metronq.com/api/v1/integration/catalog/materials \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /catalog/{name}.csv

Berechtigung: config:read. Derselbe Katalog als Tabelle, wie sie der Export im Panel erzeugt: mit BOM für Excel, mit dem Spaltentrenner des Betriebs, eine Zeile je Eintrag. Maschinen werden ohne Werkzeugliste exportiert, weil eine Zeile keine Liste aufnehmen kann.

curl https://app.metronq.com/api/v1/integration/catalog/machines.csv \
  -H "Authorization: Bearer mq_live_YOUR_KEY" > machines.csv

key;name;technology;hourly_rate;min_quantity;envelope_mm.1;envelope_mm.2;...
dmu50;DMU 50;milling;280,00;1;500,0;450,0;400,0;...

GET /tools

Berechtigung: config:read. Alle Werkzeuge des Betriebs als flache Liste; jede Zeile nennt ihre Maschine. ?machine= beschränkt die Liste auf eine Maschine. Fehler: 404 unknown_machine bei einem unbekannten Maschinenschlüssel.

curl https://app.metronq.com/api/v1/integration/tools \
  -H "Authorization: Bearer mq_live_YOUR_KEY"
curl "https://app.metronq.com/api/v1/integration/tools?machine=dmu50" \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /machines/{key}/tools

Berechtigung: config:read. Die Werkzeugbibliothek einer Maschine und der Eckenradius, der daraus folgt.

curl https://app.metronq.com/api/v1/integration/machines/dmu50/tools \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "machine_key": "dmu50",
  "machine_name": "DMU 50",
  "count": 3,
  "min_tool_radius_mm": 1.0,
  "tool_radius_effective_mm": 6.0,
  "items": [
    {
      "key": "e12",
      "kind": "endmill",
      "name": "12 mm Hartmetall",
      "diameter_mm": 12.0,
      "nose_radius_mm": null,
      "flute_length_mm": 45.0,
      "designation": "",
      "machine_key": "dmu50",
      "machine_name": "DMU 50",
      "cut_radius_mm": 6.0
    },
    { "key": "d6.8", "kind": "drill", "diameter_mm": 6.8, "cut_radius_mm": 3.4, "...": "..." },
    { "key": "m8", "kind": "tap", "diameter_mm": 8.0, "designation": "M8", "...": "..." }
  ]
}

PUT /machines/{key}/tools

Berechtigung: config:write. Ersetzt die gesamte Bibliothek, höchstens 500 Werkzeuge. Der Aufruf ist idempotent: Ein Abgleich kann seine Liste senden, ohne den bisherigen Stand zu kennen. Fehler: 422 duplicate_tool_key, wenn zwei Werkzeuge denselben Schlüssel haben.

curl -X PUT https://app.metronq.com/api/v1/integration/machines/dmu50/tools \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tools": [
        {"key": "e12", "kind": "endmill", "name": "12 mm Hartmetall",
         "diameter_mm": 12.0, "flute_length_mm": 45.0},
        {"key": "d6.8", "kind": "drill", "diameter_mm": 6.8},
        {"key": "m8", "kind": "tap", "diameter_mm": 8.0, "designation": "M8"}
      ]}'

POST /machines/{key}/tools

Berechtigung: config:write. Fügt ein Werkzeug hinzu oder ersetzt das Werkzeug mit demselben Schlüssel. Für ein System, das einzelne Änderungen meldet, statt die gesamte Bibliothek erneut zu senden.

curl -X POST https://app.metronq.com/api/v1/integration/machines/dmu50/tools \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "r8h7", "kind": "reamer", "diameter_mm": 8.0}'

DELETE /machines/{key}/tools/{tool}

Berechtigung: config:write. Entfernt ein Werkzeug. Fehler: 404 unknown_tool, wenn der Schlüssel nicht in der Bibliothek steht. Ein Abgleich kann so eine Entfernung von einem Tippfehler im eigenen Mapping unterscheiden.

curl -X DELETE https://app.metronq.com/api/v1/integration/machines/dmu50/tools/r8h7 \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /cutting-data

Berechtigung: config:read. Je Werkstoff die Schnittgeschwindigkeit und die Zeitspanvolumina, aus denen ein Preis gerechnet wird; je Maschine die Spindeldaten, mit denen diese Werte skaliert werden. Keine Schnittwerttabelle (siehe oben).

curl https://app.metronq.com/api/v1/integration/cutting-data \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

POST /config/import/preview

Berechtigung: config:write. Zeigt, was eine Tabelle bewirken würde, und schreibt nichts. Parameter: catalog (materials, machines oder treatments) und csv_base64 (die Datei als Base64). Antwort: das entstehende Dokument, die neuen und geänderten Schlüssel, die nicht lesbaren Zeilen, die nicht erkannten Spalten und ein base_hash. Fehler: 400 invalid_base64, 404 unknown_catalog.

curl -X POST https://app.metronq.com/api/v1/integration/config/import/preview \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"catalog\": \"materials\", \"csv_base64\": \"$(base64 -w0 materials.csv)\"}"

POST /config/import/preview-json

Berechtigung: config:write. Dasselbe für ein ganzes Dokument. Parameter: config und mode (merge oder replace, Voreinstellung merge). merge wendet nur an, was das Dokument angibt. Das Dokument selbst muss trotzdem vollständig sein: Die Kataloge für Werkstoffe und Maschinen sind Pflicht, und jeder Eintrag braucht seine Pflichtfelder. Der Modus bestimmt, was geschrieben wird, nicht, was in der Anfrage fehlen darf. replace übernimmt das Dokument vollständig, einschließlich Löschungen.

curl -X POST https://app.metronq.com/api/v1/integration/config/import/preview-json \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "merge", "config": {"materials": [ ... ], "machines": [ ... ]}}'

POST /config/import

Berechtigung: config:write. Wendet das Dokument aus einer Vorschau an. Parameter: config und der base_hash der Vorschau. Antwort: das gespeicherte Dokument. Fehler: 409 config_changed, wenn die Preisliste seit der Vorschau gespeichert wurde.

curl -X POST https://app.metronq.com/api/v1/integration/config/import \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d @commit.json      # {"config": ..., "base_hash": "..."} from the preview

{
  "materials": [ { "key": "alu-6061", "price_per_kg": 32.0, "...": "..." } ],
  "machines": [ "..." ],
  "treatments": [ "..." ],
  "params": { "margin_pct": 30.0, "...": "..." },
  "gates": { "mode": "review_all", "...": "..." },
  "machine_selection": "cheapest",
  "stock_selection": "cheapest",
  "currency": "PLN"
}

GET /quotes

Berechtigung: quotes:read. Kalkulationen, neueste zuerst. Parameter: since= für den regelmäßigen Abruf, status=, external_ref=, limit (1-200, Voreinstellung 100) und offset. Ohne customers:read sind die Kontaktfelder null.

curl "https://app.metronq.com/api/v1/integration/quotes?since=2026-09-16T00:00:00Z&status=priced&limit=50&offset=0" \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /quotes/{id}

Berechtigung: quotes:read. Eine Kalkulation mit der gespeicherten Kostenaufschlüsselung hinter ihrem Preis. GET /quotes, GET /quotes/{id}, GET /quotes/{id}/metrics und PATCH /quotes/{id} erreichen auch eine Kalkulation, die der Betrieb im Panel in den Papierkorb verschoben hat. Alle anderen Aufrufe zu einer einzelnen Kalkulation antworten für sie mit 404.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /quotes/{id}/metrics

Berechtigung: quotes:read. Die Messwerte der Analyse. Fehler: 409 not_analysed, solange die Datei noch analysiert wird. Dieser Code bedeutet „später erneut abfragen“, nicht „falsche Kennung“.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/metrics \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /orders

Berechtigung: quotes:read. Aufträge, neueste zuerst, mit denselben Filtern. Aufträge, die der Betrieb in den Papierkorb verschoben hat, sind nicht enthalten. Ohne customers:read sind die Kontaktfelder null.

curl "https://app.metronq.com/api/v1/integration/orders?since=2026-09-16T00:00:00Z&external_ref=WO-2026-0912" \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "items": [
    {
      "id": "1b7a44c0-9d2e-4e51-8a10-64d1f0a2e777",
      "quote_id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
      "status": "confirmed",
      "payment_status": "unpaid",
      "created_at": "2026-09-16T09:12:40+00:00",
      "paid_at": null,
      "quantity": 25,
      "unit_price": 41.5,
      "total_price": 1062.5,
      "min_order_top_up": 0.0,
      "delivery_cost": 25.0,
      "currency": "EUR",
      "external_ref": "WO-2026-0912",
      "customer": {
        "name": "Anna Muster",
        "email": "einkauf@example.com",
        "company": "Muster GmbH",
        "phone": "+49 000 0000000",
        "address": "Musterstraße 4",
        "postcode": "00000",
        "city": "Musterstadt"
      },
      "note": "",
      "customer_data_visible": true
    }
  ],
  "limit": 100,
  "offset": 0
}

GET /orders/{id}

Berechtigung: quotes:read. Ein Auftrag mit den Kundendaten für Rechnung und Versand.

curl https://app.metronq.com/api/v1/integration/orders/ORDER_ID \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

PATCH /quotes/{id}

Berechtigung: quotes:write. Schreibt die eigene Nummer (external_ref) auf eine Kalkulation; ein leerer Wert löscht sie. Andere Felder lassen sich nicht ändern, weil Preis und Freigabe bei der Engine und der Arbeitsvorbereitung liegen.

curl -X PATCH https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ref": "RFQ-2026-0455"}'

PATCH /orders/{id}

Berechtigung: quotes:write. Ändert eigene Nummer (external_ref), Status (status) und Zahlungsmarkierung (payment_status). Geändert wird nur, was im Body steht. Die Status confirmed und shipped senden dem Kunden des Betriebs eine E-Mail.

curl -X PATCH https://app.metronq.com/api/v1/integration/orders/ORDER_ID \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ref": "WO-2026-0912", "status": "in_production",
       "payment_status": "paid"}'

POST /quotes

Berechtigung: quotes:create. Legt eine Kalkulation für eine Datei an und liefert die Adresse für den Upload. Antwort: 201 mit quote, release und upload. Fehler: 403 quoting_blocked:<reason>, 429 analysis_backlog, 422 bei unbekanntem Feld, Dateityp, Werkstoff, unbekannter Behandlung oder Klasse.

curl -X POST https://app.metronq.com/api/v1/integration/quotes \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "bracket.step", "file_size_bytes": 482113, "quantity": 25,
       "material_key": "alu_6061", "tolerance_class": "f", "external_ref": "RFQ-2026-0455"}'

POST /quotes/{id}/confirm-upload

Berechtigung: quotes:create. Meldet, dass die Datei angekommen ist, reiht die Analyse ein und kalkuliert direkt danach. Antwort: 202. Nur für eine über die API angelegte Kalkulation (sonst 409 not_an_api_quote). Kontingent und Grenze der laufenden Analysen werden erneut geprüft (403 quoting_blocked, 429 analysis_backlog). Eine seit mehr als 30 Minuten abgelaufene Adresse ergibt 409 upload_expired.

curl -X POST https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/confirm-upload \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

POST /quotes/{id}/reprice

Berechtigung: quotes:create. Setzt neue Parameter; die Engine kalkuliert neu. Gilt für jede Kalkulation des Betriebs, bis über sie entschieden ist. Fehler: 409 analysis_pending, solange die Datei noch analysiert wird; 409 drawing_needs_input bei einer Zeichnung, die auf Angaben wartet. Bei einer Baugruppe kann ein Gewinde- oder Passungsschlüssel ein einzelnes Teil benennen (1:M16, 2:80.0); die Schlüssel jedes Teils listet GET /quotes/{id}/parts.

curl -X POST https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/reprice \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 50, "confirmed_threads": ["M8"], "hole_fits": {"8.0": "H7"}}'

POST /quotes/{id}/drawing-inputs

Berechtigung: quotes:create. Liefert Werkstoff, Maßstab oder Dicke für eine über die API gesendete Zeichnung nach, die die Engine nicht rekonstruieren konnte. Die Analyse läuft erneut und kalkuliert das Teil. Antwort: 202. Der Aufruf zählt wie eine neue Datei gegen die Grenze der laufenden Analysen.

curl -X POST https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/drawing-inputs \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scale_ratio": 2.0, "material_key": "steel_c45"}'

POST /quotes/{id}/submit-drawing

Berechtigung: quotes:create. Übergibt eine über die API gesendete Zeichnung, die die Engine nicht rekonstruieren konnte, an die Arbeitsvorbereitung zur Kalkulation von Hand. Optionale Parameter: quantity, material_key, customer_email.

curl -X POST https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/submit-drawing \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 10}'

GET /quotes/{id}/detail

Berechtigung: quotes:read. Alle Daten der Detailansicht; siehe oben.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/detail \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /quotes/{id}/similar

Berechtigung: quotes:read. Die drei geprüften Teile des Betriebs, die diesem Teil am nächsten kommen. Vor der Analyse ist die Liste leer.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/similar \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "count": 1,
  "items": [
    {
      "id": "0d9e7c21-5b3a-4f10-8c6d-9a2e4b7f1c05",
      "number": 1017,
      "ref": "WID-1017",
      "original_filename": "bracket-rev-a.step",
      "approved_unit_price": 39.0,
      "quantity": 20,
      "currency": "EUR",
      "auto_error_pct": 4.1,
      "date": "2026-08-30T14:02:11+00:00"
    }
  ]
}

GET /quotes/{id}/machine-options

Berechtigung: quotes:read. Der Preis auf jeder Maschine des Parks oder der Grund, aus dem eine Maschine das Teil nicht annehmen kann. Nur lesend; vor der Analyse ist die Liste leer.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/machine-options \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "count": 2,
  "items": [
    { "key": "dmu50", "name": "DMU 50", "technology": "milling", "unit_price": 41.5,
      "feasible": true, "reasons": [], "pinned": false, "auto": true },
    { "key": "vf2", "name": "Haas VF-2", "technology": "milling", "unit_price": null,
      "feasible": false, "pinned": false, "auto": false,
      "reasons": [ { "raw": "part_exceeds_envelope:vf2:part_size_y:350:310", "code": "part_exceeds_envelope", "...": "..." } ] }
  ]
}

GET /quotes/{id}/parts

Berechtigung: quotes:read. Die Teile einer Baugruppe, jedes mit den Gewinden und Bohrungen, die sich dafür bestätigen lassen, und mit den Vorgaben der Arbeitsvorbereitung für dieses Teil im Panel. Nur lesend. Bei einem Einzelteil, dessen Optionen im Block choices von GET /quotes/{id}/detail stehen, und vor der Analyse ist items leer. Fehler: 404 not_found bei einer unbekannten Kalkulation oder einer Kalkulation eines anderen Betriebs.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/parts \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "count": 2,
  "items": [
    {
      "index": 1,
      "label": "housing",
      "count": 1,
      "gate_status": "instant",
      "gate_reasons": [],
      "unpriced_reason": null,
      "price_overrides": { "machine_key": "dmu50", "stock_selection": "standard_stock" },
      "choices": {
        "thread_candidates": [ { "designation": "M16", "count": 4, "total_depth_mm": 96.0, "hole_key": "14.0", "key": "1:M16", "item_index": 1 } ],
        "external_thread_candidates": [],
        "hole_fit_options": [ { "key": "1:80.0", "diameter": 80.0, "count": 1, "hole_key": "80.0", "item_index": 1 } ]
      }
    },
    {
      "index": 2,
      "label": null,
      "count": 4,
      "gate_status": "tbd",
      "gate_reasons": [ { "raw": "probable_norm_part", "code": "probable_norm_part", "...": "..." } ],
      "unpriced_reason": "norm_part",
      "price_overrides": {},
      "choices": { "thread_candidates": [], "external_thread_candidates": [], "hole_fit_options": [] }
    }
  ]
}

• index - die Nummer des Teils, dieselbe wie in items von GET /quotes/{id}/detail und in readout.parts. label ist null, wenn die Datei das Teil nicht benennt. count - wie oft das Teil in der Baugruppe vorkommt.
• gate_status, gate_reasons - das Ergebnis der Prüf-Gates für dieses Teil; jeder Grund als Rohstring und zerlegt, wie in der vollständigen Kalkulation.
• unpriced_reason - warum die Engine das Teil nicht kalkuliert hat: norm_part (vermutlich ein Normteil, das zugekauft wird), casting (vermutlich ein Gussteil), implausible_time (die berechnete Bearbeitungszeit ist nicht plausibel), no_machine (keine Maschine des Parks nimmt das Teil an; Einzelheiten in gate_reasons). null, wenn die Engine das Teil kalkuliert hat.
• price_overrides - die Vorgaben der Arbeitsvorbereitung für dieses Teil im Panel: machine_key, material_key und stock_selection (cheapest, cut_to_size oder standard_stock). Fehlt ein Schlüssel, folgt das Teil der Kalkulation; {} bedeutet, dass nichts gewählt ist. Änderbar nur im Panel.
• choices - die Optionen nur dieses Teils: thread_candidates, external_thread_candidates und hole_fit_options. key ist der Wert, den POST /quotes/{id}/reprice für dieses Teil annimmt: "<Index>:<Bezeichnung>" für ein Gewinde (1:M16) in confirmed_threads oder confirmed_external_threads, "<Index>:<Durchmesser>" für eine Passung (1:80.0) als Schlüssel in hole_fits. hole_key ist der Durchmesser, unter dem die 3D-Vorschau die Bohrung führt.

GET /quotes/{id}/pdf

Berechtigung: quotes:read. Das Angebotsdokument als PDF. ?locale= wählt eine der Sprachen, die der Betrieb anbietet. Fehler: 422 language_not_offered bei einer anderen Sprache.

curl "https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/pdf?locale=en" \
  -H "Authorization: Bearer mq_live_YOUR_KEY" -o quote.pdf

GET /quotes/{id}/file

Berechtigung: quotes:read und files:read. Die vom Kunden hochgeladene Datei unter ihrem ursprünglichen Namen. Fehler: 409 file_not_uploaded, solange die Datei nicht angekommen ist; 404 files_deleted, nachdem die Aufbewahrungsfrist sie entfernt hat.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/file \
  -H "Authorization: Bearer mq_live_YOUR_KEY" -o bracket.step

GET /quotes/{id}/preview.glb und GET /quotes/{id}/items/{index}/preview.glb

Berechtigung: quotes:read und files:read. Die 3D-Vorschau als binäres glTF, für das ganze Teil oder für ein Teil einer Baugruppe. Fehler: 404 no_preview, wenn die Kalkulation keine Vorschau hat.

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/preview.glb \
  -H "Authorization: Bearer mq_live_YOUR_KEY" -o bracket.glb
curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/items/2/preview.glb \
  -H "Authorization: Bearer mq_live_YOUR_KEY" -o part-2.glb

Anfragelimits

Die Limits der API werden mit dem API-Zugang je Betrieb vereinbart; es gibt dafür keinen veröffentlichten Tarif.

• Voreinstellung: 120 Anfragen pro Minute und 20 000 Anfragen pro Tag. Der Tag beginnt um 00:00 UTC. Für ein Konto vereinbarte Werte können abweichen.
• Ein stündlicher Katalogabgleich mit einer minütlichen Abfrage neuer Kalkulationen bleibt deutlich unter diesen Werten.
• Die für Ihren Schlüssel geltenden Werte stehen in jeder Antwort im Header, in whoami und im Panel unter Einstellungen, Integrationen.
• Beim Anlegen eines Schlüssels kann der Betrieb unter „Tageslimit für diesen Schlüssel (optional)“ für diesen Schlüssel ein niedrigeres Tageslimit festlegen als für die übrigen.

Während einer Testphase des API-Zugangs gilt zusätzlich ein Gesamtkontingent: eine feste Zahl von Anfragen für den gesamten Test, die sich nicht täglich erneuert. Die Höhe wird mit jedem Betrieb einzeln vereinbart. Sie reicht aus, um eine Anbindung zu entwickeln, nicht, um sie dauerhaft zu betreiben; dafür ist ein vereinbarter API-Zugang nötig.

• Das Panel zeigt das Kontingent und den Verbrauch unter Einstellungen, Integrationen.
• whoami liefert das Kontingent als requests_total.
• Jede Antwort enthält den Zählerstand im Header.
• Ist das Kontingent aufgebraucht, antwortet die API mit 429 und total_quota_exceeded, ohne Retry-After, weil das Kontingent zu keinem Zeitpunkt erneuert wird.
• Die Zahlen in den Beispielen auf dieser Seite sind Beispielwerte.

Jede Antwort enthält den aktuellen Stand der Limits. Ein Client kann damit seine Anfragerate anpassen, bevor ein Limit erreicht ist. Die letzten beiden Header erscheinen nur, solange ein Gesamtkontingent gilt:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 41
X-RateLimit-Quota: 20000
X-RateLimit-Quota-Remaining: 19863
X-RateLimit-Quota-Reset: 51240
X-RateLimit-Total: 1000
X-RateLimit-Total-Remaining: 947

Fehlercodes

Eine bekannte Ablehnung enthält im Body einen kurzen Code. Werten Sie diesen Code aus; der HTTP-Status allein legt nicht fest, was als Nächstes zu tun ist.

• 429 rate_limited - das Minutenlimit ist erreicht. Dieselbe Anfrage funktioniert kurz darauf wieder; Retry-After nennt die Sekunden.
• 429 daily_quota_exceeded - das Tageslimit ist erreicht. Retry-After nennt die Sekunden bis 00:00 UTC.
• 429 total_quota_exceeded - das Gesamtkontingent der Testphase ist aufgebraucht. Kein Retry-After, weil Warten nichts ändert.
• 401 invalid_api_key - der Schlüssel ist unbekannt, widerrufen oder abgelaufen, oder für das Konto ist der API-Zugang geschlossen oder die Testphase, der Tarif oder die Lizenz abgelaufen. Alle Fälle ergeben dieselbe Antwort, weil eine Unterscheidung nur dem Dieb eines Schlüssels nützen würde.
• 403 missing_scope - der Schlüssel ist gültig, hat aber nicht die Berechtigung für diesen Endpunkt. Eine Wiederholung hilft nicht; nötig ist ein Schlüssel mit den passenden Scopes.
• 404 not_found, unknown_catalog, unknown_machine - diese Kalkulation, dieser Auftrag, dieser Katalog oder diese Maschine existiert in diesem Konto nicht.
• 409 config_changed - die Preisliste wurde zwischen Vorschau und Übernahme gespeichert; das gesendete Dokument beschreibt nicht mehr, was geschehen würde. Lesen Sie die Konfiguration neu, erstellen Sie eine neue Vorschau und wenden Sie sie erneut an.
• 409 not_analysed - die Kalkulation existiert, hat aber noch keinen Auslesebericht, weil die Datei noch analysiert wird. Fragen Sie kurz darauf erneut ab.
• 403 quoting_blocked:<reason> - der Betrieb kann derzeit keine neuen Kalkulationen anlegen. <reason> ist trial_limit oder plan_limit (die Kalkulationen der Testphase oder des Tarifmonats sind aufgebraucht) oder daily_limit (das Tageslimit des Betriebs ist erreicht). Es ist derselbe Grund, den auch das Panel anzeigt. Ein vollständig gesperrtes Konto erreicht diesen Punkt nicht; es wird bereits bei der Prüfung des Schlüssels mit 401 invalid_api_key abgewiesen.
• 429 analysis_backlog - fünf über die API gesendete Dateien des Betriebs sind bereits in der Analyse; Kalkulationen aus dem Widget und dem Panel zählen nicht mit. Retry-After: 30 nennt die Wartezeit bis zum nächsten Versuch.
• 409 file_not_uploaded - die Datei ist nicht im Speicher angekommen.
• 409 quote_not_awaiting_upload - der Upload dieser Kalkulation wurde bereits bestätigt.
• 409 upload_expired - die Upload-Adresse dieser Kalkulation ist seit mehr als 30 Minuten abgelaufen. Legen Sie eine neue Kalkulation an.
• 409 quote_in_review - die Arbeitsvorbereitung hat einen Preis für diese Kalkulation oder eines ihrer Teile eingetragen. Neu kalkulieren lässt sie sich dann nur im Panel.
• 409 analysis_pending - die Datei wird noch analysiert.
• 409 drawing_needs_input - die Kalkulation ist eine Zeichnung, die auf ihre Angaben wartet.
• 409 quote_closed - die Kalkulation ist freigegeben oder abgelehnt, oder der Kunde hat sie bestellt.
• 409 not_an_api_quote - die Kalkulation wurde nicht über die API angelegt. confirm-upload, drawing-inputs und submit-drawing gelten nur für Kalkulationen aus der API.
• 404 files_deleted - die Dateien wurden nach Ablauf der Aufbewahrungsfrist entfernt.
• 404 no_preview - diese Kalkulation hat keine 3D-Vorschau.
• 404 unknown_tool - dieses Werkzeug steht nicht in der Bibliothek der Maschine.
• 404 file_not_found - die Datei ließ sich im Speicher nicht lesen.
• 409 quote_already_analyzed - die Zeichnung wartet nicht mehr auf ihre Angaben: Sie wurde rekonstruiert, übergeben oder wird noch analysiert.
• 409 not_a_drawing - die Kalkulation ist keine Zeichnung.
• 400 invalid_base64 - csv_base64 ist kein gültiges Base64.
• 422 - die Anfrage wurde abgelehnt; es wurde nichts geschrieben. Bekannte Fehler haben einen kurzen Code: unknown_material, file_too_large, unsupported_file_type, unknown_treatment, unknown_lead_time, unknown_tolerance_class, unknown_geometric_class, unknown_surface_finish, unknown_thread, unknown_external_thread, unknown_hole, unknown_hole_fit, unknown_countersink_angle, unknown_region, no_inputs_given, implausible_scale, implausible_thickness, duplicate_tool_key, language_not_offered. Passt der Body nicht zum Schema (ein unbekanntes Feld, ein Wert außerhalb des Bereichs, ein Steuerzeichen im Dateinamen), enthält die Antwort stattdessen die Fehlerliste von FastAPI: {"detail":[{"type","loc","msg"}]}.

Berechtigungen im Panel

Import und Export folgen der Berechtigung für den Reiter Kalkulationsregeln: Der Inhaber und jeder Mitarbeiter, dem dieser Reiter freigegeben ist, können sie nutzen. Im Panel sind Exporte Downloads innerhalb der angemeldeten Sitzung. Außerhalb des Panels sind sie nur über einen API-Schlüssel mit der passenden Berechtigung möglich.

Anforderungen, die diese Seite nicht abdeckt, etwa eine Synchronisation zu festen Zeiten oder die automatische Übertragung neuer Angebote in das eigene System, senden Sie an contact@metronq.com. Nennen Sie dabei das eingesetzte System; diese Angabe fließt in die Planung weiterer Funktionen ein.