REST API und Webhooks

Basis: https://your-domain.example/api/v1. Nur HTTPS im externen Betrieb. Authorization: Bearer <token>; API-Tokens entstehen unter Schnittstellen. Die API ist zustandslos und akzeptiert keine Browsersitzung als API-Authentifizierung.

Methode	Pfad	Berechtigung	Inhalt
GET	/machines?page=1	machines:read	Eigene Maschinen, 50 je Seite, Gesamtzahl
POST	/machines	machines:write	Eigene Maschine erstellen
PUT	/machines/{id}	machines:write	Eigenen Maschinendatensatz vollständig ersetzen
GET	/leads?page=1	leads:read	Anfragen mit der eigenen Firma als Käufer oder Lieferant
PATCH	/leads/{id}	leads:write	Vertriebsstatus eigener eingehender Anfrage ändern
GET	/documents?machine={id}	documents:read	Metadaten eigener Dokumente
GET	/documents/{id}/original	documents:read	Eigenes aktuelles Original herunterladen

Beispiel für einen Maschinen-Request:

{
  "model": "CNC-500",
  "category": "cnc",
  "name": {"de": "Bearbeitungszentrum", "en": "Machining center", "ja": "マシニングセンタ"},
  "description": {"de": "Beschreibung", "en": "Description", "ja": "説明"},
  "status": "draft",
  "process": "Milling",
  "materials": ["Steel", "Aluminium"],
  "voltage": 400,
  "frequency": 50,
  "powerKw": 15,
  "precisionMm": 0.005,
  "specs": {"Working range": "500 × 400 × 300 mm"},
  "media": []
}

Preiswerte werden in den Geschäftsobjekten als ganzzahlige kleinste Währungseinheit gespeichert: EUR-Cent und ganze JPY. Die Maschinen-API verwaltet Herstellerdaten. Händlerkonditionen werden im eigenen Angebotsbereich gepflegt.

curl --fail --header "Authorization: Bearer $MACHINEBRIDGE_TOKEN" \
  https://your-domain.example/api/v1/machines

{"status":"qualified"}

Gültige Vertriebsstatus: new, qualified, quoted, won, lost. Fremde Datensätze werden weder ausgeliefert noch bearbeitet. Token-Nutzer müssen weiter aktiv/verifiziert sein und zur Token-Firma gehören. Das API-Kontingent beträgt zunächst 120 Requests pro Minute und Token. HTTP-Fehler liefern ein JSON-Objekt mit error.

Ausgehende Webhooks

Ereignisse: inquiry.created, inquiry.updated, machine.updated. Jede Firma verwaltet ihre eigenen Endpunkte. Ziele müssen öffentliche HTTPS-Adressen sein. Private Netze, Weiterleitungen und im URL eingebettete Zugangsdaten sind gesperrt.

{
  "id": "unique-event-id",
  "type": "inquiry.created",
  "occurred_at": "2026-10-18T09:00:00+00:00",
  "data": {"id": 123, "subject": "New production line", "machine": "CNC-500"}
}

Header:

X-Machinebridge-Event: unique-event-id
X-Machinebridge-Signature: t=unix_timestamp,v1=hex_hmac

Der HMAC ist HMAC-SHA256(timestamp + "." + unveränderter HTTP-Body, webhook_secret). Empfänger prüfen Signatur, Zeitfenster und Ereignis-ID und verarbeiten wiederholte Zustellungen idempotent. Die Plattform wertet nur 2xx als Erfolg und wiederholt fehlgeschlagene Zustellungen über Messenger. Nach ausgeschöpften Versuchen liegt der Auftrag im Fehlertransport; der Betreiber kann ihn prüfen und erneut zustellen.

Der Schlüssel wird nur bei Erstellung gezeigt. Gespeichert wird er mittels libsodium verschlüsselt; APP_SECRET gehört deshalb in die getrennte Geheimnissicherung.