Kunden (Customers)

Die Kunden-API verwaltet alle Kunden und deren Zuordnungen.

Sichtbarkeit

Benutzer sehen standardmäßig nur Kunden aus ihrer eigenen Gruppe. Mit der Berechtigung inventory_global werden alle Kunden sichtbar.

Endpunkte

Methode	Pfad	Beschreibung	Berechtigung
GET	/api/v2/customers	Alle Kunden auflisten	customers_view
GET	/api/v2/customers/{id}	Einzelnen Kunden abrufen	customers_view
POST	/api/v2/customers	Kunden anlegen	customers_edit
PUT	/api/v2/customers/{id}	Kunden aktualisieren	customers_edit
DELETE	/api/v2/customers/{id}	Kunden löschen	customers_delete

Feldmapping

Metrologie-Code	API-Feldname	Beschreibung
K4601	name	Kundenname
K4602	contact	Ansprechpartner
K4603	city	Stadt
K4604	postal_code	Postleitzahl

Alle Kunden auflisten

curl -X GET "https://example.com/api/v2/customers?page=1&per_page=25" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Query-Parameter

Parameter	Typ	Beschreibung
page	integer	Seitennummer (Standard: 1)
per_page	integer	Einträge pro Seite (Standard: 25)
sort	string	Sortierfeld, z.B. name oder -city (absteigend)
filter[name]	string	Nach Kundenname filtern
filter[city]	string	Nach Stadt filtern
filter[postal_code]	string	Nach Postleitzahl filtern

Antwort

{
  "data": [
    {
      "id": 5,
      "name": "Mustermann GmbH",
      "contact": "Max Mustermann",
      "city": "München",
      "postal_code": "80331",
      "address": "Industriestraße 42",
      "email": "info@mustermann.de",
      "phone": "+49 89 1234567"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 87,
    "last_page": 4
  },
  "links": {
    "first": "/api/v2/customers?page=1",
    "last": "/api/v2/customers?page=4",
    "next": "/api/v2/customers?page=2",
    "prev": null
  }
}

Einzelnen Kunden abrufen

curl -X GET "https://example.com/api/v2/customers/5" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Kunden anlegen

curl -X POST "https://example.com/api/v2/customers" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Neuer Kunde AG",
    "contact": "Erika Musterfrau",
    "city": "Berlin",
    "postal_code": "10115",
    "address": "Hauptstraße 1",
    "email": "info@neuer-kunde.de",
    "phone": "+49 30 9876543"
  }'

Pflichtfelder

Das Feld name ist ein Pflichtfeld. Alle weiteren Felder sind optional.

Erfolgreiche Antwort (201)

{
  "data": {
    "id": 88,
    "name": "Neuer Kunde AG",
    "contact": "Erika Musterfrau",
    "city": "Berlin",
    "postal_code": "10115",
    "address": "Hauptstraße 1",
    "email": "info@neuer-kunde.de",
    "phone": "+49 30 9876543"
  }
}

Kunden aktualisieren

curl -X PUT "https://example.com/api/v2/customers/88" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": "Hans Meier",
    "phone": "+49 30 1111111"
  }'

Partielle Updates

Es müssen nur die zu ändernden Felder gesendet werden.

Kunden löschen

curl -X DELETE "https://example.com/api/v2/customers/88" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Achtung

Ein Kunde kann nur gelöscht werden, wenn keine Inventare mehr mit ihm verknüpft sind.

Gruppen-Scoping

Die Kunden-API berücksichtigt automatisch die Gruppenzugehörigkeit des authentifizierten Benutzers:

Berechtigung	Sichtbarkeit
Ohne inventory_global	Nur Kunden der eigenen Gruppe
Mit inventory_global	Alle Kunden im System

# Benutzer ohne inventory_global sieht nur eigene Kunden
curl "https://example.com/api/v2/customers" \
  -H "Authorization: Bearer {token_ohne_global}"
# → Nur Kunden aus der Gruppe des Benutzers

# Benutzer mit inventory_global sieht alle Kunden
curl "https://example.com/api/v2/customers" \
  -H "Authorization: Bearer {token_mit_global}"
# → Alle Kunden im System

Sortierung und Filterung

# Nach Name sortiert
curl "https://example.com/api/v2/customers?sort=name" \
  -H "Authorization: Bearer {token}"

# Kunden in München
curl "https://example.com/api/v2/customers?filter[city]=München" \
  -H "Authorization: Bearer {token}"

# Nach PLZ filtern, absteigend sortiert
curl "https://example.com/api/v2/customers?filter[postal_code]=80331&sort=-name" \
  -H "Authorization: Bearer {token}"

Fehlercodes

HTTP-Status	Bedeutung
401	Nicht authentifiziert — ungültiger oder fehlender Token
403	Keine Berechtigung (customers_view, customers_edit oder customers_delete fehlt)
404	Kunde nicht gefunden oder nicht in der eigenen Gruppe
409	Kunde kann nicht gelöscht werden — verknüpfte Inventare vorhanden
422	Validierungsfehler — z.B. fehlender Kundenname
429	Rate-Limit überschritten