API-Referenz — Übersicht

Das anyPIM bietet eine vollständige REST-API mit über 370 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:

Client → HTTP-Request → Auth (Sanctum Token) → Controller (Validierung) → Service (Geschäftslogik) → Response (JSON-Antwort)

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:

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

Rate Limiting

Die API ist durch Rate Limiting geschützt:

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.

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

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 Medien zwischen Zentrale und Tochtergesellschaften austauschen.