MEDIIO API-Initiative
Join the initiative

Use case · Product image retrieval

Fetch product images directly from the supplier

Retrieve all available images for one or more supplier article numbers or a PZN – for reliable visual identification of the product.

POST /api/ProductImage/query
Join the initiative Back to use cases
api.host · REST
POST /api/ProductImage/query 
[
  {
    "articleNumber": "4711",
    "images": [
      { "url": "…/4711_1000.webp", "mimeType": "webp", "isPrimary": true }
    ]
  }
]

User story

„As a user, I want to retrieve the image or the available images for one or more supplier article numbers or a PZN, so I have visual support in identifying the product."

Scope

How product images are delivered

One or more articles are requested by supplier article number or PZN. 0, 1 or several images are returned per article – derived from the acceptance criteria.

Batch request

One or more articles per request – identified by article number or PZN.

Image as URL

Returned as an image URL (e.g. from a CDN) – no binary upload via this endpoint.

Format & size

webp as default, jpg as fallback · max. 200 KB · resolution 800–1200 px.

Primary & order

isPrimary marks the main image (position 0), further images via position.

Deliberately out of scope

  • Images are referenced as URLs – the image itself is fetched from the supplier’s CDN.
  • Other media (documents/datasheets) are handled via a dedicated endpoint.

Request

Request body

POST with a JSON array – each entry is a supplier article number or a PZN (batch: 1..n).

Field Type Meaning
articleNumber string Supplier article number.
pzn string PZN – alternative to articleNumber.

One of the two fields is enough per entry. Multiple entries = multiple articles at once.

Examples

Typical queries

As a consumer I want to … – and send the following request:

retrieve all available images for a supplier article number

POST
https://host_url/api/ProductImage/query
Body 
[
  { "articleNumber": "4711" }
]

retrieve all available images for a PZN

POST
https://host_url/api/ProductImage/query
Body 
[
  { "pzn": "4711" }
]

retrieve images for several article numbers at once

POST
https://host_url/api/ProductImage/query
Body 
[
  { "articleNumber": "4711" },
  { "articleNumber": "0815" },
  { "articleNumber": "42" }
]

Response

Response (JSON)

One array entry per requested article. images contains 0..n images with URL, format, dimensions and optionally text, primary flag and position.

Response · application/json 
[
  {
    "articleNumber": "string",
    "pzn": "string",
    "images": [
      {
        "url": "string",
        "mimeType": "string",
        "width": 0,
        "height": 0,
        "desc": "string",
        "isPrimary": true,
        "position": 0
      }
    ]
  }
]
200 Success with result – one or more images.
204 Success without result – no image available.

Key fields

articleNumber / pzn

Article identification (one of the two set).

images[]

0..n images – empty means: no image (HTTP 204).

url

Image URL, e.g. “…/123_400.webp” (mandatory).

mimeType

Image format: “webp” or “jpeg”/“jpg” (mandatory).

width / height

Width and height in pixels (mandatory).

desc

Text for the image (optional).

isPrimary

Marks the main image (optional).

position

Order; 0 = main image, otherwise numeric (optional).

Self-test

Validate response

Paste the JSON response of your /api/ProductImage/query endpoint – its structure is validated instantly in the browser against this schema.

No validation yet – paste JSON and click “Validate”.

Want to use this use case in your system?

Become part of the API Initiative – we’ll support you through onboarding.

Join the initiative Back to use cases