API-Referenz

Das anyPIM bietet eine vollständige REST-API mit über 90 Endpunkten, die sämtliche Funktionen des Systems programmatisch zugänglich machen. Die API folgt konsistenten Konventionen und unterstützt JSON als Datenformat.

Basis-URL

Alle API-Endpunkte befinden sich unter dem Pfad:

https://pim.ihre-domain.de/api/v1

Für die lokale Entwicklung:

http://localhost:8000/api/v1

Authentifizierung

Die API verwendet Bearer-Token-Authentifizierung über Laravel Sanctum. Bei jedem Aufruf muss ein gültiges Token im Authorization-Header mitgesendet werden:

Authorization: Bearer {token}

Details zur Authentifizierung finden Sie unter Authentifizierung.

Request-Flow

Der Weg einer API-Anfrage durch das System:

Konventionen

Datenformat

Alle Anfragen und Antworten verwenden JSON. Setzen Sie die entsprechenden Header:

Content-Type: application/json
Accept: application/json

Paginierung

Listen-Endpunkte unterstützen Paginierung über Query-Parameter:

Parameter	Typ	Standard	Beschreibung
page	Integer	1	Aktuelle Seite
per_page	Integer	25	Einträge pro Seite (max. 100)

Sortierung

Sortierung wird über den sort-Parameter gesteuert. Aufsteigende Sortierung ist Standard, ein Minus-Präfix sortiert absteigend:

GET /api/v1/products?sort=name          # Aufsteigend nach Name
GET /api/v1/products?sort=-created_at   # Absteigend nach Erstelldatum

Filterung

Filter werden als Query-Parameter übergeben:

GET /api/v1/products?filter[status]=active&filter[product_type]=simple

Includes (Eager Loading)

Verwandte Ressourcen können über den include-Parameter mitgeladen werden:

GET /api/v1/products?include=variants,media,prices

Sparse Fields

Mit dem fields-Parameter können Sie die zurückgegebenen Felder einschränken:

GET /api/v1/products?fields=id,sku,name,status

Suche

Freitextsuche über den search-Parameter:

GET /api/v1/products?search=Bohrmaschine

Sprachauswahl

Bei mehrsprachigen Ressourcen bestimmt der lang-Parameter die Sprache:

GET /api/v1/products?lang=de

Fehlerformat

Fehler werden im Format RFC 7807 (Problem Details for HTTP APIs) zurückgegeben:

{
  "type": "https://pim.example.com/docs/errors/validation-error",
  "title": "Validierungsfehler",
  "status": 422,
  "detail": "Die übermittelten Daten sind ungültig.",
  "errors": {
    "sku": ["Das Feld 'sku' ist ein Pflichtfeld."],
    "name_de": ["Das Feld 'name_de' darf maximal 255 Zeichen lang sein."]
  }
}

HTTP-Statuscodes

Code	Bedeutung
200	Erfolgreiche Anfrage
201	Ressource erfolgreich erstellt
204	Erfolgreich, kein Inhalt (z. B. nach Löschen)
400	Ungültige Anfrage
401	Nicht authentifiziert
403	Keine Berechtigung
404	Ressource nicht gefunden
422	Validierungsfehler
429	Rate Limit erreicht
500	Interner Serverfehler

Rate Limiting

Die API ist durch Rate Limiting geschützt:

Kategorie	Limit	Beschreibung
Standard	60 Anfragen/Minute	Allgemeine API-Endpunkte
Export	600 Anfragen/Minute	Export-Endpunkte (höheres Limit)

Bei Überschreitung wird ein 429 Too Many Requests-Status mit folgenden Headern zurückgegeben:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 45

Endpunkt-Gruppen

Die API gliedert sich in folgende Bereiche:

Authentifizierung

Login, Logout, Token-Verwaltung und Benutzerinformationen.

API-Keys

Langlebige API-Schlüssel für externe Integrationen, Skripte und Machine-to-Machine-Zugriff. API-Keys sind an Benutzer gebunden und erben deren Rollenberechtigungen.

Produkte

CRUD-Operationen für Produkte, Attributwerte, Varianten, Medien, Preise und Relationen.

Attribute

Verwaltung von Attributen, Attributtypen, Einheitengruppen, Einheiten, Wertelisten, Wertelisteneinträgen und Attributansichten.

Hierarchien

Verwaltung von Hierarchien, Baumstrukturen, Knoten und knotenspezifischen Attributzuordnungen.

PQL

PQL-Abfragen ausführen, validieren und analysieren.

Export

Export-Endpunkte für JSON und Publixx-Format. Dokumentiert unter JSON-Export und Publixx-Export.

Import

Import-Endpunkte für Upload, Validierung und Ausführung. Dokumentiert unter Import.

Benutzerverwaltung

CRUD-Operationen für Benutzer, Rollen und Berechtigungen.

Sprachen

Verwaltung der verfügbaren Inhaltssprachen.

Medien

Upload, Verwaltung und Zuordnung von Medien.

Preise

Verwaltung von Preisarten, Währungen und Produktpreisen.

PimSync API

Bidirektionale Synchronisation zwischen anyPIM-Instanzen. Produkte, Attribute, Preise und Media zwischen Zentrale und Tochtergesellschaften austauschen.