API

WAMA REST-API-Leitfaden

Integriere deine Systeme mit WAMA über die HTTPS-JSON-API unter https://www.wama.cloud.

Diese Seite beschreibt die Authentifizierung mit API-Schlüsseln, den Multi-Tenant-Kontext der Verkaufsstelle, Paginierung und Fehler. Für Request- und Response-Felder öffne die interaktive OpenAPI-Referenz (Vollbild).

Erste Schritte

1. Erstelle einen API-Schlüssel in der WAMA-Web-App (Einstellungen → Integrationen). Bevorzuge Nur Lesen, sofern deine Integration keine Schreibzugriffe braucht.
2. Rufe /api/** mit dem Header Authorization: Bearer <api_key> auf (oder X-Api-Key).
3. Nutze die interaktive API-Referenz für Request-/Response-Felder.

Basis-URL: https://www.wama.cloud

Authentifizierung

API-Schlüssel erstellen

1. Melde dich im Browser als Konto-Administrator bei WAMA an (ROLE_USER / Administrator).
2. Öffne Einstellungen → Integrationen.
3. Wähle API-Schlüssel erstellen, setze einen Namen, die Verkaufsstelle, den der Schlüssel gebunden wird, den Scope und optional ein Ablaufdatum.
4. Kopiere den Schlüssel sofort — das vollständige Geheimnis wird nur einmal angezeigt.

Schlüsselformat:

wama_<publicId>_<secret>

Speichere ihn wie ein Passwort (Umgebungsvariable oder Secret Manager). Committe niemals Schlüssel in Quellcode oder öffentliche Tickets.

Scopes

Bevorzuge Nur Lesen für Reporting, Sync und KI-Assistenten, sofern keine Schreibzugriffe nötig sind.

API aufrufen

Sende den Schlüssel bei jeder Anfrage als HTTP-Header:

Authorization: Bearer wama_YOUR_PUBLIC_ID_YOUR_SECRET

Optionaler Alias (derselbe Schlüssel):

X-Api-Key: wama_YOUR_PUBLIC_ID_YOUR_SECRET

Wenn sowohl ein JWT Authorization: Bearer … als auch X-Api-Key gesetzt sind, gewinnt das JWT und X-Api-Key wird ignoriert.

Beispiel:

curl -X GET 'https://www.wama.cloud/api/products' \
  -H 'Authorization: Bearer wama_YOUR_PUBLIC_ID_YOUR_SECRET' \
  -H 'Accept: application/json'

Äquivalent mit X-Api-Key:

curl -X GET 'https://www.wama.cloud/api/products' \
  -H 'X-Api-Key: wama_YOUR_PUBLIC_ID_YOUR_SECRET' \
  -H 'Accept: application/json'

Widerrufen oder rotieren

Widerrufe Schlüssel unter Einstellungen → Integrationen. Widerrufene oder abgelaufene Schlüssel liefern 401. Zum Rotieren einen neuen Schlüssel erstellen, den Client aktualisieren und den alten widerrufen.

API-Schlüssel können keine anderen API-Schlüssel erstellen, auflisten oder widerrufen — verwalte Schlüssel nur in der Web-App (Sitzungslogin).

Verkaufsstelle (Mandantenfähigkeit)

Lagerbestand, Verkäufe und zugehörige Daten gehören zu einer Verkaufsstelle (POS).

Jeder API-Schlüssel ist bei der Erstellung an eine POS gebunden. Anfragen mit diesem Schlüssel nutzen immer diese POS — du wechselst die POS nicht mit POST /api/point-of-sales/..., wenn du einen API-Schlüssel verwendest.

Erstelle einen eigenen Schlüssel pro Lager/Filiale, wenn du mehrere POS-Kontexte brauchst.

Paginierung

Listen-Endpunkte akzeptieren Spring-Data-Paginierungsparameter:

Erfolgreiche Listenantworten enthalten:

Fehler

Die meisten Fehler liefern JSON in dieser Form:

{
  "message": "error.validation",
  "description": "Optional human-readable text",
  "fieldErrors": [
    {
      "objectName": "productDTO",
      "field": "barcode",
      "message": "NotNull",
      "defaultMessage": "must not be null"
    }
  ]
}

Parametrisierte Domänenfehler können { "message": "...", "params": ["..."] } zurückgeben.

Typische Auth-Ergebnisse:

Konventionen

• JSON-Request- und -Response-Bodies (Content-Type: application/json)
• Daten als ISO-8601 mit Offset (z. B. 2026-03-15T10:30:00.000Z)
• Geldbeträge als Dezimalwerte mit Währungsobjekten wo vorgesehen
• Ids werden vom Server vergeben; beim Anlegen weglassen (oder null senden)

Beispiel: Produkte auflisten

curl 'https://www.wama.cloud/api/products?page=0&size=20&sort=timeModified,desc' \
  -H 'Authorization: Bearer wama_YOUR_PUBLIC_ID_YOUR_SECRET'

OpenAPI-Referenz

Alle öffentlichen Endpunkte durchsuchen: