Schnittstelle (API)

Was ist möglich?

Alles davon ist ein Tarif-Merkmal. Ob es für Ihre Organisation freigeschaltet ist, steht unter Team → Tarif & Nutzung und auf den Seiten selbst („im Tarif nicht enthalten“).

Schnellstart: der erste Zählerstand

1. Unter Team → API auf Neuer Zugangsschlüssel. Dafür brauchen Sie die Rolle Verwaltung oder das Gruppenrecht „API-Zugangsschlüssel verwalten“ (siehe Team, Rollen und Rechte).
2. Bezeichnung eintragen (z. B. „Kompressor-Gateway Halle 1“), das Recht Zählerstände melden ankreuzen, Bereich und Ablauf nach Bedarf, Schlüssel erzeugen.
3. Den Schlüssel (vmk_…) jetzt kopieren. Er wird nur einmal angezeigt.
4. Die Nummer der Maschine steht in der Adresse ihrer Seite (/maschinen/17/). Den Zählerstand melden:

curl -X POST https://vormerk.de/api/v1/machines/17/meter-readings \
  -H "Authorization: Bearer vmk_…" \
  -H "Content-Type: application/json" \
  -d '{"value": 1234.5}'

Antwort: 201 mit dem gespeicherten Stand. Die Maschine muss einen Zähler führen (Maschinenformular: „Zähler führen“).

Zugangsschlüssel

Ein Schlüssel ist ein Dienstkonto der Organisation: Er gehört keiner Person, und niemand muss ihn mit einem Passwort teilen. Vormerk speichert nur einen Fingerabdruck, den Klartext sehen Sie nur beim Anlegen.

Rechte (Scopes). Geben Sie nur, was das Fremdsystem braucht.

Bereich. Standorte (inklusive Unterstandorten), Objektarten und einzelne Objekte, beliebig kombinierbar. Ein Objekt gehört zum Bereich, wenn es zu einer der Auswahlen passt. Nichts gewählt bedeutet: die ganze Organisation. Was außerhalb liegt, gibt es für den Schlüssel nicht (Antwort 404, nicht 403). Beispiel: Der Schlüssel „Sensor Presse 4“ darf nur an der einen Maschine Zählerstände melden.

Weitere Einschränkungen. Ablaufdatum (Vorgabe: ein Jahr), Liste erlaubter Adressen (eine Adresse oder ein Netz wie 203.0.113.0/24 je Zeile) und ein eigenes Limit pro Minute.

Pflege. - Widerrufen wirkt sofort. Auf der Seite des Schlüssels sehen Sie letzte Nutzung und Abrufe der letzten Tage. - Rotation: neuen Schlüssel anlegen, im Fremdsystem eintragen, den alten widerrufen. - Bewahren Sie Schlüssel wie Passwörter auf: nicht im Quelltext, nicht in Adressen, nicht in Tickets.

Die Schnittstelle im Alltag

Grundregeln - Adresse: https://vormerk.de/api/v1/…. Anmeldung mit Authorization: Bearer vmk_…. - Daten als JSON. Zeiten nach ISO 8601 mit Zeitzone (2026-10-15T08:30:00+02:00). Dezimalzahlen kommen als Text ("1234.50"), damit nichts gerundet wird. - Listen nehmen limit (höchstens 200) und offset. Antwort: {"count": …, "items": […]}. - Fehler haben immer die Form {"code": "…", "detail": "…"}.

Wiederholen ohne Doppelungen. Schreibende Abrufe nehmen die Kopfzeile Idempotency-Key (bis 64 Zeichen) an. Sendet Ihr System denselben Abruf mit demselben Schlüssel nochmals, zum Beispiel nach einem Netzfehler, liefert Vormerk 24 Stunden lang dieselbe Antwort und führt nichts ein zweites Mal aus. Mit anderen Daten unter demselben Schlüssel: 422 idempotency_conflict.

Objekte ansprechen. Wo ein Objekt gebraucht wird, genügt eine der Angaben id, inventory_no (Inventarnummer) oder external_id (Kennung in Ihrem System, im Maschinenformular unter „Externe Kennung“).

Abrufe im Überblick

Zählerstände

Ein Stand darf nicht kleiner sein als der letzte (422 meter_decreased) und nicht in der Zukunft liegen (read_at_in_future). Ohne read_at gilt der Zeitpunkt des Abrufs.

Sammelabruf für Gateways, mit Ergebnis je Zeile:

curl -X POST https://vormerk.de/api/v1/meter-readings/batch \
  -H "Authorization: Bearer vmk_…" -H "Content-Type: application/json" \
  -d '[{"external_id": "PLC-7", "value": 1210.5},
       {"inventory_no": "K-1",  "value": 880}]'

{"ok": 2, "errors": 0, "results": [{"index": 0, "status": "ok", "id": 91}, {"index": 1, "status": "ok", "id": 92}]}

Fehlerhafte Zeilen stehen mit status: "error" und code in der Antwort. Die übrigen werden gespeichert.

Störungen auslösen

curl -X POST https://vormerk.de/api/v1/incidents \
  -H "Authorization: Bearer vmk_…" -H "Content-Type: application/json" \
  -d '{"title": "Druckabfall Kompressor", "priority": "high",
       "object": {"external_id": "PLC-7"}, "external_ref": "ALARM-4711"}'

Mit external_ref (Ihre Alarmnummer) entsteht keine zweite Störung, solange die erste offen ist: Die Antwort ist dann 200 mit "duplicate": true und der vorhandenen Störung. Priorität high und standstill benachrichtigen die Admins wie bei einer Meldung aus der Oberfläche. Der Verlauf der Störung vermerkt den Schlüssel.

Abgleich mit ERP oder CMMS

Der regelmäßige Abgleich läuft über die externe Kennung:

curl -X PUT https://vormerk.de/api/v1/machines/by-external-id/SAP-1000234 \
  -H "Authorization: Bearer vmk_…" -H "Content-Type: application/json" \
  -d '{"name": "Presse 4", "inventory_no": "P-4", "location_id": 3, "serial_no": "A-77"}'

Gibt es die Kennung, wird die Maschine geändert (200), sonst angelegt (201). Beim Anlegen gelten Ihre Tarifgrenze für Maschinen und der Bereich des Schlüssels; Pläne aus den Vorlagen der Objektart entstehen wie bei einer Anlage in der Oberfläche.

Kalender abonnieren

Ein Schlüssel nur mit dem Recht calendar:read genügt. Adresse für Kalender-Apps: https://vormerk.de/api/v1/calendar.ics?token=vmk_…. Weil dieser Schlüssel in der Adresse steht, darf er nichts anderes können.

Grenzen und Fehlercodes

Pro Schlüssel gelten Abrufe je Minute (Vorgabe 120, einstellbar) und für die Organisation das Kontingent des Tarifs je Abrechnungsperiode. Darüber antwortet die Schnittstelle mit 429 und Retry-After.