REST API — Dokumentation

Authentifizierung

Alle Anfragen müssen den API-Key als Bearer-Token im Authorization-Header mitschicken. Der Key beginnt immer mit nsk_ und ist nach Erstellung nur einmalig im Klartext sichtbar.

Authorization: Bearer nsk_<dein-key>

Fehlt der Header oder ist der Key ungültig/widerrufen, antwortet die API mit 401 Unauthorized.

Rate-Limiting

Jeder API-Key darf maximal 60 Anfragen pro Minute (gleitendes Fenster) absetzen. Bei Überschreitung antwortet die API mit 429 Too Many Requests. Warte kurz und versuche es dann erneut.

Basis-URL

https://normsafe.app/api/v1

Alle Antworten sind JSON. Erfolgreiche Antworten haben HTTP-Status 200 und ein Feld data (Array). Fehlerantworten haben ein Feld error (String).

Endpunkte

curl -H "Authorization: Bearer nsk_..." \
  "https://normsafe.app/api/v1/inspections?type=device&since=2025-01-01T00:00:00Z&limit=50"

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "type": "device",
      "inspected_at": "2025-06-15T10:30:00.000Z",
      "result": "passed",
      "next_inspection_due": "2026-06-15",
      "object_name": "Verlängerungskabel 25m",
      "customer_name": "Musterbau GmbH",
      "location_label": "Lager EG"
    }
  ]
}

curl -H "Authorization: Bearer nsk_..." \
  "https://normsafe.app/api/v1/customers"

curl -H "Authorization: Bearer nsk_..." \
  "https://normsafe.app/api/v1/devices?limit=200"

Webhooks

Webhooks erlauben es, Push-Benachrichtigungen an eigene Systeme zu senden, sobald eine Prüfung abgeschlossen wird. Konfiguriert werden sie unter Einstellungen → Webhooks.

Events

Payload-Format

POST https://deine-url.example.com/webhook
Content-Type: application/json
X-NormSafe-Signature: sha256=<hmac-hex>

{
  "event": "inspection.failed",
  "org_id": "uuid-...",
  "timestamp": "2025-06-15T10:30:00.000Z",
  "data": {
    "id": "uuid-...",
    "type": "device",
    "object_id": "uuid-...",
    "inspected_at": "2025-06-15T10:30:00.000Z",
    "result": "failed",
    "next_inspection_due": null
  }
}

Signatur-Verifikation

Jede Zustellung enthält den Header X-NormSafe-Signature: sha256=<hex>. Verifiziere ihn in deinem Empfänger, um sicherzustellen, dass die Anfrage tatsächlich von NormSafe stammt:

// Node.js-Beispiel
import { createHmac, timingSafeEqual } from "crypto";

function verifySignature(rawBody: string, secret: string, header: string): boolean {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(header);
  const b = Buffer.from(expected);
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

Verwende immer timingSafeEqual statt ===, um Timing-Angriffe zu vermeiden.

Wiederholungsversuche

Bei HTTP-Fehlercodes oder Verbindungsfehlern wiederholt NormSafe die Zustellung automatisch. Wiederholungen laufen gesammelt einmal täglich; jede Zustellung trägt den Header X-NormSafe-Delivery-Id, über den Empfänger doppelte Zustellungen erkennen können:

Fehlercodes