/
API-Referenz Bildkonverter

API-Referenz Bildkonverter

 

Die Schnittstelle unter /images/ bietet Ihnen umfassende Funktionen zur Verwaltung von Bildern unterschiedlicher Formate in unserem Shopsystem.

Über verschiedene Endpunkte können Sie Bilder hochladen, konvertieren, löschen sowie die zugehörigen URLs abrufen.

Inhaltsverzeichnis:

1. Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info

Endpunkte

GET

PUT

POST

DELETE

Befehl/Info

Endpunkte

GET

PUT

POST

DELETE

Image Upload

images/

2. Unterstützte Bildformate

  • Bitmap

  • FITS

  • GIF

  • Graphics Kernel System

  • JPEG

  • NIFF

  • PM

  • PNG

  • XFIG

  • XPM

  • TIFF

  • GIMP XCF

  • webp

 

3. Datenfelder eines Verzeichnisses

Name

Typ

Verwendung

Name

Typ

Verwendung

name

String

Der Name des Verzeichnisses

path

String

Der Pfad zum Verzeichnis

subDirectories

Array

Ein Array von Unterverzeichnissen

Beispiel:

{ "name": "products", "path": "products", "subDirectories": [ { "name": "thumbnail", "path": "products/thumbnail", "subDirectories": [] }, { "name": "normal", "path": "products/normal", "subDirectories": [] }, { "name": "large", "path": "products/large", "subDirectories": [] } ] }

 

4. Methoden zur Verwaltung von Bildern

4.1 GET images/url/{typeId}

Dieser Endpunkt liefert die URL eines Bildes basierend auf dem angegebenen Typ (typeId) und optional dem gewünschten Format.

Er wird verwendet, um den Speicherort eines Bildes im System zu ermitteln – insbesondere, wenn der Pfad nach dem Hochladen nicht bekannt ist.
Gültige Werte für typeId sind:

  • categories für Kategoriebilder,

  • products für Produktbilder,

  • appImages für Bilder innerhalb der App-Oberfläche.

Die zurückgegebene URL zeigt auf das Zielverzeichnis für den jeweiligen Bildtyp, sodass anschließend Bilddaten korrekt abgelegt oder referenziert werden können. Leseberechtigungen sind erforderlich.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/images/url/products?formatNodeId=content.imageFormat.normal

Antwort:

{ "url": "//content.myshop.localhost/products/normal" }

Fehler

Typ

Grund

Fehler

Typ

Grund

401 Unauthorized

 

Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kategorie-, Produkt- oder App-Daten.

400 Bad Request

"invalidValue"

typeId ∉ {"categories", "products", "appImages"}
subshopId ist ungültig.

400 Bad Request

"missing"

subshopId oder formatNodeId wurden nicht übergeben.

 

4.2 GET images/directories/{typeId}

Dieser Endpunkt liefert die Struktur der verfügbaren Bildverzeichnisse als Baumstruktur zurück.

Je nach Wert des Parameters typeId werden entweder Quellverzeichnisse (source) oder Zielverzeichnisse (target) ausgegeben. Die Antwort enthält eine hierarchische Darstellung der vorhandenen Ordner und Unterordner.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/images/directories/source

Antwort:

{ "items": [ { "name": "myDir1", "path": "myDir1", "subDirectories": [ { "name": "myDir2", "path": "myDir1/myDir2", "subDirectories": [] }, { "name": "myDir3", "path": "myDir1/myDir3", "subDirectories": [ { "name": "myDir4", "path": "myDir1/myDir3/myDir4", "subDirectories": [] } ] } ] } ] }

Fehlercodes:

Fehler

Typ

Grund

Fehler

Typ

Grund

401 Unauthorized

 

Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von konvertierten Bildern.

400 Bad Request

"invalidValue"

typeId ∉ {"target", "source"}

 

4.3 GET images/convert/results

Dieser Endpunkt liefert eine Liste der Ergebnisse abgeschlossener Bildkonvertierungen.

Für jedes konvertierte Bild werden Informationen wie Quelldatei, Zieldatei, Zielformat, Dateigröße, Dauer der Konvertierung und der Verarbeitungsstatus zurückgegeben. So kann nachvollzogen werden, ob und wie ein Bild erfolgreich in verschiedene Formate umgewandelt wurde.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/images/convert/results

Antwort:

{ "items": [ { "duration": 0, "fileSize": "55 KB", "format": "app", "formatId": "content.imageFormat.app", "message": "success", "output": "app/Screenshot 2025-03-24 222742.png", "outputFilename": "Screenshot 2025-03-24 222742.png", "source": "upload/9fcd26d4c240/Screenshot 2025-03-24 222742.png", "sourceFilename": "Screenshot 2025-03-24 222742.png", "status": "success" }, { "duration": 1, "fileSize": "55 KB", "format": "normal category", "formatId": "content.imageFormat.normalCategory", "message": "success", "output": "categories/normal/Screenshot 2025-03-24 222742.png", "outputFilename": "Screenshot 2025-03-24 222742.png", "source": "upload/9fcd26d4c240/Screenshot 2025-03-24 222742.png", "sourceFilename": "Screenshot 2025-03-24 222742.png", "status": "success" }, { "duration": 1, "fileSize": "55 KB", "format": "normal product", "formatId": "content.imageFormat.normalProduct", "message": "success", "output": "products/normal/Screenshot 2025-03-24 222742.png", "outputFilename": "Screenshot 2025-03-24 222742.png", "source": "upload/9fcd26d4c240/Screenshot 2025-03-24 222742.png", "sourceFilename": "Screenshot 2025-03-24 222742.png", "status": "success" }, { "duration": 1, "fileSize": "10 KB", "format": "thumbnail product", "formatId": "content.imageFormat.thumbnailProduct", "message": "success", "output": "products/thumbnail/Screenshot 2025-03-24 222742.png", "outputFilename": "Screenshot 2025-03-24 222742.png", "source": "upload/9fcd26d4c240/Screenshot 2025-03-24 222742.png", "sourceFilename": "Screenshot 2025-03-24 222742.png", "status": "success" } ] }

Fehlercodes:

Fehler

Typ

Grund

Fehler

Typ

Grund

401 Unauthorized

 

Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von konvertierten Bildern.

 

4.4 GET images/convert/status

Dieser Endpunkt liefert den aktuellen Status eines laufenden oder den letzten bekannten Status eines abgeschlossenen Bildkonvertierungsprozesses.

Dabei werden Informationen wie Fortschritt, Anzahl erfolgreicher oder fehlgeschlagener Konvertierungen, sowie Timer-Daten (Startzeit, Endzeit, Dauer) zurückgegeben. Der Endpunkt ermöglicht die Überwachung und Auswertung von Bildkonvertierungsprozessen im System.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/images/convert/status

Antwort:

{ "canceled": true, "counter": { "error": 0, "skipped": 0, "success": 0, "warning": 0 }, "formatCounter": { "error": 0, "skipped": 0, "success": 0, "warning": 0 }, "progress": { "finished": 0, "percentage": 0, "total": 0 }, "progressFormat": { "finished": 0, "percentage": 0, "total": 0 }, "running": false, "status": "ready", "timer": { "duration": 0, "end": 0, "start": 0 }, "usedFormats": [] }

Fehlercodes:

Fehler

Typ

Grund

Fehler

Typ

Grund

401 Unauthorized

 

Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von konvertierten Bildern.

503 Service Unavailable

 "internalError"

Der Konvertierungsprozess kann nicht geprüft werden.

 

4.5 GET images/report/products

Dieser Endpunkt liefert einen Bericht über die Nutzung von Produktbildern im Shopsystem.

Dabei werden sowohl fehlende Bilder (missingImages) als auch ungenutzte Bilder (unusedImages) aufgelistet. Der Bericht hilft dabei, Bilddateien zu identifizieren, die keinem aktiven Produkt mehr zugeordnet sind oder die im System fehlen, und unterstützt so bei der Optimierung der Bilddatenverwaltung.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/images/report/products

Antwort:

{ "createdAt": "2025-04-25T15:55:39.000Z", "id": 1, "missingImages": [], "unusedImages": [ { "filename": "th.jpg", "format": "" }, { "filename": "Screenshot 2025-03-24 222742.png", "format": "" }, { "filename": "th.jpg", "format": "" }, { "filename": "Screenshot 2025-03-24 222742.png", "format": "" } ] }

Fehlercodes:

Fehler

Typ

Grund

Fehler

Typ

Grund

401 Unauthorized

 

Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Produktdaten.

 

4.6 POST images/upload

Dieser Endpunkt ermöglicht das Hochladen eines Bildes in das Shopsystem.

Das Bild wird als Base64-kodierter String im Request-Body übertragen. Zusätzlich kann angegeben werden, in welche Formate das Bild konvertiert werden soll. Nach dem erfolgreichen Upload wird der Pfad zur gespeicherten Bilddatei zurückgegeben.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/images/upload

Request Body:

{ "fileName": [ "Screenshot 2025-03-24 222742.png" ], "formats": [ "content.imageFormat.normalProduct", "content.imageFormat.thumbnailProduct" ], "imageData": [ "iVBORw0KGgoAAAANSUhEUgAAAU8AAAJcCAYAAAB5ZyZaAAAAAXNSR0IArs4c6QAAAA..." ] }

Antwort:

{ "path": "upload/c14cb01ea580", "size": 1 }

Fehlercodes:

Fehler

Typ

Grund

Fehler

Typ

Grund

401 Unauthorized

 

Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Veröffentlichen von konvertierten Bildern.

400 Bad Request

 

Request body konnte nicht geladen werden.

400 Bad Request

"missing"

formats wurden nicht übergeben.

400 Bad Request

"invalidValue"

Ein Bildformat ist ungültig. imageData ist ungültig.

400 Bad Request

"invalidFormat"

Das Feld formats ist kein Array von Strings.
Das Feld fileName ist kein String und kein Array von Strings.
Das Feld imageData ist kein String.

400 Bad Request

"invalidFileFormat"

Das Bild hat ein ungültiges Format.

400 Bad Request

“unknownDataField"

Request body enthält etwas außer fileName, imageData und formats.

503 Service Unavailable

 "internalError"

Das Konvertieren vom Bild ist fehlgeschlagen.

 

4.7 POST images/upload/convert

Dieser Endpunkt ermöglicht das Hochladen eines Bildes mit anschließender sofortiger Konvertierung in ein oder mehrere definierte Zielformate.

Das Bild wird als Base64-kodierter String im Request-Body übermittelt. Im Unterschied zum normalen Upload wird hier die Konvertierung automatisch angestoßen, sodass direkt optimierte oder formatangepasste Varianten erstellt werden können. Nach Abschluss wird eine Übersicht der erzeugten Bilddateien zurückgegeben.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/images/upload/convert

Request Body:

{ "fileName": "myPicture.png", "formats": [ "content.imageFormat.normalCategory", "content.imageFormat.normalProduct" ], "imageData": "iVBORw0KGgoAAAANSUhEUgAAAU8AAAJcCAYAAAB5ZyZaAAAAAXNS..." }

Antwort:

{ "items": [ { "duration": 0, "fileSize": "55 KB", "format": "normal category", "formatId": "content.imageFormat.normalCategory", "message": "success", "output": "categories/normal/myPicture.png", "outputFilename": "myPicture.png", "source": "upload/169357275289/myPicture.png", "sourceFilename": "myPicture.png", "status": "success" }, { "duration": 0, "fileSize": "55 KB", "format": "normal product", "formatId": "content.imageFormat.normalProduct", "message": "success", "output": "products/normal/myPicture.png", "outputFilename": "myPicture.png", "source": "upload/169357275289/myPicture.png", "sourceFilename": "myPicture.png", "status": "success" } ] }

Fehlercodes:

Fehler

Typ

Grund

Fehler

Typ

Grund

401 Unauthorized

 

Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Veröffentlichen von konvertierten Bildern. Der Bildtyp wird in den Berechtigungen berücksichtigt.

400 Bad Request

 

Request body konnte nicht geladen werden.

400 Bad Request

"missing"

formats wurden nicht übergeben.

400 Bad Request

"invalidValue"

Ein Bildformat ist ungültig. imageData ist ungültig. Es wurden mehrere Bilder übergeben.

400 Bad Request

"invalidFormat"

Das Feld formats ist kein Array von Strings.
Das Feld fileName ist kein String und kein Array von Strings.
Das Feld imageData ist kein String.

400 Bad Request

"invalidFileFormat"

Das Bild hat ein ungültiges Format.

400 Bad Request

“unknownDataField"

Request body enthält etwas außer fileName, imageData und formats.

503 Service Unavailable

 "internalError"

Das Konvertieren vom Bild ist fehlgeschlagen.

 

4.8 POST images/report

Dieser Endpunkt startet die Überprüfung der im System vorhandenen Bilder auf fehlende oder ungenutzte Dateien.

Die Ausführung erfolgt asynchron: Nach dem erfolgreichen Start der Überprüfung wird kein direktes Ergebnis zurückgegeben.

Der vollständige Bericht kann anschließend über GET /images/report/ abgerufen werden. Der Endpunkt stellt sicher, dass Bilddaten regelmäßig auf Konsistenz geprüft werden können.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/images/report

Request Body:

{}

Antwort:

{}

Fehlercodes:

Fehler

Typ

Grund

Fehler

Typ

Grund

401 Unauthorized

 

Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Produkten.

503 Service Unavailable

 "internalError"

Der Überprüfung konnte nicht gestartet werden.

 

4.9 POST images/convert/start

Dieser Endpunkt startet den Konvertierungsprozess für im System gespeicherte Bilder.

Dabei werden die Bilder in die jeweils definierten Zielformate umgewandelt (z. B. verschiedene Größen oder Dateiformate). Die Ausführung erfolgt asynchron, aber es wird nach dem Starten vom Prozess eine direkte Rückmeldung zu den konvertierten Bildern geliefert. Der Fortschritt und der Status der Konvertierung können später über den Endpunkt GET /images/convert/status abgefragt werden.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/images/convert/start

Request Body:

{ "action": "manual", "source": "directory", "formatList": [ "content.imageFormat.app", "content.imageFormat.normalCategory", "content.imageFormat.normalProduct", "content.imageFormat.thumbnailProduct" ], "directory": "upload/e6122e69f1d0" }

Antwort:

{ "canceled": true, "counter": { "error": 0, "skipped": 0, "success": 0, "warning": 0 }, "formatCounter": { "error": 0, "skipped": 0, "success": 4, "warning": 0 }, "progress": { "finished": 1, "percentage": 100, "total": 1 }, "progressFormat": { "finished": 4, "percentage": 100, "total": 4 }, "running": false, "status": "finished", "timer": { "duration": 1745857938, "end": 1745857938, "start": 0 }, "usedFormats": [ "content.imageFormat.app", "content.imageFormat.normalCategory", "content.imageFormat.normalProduct", "content.imageFormat.thumbnailProduct" ] }

Fehlercodes:

Fehler

Typ

Grund

Fehler

Typ

Grund

401 Unauthorized

 

Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Veröffentlichen von konvertierten Bildern.

400 Bad Request

 

Request body konnte nicht geladen werden. Das Format wurde nicht gefunden. Das Format hat ein ungültiges Quellverzeichnis oder es wurde ein ungültiges Quellverzeichnis angegeben. Es existieren keine Formate. Das Feld source enthält etwas außer format oder directory.

503 Service Unavailable

 "internalError"

Der Konvertierungsprozess kann nicht gestartet werden.

 

4.10 POST images/convert/cancel

Dieser Endpunkt bricht einen aktuell laufenden Konvertierungsprozess für Bilder ab.

Der Abbruch erfolgt nicht asynchron, es wird eine direkte Rückmeldung zu den konvertierten Bildern gleich geliefert.

Nach der Ausführung kann der Status des Konvertierungsprozesses über den Endpunkt GET /images/convert/status wieder abgefragt werden. Der Abbruchvorgang erfordert entsprechende Berechtigungen.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/images/convert/cancel

Request Body:

{}

Antwort:

{ "canceled": true, "counter": { "error": 0, "skipped": 0, "success": 0, "warning": 0 }, "formatCounter": { "error": 0, "skipped": 0, "success": 2, "warning": 0 }, "progress": { "finished": 1, "percentage": { "source": "100.0", "parsedValue": 100 }, "total": 1 }, "progressFormat": { "finished": 2, "percentage": { "source": "100.0", "parsedValue": 100 }, "total": 2 }, "running": false, "status": "finished", "timer": { "duration": 1745858133, "end": 1745858133, "start": 0 }, "usedFormats": [ "content.imageFormat.normalProduct", "content.imageFormat.thumbnailProduct" ] }

Fehlercodes:

Fehler

Typ

Grund

Fehler

Typ

Grund

401 Unauthorized

 

Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Veröffentlichen von konvertierten Bildern.

503 Service Unavailable

 "internalError"

Der Konvertierungsprozess kann nicht geprüft werden.

 

4.11 POST images/directories/{typeId}

Ein Verzeichnis wird erstellt.

Bei typeId = source handelt es sich um Quellverzeichnisse, bei typeId = target handelt es sich um Zielverzeichnisse.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/images/directories/target

Request Body:

{ "path": "myDir", "name": "test" }

Antwort:

{ "items": [ { "name": "myDir", "path": "myDir", "subDirectories": [ { "name": "test", "path": "myDir/test", "subDirectories": [] } ] } ] }

 

4.12 DELETE images/directories/{typeId}

Dieser Endpunkt löscht ein Verzeichnis innerhalb des angegebenen Bereichs (source oder target) für Bilddateien.

Über den Request-Body können der Pfad zum übergeordneten Verzeichnis sowie der Name des zu löschenden Ordners definiert werden. Nach erfolgreicher Löschung wird die aktualisierte Verzeichnisstruktur ohne das gelöschte Verzeichnis als Baumstruktur zurückgegeben.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/images/directories/target

Request Body:

{ "path": "myDir/test" }

Antwort:

{ "items": [ { "name": "myDir", "path": "myDir", "subDirectories": [] } ] }

Fehlercodes:

Fehler

Typ

Grund

Fehler

Typ

Grund

401 Unauthorized

 

Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Löschen von konvertierten Bildern.

400 Bad Request

 

Request body konnte nicht geladen werden.

400 Bad Request

"invalidValue"

typeId ∉ {"target", "source"} | path fehlt oder ist leer.

404 Not Found

 

Das Verzeichnis wurde nicht gefunden.

503 Service Unavailable

 "internalError"

Das Löschen vom Verzeichnis ist fehlgeschlagen.

 

4.13 DELETE images/upload/{typeId}

Dieser Endpunkt löscht eines oder mehrere Bilder innerhalb eines angegebenen Bereichs (categories, products oder appImages).

Der Name der zu löschenden Datei(en) wird über das Feld fileName im Request-Body angegeben, entweder als String oder als Array von Strings. Optional kann über das Feld formats angegeben werden, welche Bildformate berücksichtigt werden sollen; andernfalls werden alle Formate gelöscht. Der Endpunkt prüft sorgfältig die Gültigkeit der angegebenen Parameter und verarbeitet sowohl Einzel- als auch Mehrfachlöschungen.

© 2025 WEBSALE AG | Impressum | Datenschutz