Schnittstelle (API)

Maschinen und Dokumente direkt aus Ihrem ERP oder PLM anlegen, statt sie einzutippen.

Diese Seite richtet sich an die Person, die es einbaut. Für alles andere genügt der Kundenbereich.

Was Sie brauchen

Ein MVO-Doku-Konto mit gebuchter Schnittstelle. 30 Tage kostenlos testen, danach 260 € netto je Jahr. Zu finden unter Konto & Firma → Schnittstelle.
Einen Schlüssel. Der Inhaber legt ihn dort an; er wird genau einmal angezeigt.

Das Abo bezahlt den Zugang, nicht die Freigaben. Jede freigegebene Maschine wird wie immer je Maschine berechnet (149–289 € netto) — auch während der kostenlosen Testphase. Ein Schlüssel mit Freigaberecht ist damit faktisch ein Zahlungsmittel: Deshalb gibt es je Schlüssel einen eigenen Schalter dafür und eine Obergrenze je Monat, die Sie selbst setzen.

Anmeldung

Der Schlüssel gehört in den Kopf jeder Anfrage:

Authorization: Bearer mvo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Höchstens 120 Aufrufe je Minute und Schlüssel. Darüber antwortet die Schnittstelle mit 429. Das ist kein Schutz gegen Angreifer — dafür ist der Schlüssel da —, sondern gegen eine Schleife im aufrufenden System.

Die Wege

POST /api/v1/maschinen

GET /api/v1/maschinen/{serienNr}

POST /api/v1/maschinen/{serienNr}/dokumente

GET /api/v1/maschinen/{serienNr}/etikett.svg|pdf|dxf

Adressiert wird über Ihre Serien-Nummer — nicht über eine von uns vergebene Kennung. Sie müssen sich also nichts merken, was Sie nicht ohnehin haben.

Maschine anlegen

curl -X POST https://mvo-doku.de/api/v1/maschinen \
  -H "Authorization: Bearer $MVO_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
        "serienNr":     "2027-4711",
        "bezeichnung":  "Abkantpresse",
        "typ":          "AP-330",
        "baujahr":      2027,
        "kontakt":      "service@ihre-firma.de",
        "stufe":        "akte"
      }'

Antwort 201 mit der Maschine, darin die fertige qrAdresse fürs Typenschild.

Wiederholte Aufrufe sind unschädlich

Schickt Ihr System denselben Aufruf nach einem Netzfehler noch einmal, entsteht keine zweite Maschine. Sie bekommen die vorhandene zurück, mit "bereitsVorhanden": true und Status 200 statt 201. Ihre Serien-Nummer ist der Schlüssel dafür — sie ist bei Ihnen ohnehin eindeutig.

Dokument hochladen

curl -X POST https://mvo-doku.de/api/v1/maschinen/2027-4711/dokumente \
  -H "Authorization: Bearer $MVO_SCHLUESSEL" \
  -F "datei=@betriebsanleitung.pdf" \
  -F "ebene=pub" \
  -F "art=anleitung"

Ebene	Wer sieht sie	Erlaubte Arten
`pub`	jeder, per QR-Code	`anleitung`, `konformitaet`
`op`	Betreiber, mit Passwort	`sonstiges`
`sec`	Behörde, auf Verlangen	`risikobeurteilung`, `sonstiges`

Passt die Art nicht zur Ebene, antwortet die Schnittstelle mit 400 und nennt, was dort hingehört. Nach der Freigabe ist pub eingefroren — Uploads dorthin werden mit 409 abgelehnt.

Antworten

Code	Bedeutung
`200` / `201`	hat geklappt
`400`	Angabe fehlt oder passt nicht
`401`	kein oder unbekannter Schlüssel
`402`	Schnittstelle nicht freigeschaltet oder gesperrt
`403`	dieser Schlüssel darf das nicht
`404`	Maschine nicht gefunden
`409`	Zustand verhindert es (z. B. bereits freigegeben)
`429`	zu viele Aufrufe

Jede Fehlerantwort enthält fehler im Klartext und meist ein maschinenlesbares grund-Feld.

Was die Schnittstelle (noch) nicht tut

Freigeben. Das Recht lässt sich je Schlüssel bereits vergeben, der Weg dafür kommt in Kürze. Der Grund für die Sorgfalt: Freigeben löst Geld aus und steckt in derselben Logik wie im Browser — wir bauen sie nicht ein zweites Mal nach, sondern teilen sie. Zwei Meinungen darüber, wann eine Maschine freigegeben ist, wären der schlimmste denkbare Fehler.

Auf Anfrage

Anmeldung über Ihren Identitätsanbieter (SSO). Wenn Ihre IT verlangt, dass sich Mitarbeiter über Microsoft Entra ID oder einen anderen Anbieter anmelden, richten wir das ein. Wir setzen dabei auf OpenID Connect; SAML nur, wenn Ihre Umgebung nichts anderes zulässt.

Mehrsprachige Oberfläche für internationale Standorte.

Beides bauen wir nicht auf Vorrat, sondern für den konkreten Fall — dann passt es zu Ihrer Umgebung, statt für alle zu raten. Schreiben Sie an info@mvo-doku.de, was bei Ihnen im Einsatz ist.

Verfügbarkeit und Sicherung

Wer eine Schnittstelle in ein laufendes System hängt, will wissen, worauf er sich verlässt. Deshalb im Klartext:

Der Dienst läuft in Deutschland und startet nach einer Störung automatisch neu.
Alle Daten werden täglich gesichert, zusätzlich hält der Rechenzentrumsbetreiber Stände auf einem getrennten System vor. Der maximale Datenverlust beträgt damit 24 Stunden.
Nach einem schweren Ausfall wird der Dienst innerhalb von sieben Tagen wiederhergestellt — als verbindliche Obergrenze.
Eine Verfügbarkeitsquote in Prozent sagen wir nicht zu. Der Dienst läuft auf einem einzelnen Server ohne automatische Umschaltung; „99,9 %" wäre nicht belegbar. Wir halten die konkreten Angaben oben für ehrlicher.

Das steht so auch in § 9 der AGB. Bauen Sie Ihr System so, dass es eine vorübergehende Störung übersteht — Aufrufe einfach später wiederholen. Das Anlegen ist idempotent, ein Wiederholungsversuch richtet also keinen Schaden an.

Was passiert, wenn das Abo endet

Die Schlüssel antworten mit 402. Gelöscht werden sie nicht — nehmen Sie das Abo wieder auf, laufen dieselben Schlüssel weiter, und in Ihrem System ist nichts umzustellen. Maschinen, Freigaben, Dokumente und QR-Codes arbeiten unverändert weiter; gesperrt ist ausschließlich der maschinelle Zugang.

Zum Kundenbereich · Wissen zur Maschinenverordnung