Schnittstellen für Firmensysteme

Eine REST-Schnittstelle, mit der ERP, PLM und Eigenentwicklungen Modelle und Pässe pflegen. Die Beschreibung als OpenAPI-Dokument ist öffentlich.

Dokumentation

Was die Schnittstelle kann

Funktionen der Schnittstelle
Thema	Inhalt
Schlüssel und Rechte	API-Schlüssel mit Rechten: `read`, `write`, `export`, `webhooks`. Ein Schlüssel gehört zu einem Mandanten und sieht nur dessen Daten.
Lesen und Schreiben	Modelle und Pässe anlegen oder aktualisieren, je Seriennummer, mit Wartungseinträgen. Sammelaufruf (`/v1/bulk`) für viele Datensätze.
Seiten und Änderungen	Cursor-Blättern und `updatedSince` liefert Änderungen und Löschungen seit dem letzten Lauf.
Wiederholbar	Idempotency-Key für schreibende Aufrufe, 24 Stunden gespeichert.
Fehler	Maschinenlesbar nach RFC 9457 (`application/problem+json`) mit Fehlercode.
Webhooks	Ereignisse wie `passport.created` oder `declaration.issued`, signiert nach Standard Webhooks, bis zu zehn Zustellversuche. Derzeit nicht eingeschaltet: Der Betreiber hat den dafür nötigen Schlüsselring noch nicht eingerichtet.
Connectoren	Abholung aus REST- und OData-Quellen mit Zuordnung ohne Code, Probelauf vor dem Scharfschalten. Derzeit nicht eingeschaltet, aus demselben Grund wie die Webhooks.
Export	Vollexport des Mandanten mit Prüfsummen und einem Werkzeug, das ihn ohne unseren Server prüft.
Testmandant	Ein Testmandant ohne öffentliche Pässe für Integrationstests.

Beispiel: Pass je Seriennummer anlegen

Ein Aufruf legt den Pass an oder aktualisiert ihn. Die Antwort enthält die Adresse für den QR-Code.

curl -X PUT "https://maschinenpass.de/api/v1/passports/by-serial/SN-2026-0412" \
  -H "X-API-Key: mp_..." \
  -H "Idempotency-Key: 6f1c1d52-3c0e-4b3b-9a53-1f0d7a3c5e11" \
  -H "Content-Type: application/json" \
  -d '{ "modelKey": "bp-200", "baujahr": 2026, "gtin": "09506000134352" }'

{
  "passport": {
    "uid": "53ethqbzawr44",
    "serial": "SN-2026-0412",
    "publicUrl": "https://maschinenpass.de/p/53ethqbzawr44",
    "qrUrl": "https://maschinenpass.de/01/09506000134352/21/SN-2026-0412"
  },
  "created": true,
  "changed": true
}

Grenzen

Der Export ist synchron und auf 10.000 Pässe begrenzt. Dateien werden einzeln abgeholt.
Die Connector-Vorlagen sind bisher nur gegen eigene Testsysteme geprüft, nicht gegen SAP, Business Central oder Windchill selbst. Feldnamen sind im Einzelfall zu prüfen.
Einen Dateitransfer per SFTP gibt es nicht.
Die Schnittstelle schreibt in den Pass, nie zur Maschine.

Felder der Schreibwege, Zusammenführen, Beispiel, Signaturprüfung, Wiederholplan und Connectoren stehen auf der Dokumentationsseite.

Anbindung besprechen

Für Anbindungen und Schlüssel melden Sie sich per E-Mail. kontakt@verdagen.ai