# Media Content Handling

The SCX system **emits** seller events containing media file links; channels **receive** these events but do **not** generate them.
When handling media in event payloads and channel attributes, channels **MUST** follow these rules:

## Media Fields in Events and Attributes

- Events **provided by SCX** include `pictureList` and `mainPicture` in both **Seller:Offer.New** and **Seller:Offer.Update** payloads.
These fields are URLs to image files.
- Any channel-specific attribute defined as type `image` or `document` **also** appears as a URL to the corresponding file.


## Defining Media Attributes

Channels can register attributes of type image or document using the endpoint:


```json
PUT /v1/channel/attribute/global
{
  "attributeList": [
    {
      "attributeId": "DEMO-TYPES_image",
      "displayName": "Image",
      "description": "Link to Image file",
      "type": "image"
    },
    {
      "attributeId": "DEMO-TYPES_document",
      "displayName": "Document",
      "description": "Link to a Document file",
      "type": "document"
    }
  ]
}
```

## File URL Structure

All media links are hosted on an S3-compatible storage and **follow** this pattern:


```
https://s3.api.jtl-software.com/scx-api/public/{media-hash}.{ext}
```

where:

- `{media-hash}` is the SHA-1 hash of the file contents.
- `{ext}` is the file extension (`gif`, `jpg`, `png`, `svg`, or `pdf`).
- The filename's hash is unique; no additional metadata is encoded in the name.


## Media URL Lifetime

- Media URLs remain valid for **7 days** after event generation.
- After this period, requests **may** return HTTP 404 or 403.
- If a marketplace integration requires access beyond 7 days, the channel **SHALL** proactively fetch and store or rehost the file to ensure ongoing availability.


## Supported Formats and Size Limits

**Allowed MIME Types and Extensions:**

| MIME Type | Extension |
|  --- | --- |
| `image/gif` | `gif` |
| `image/jpeg` | `jpg` |
| `image/pjpeg` | `jpg` |
| `image/png` | `png` |
| `image/x-png` | `png` |
| `image/svg+xml` | `svg` |
| `application/pdf` | `pdf` |


- **Maximum file size:** 16 MB per media file.
- Files that do not match these MIME types or exceed the size limit may be rejected by the SCX system or remain unsupported.


### Example: Simplified Seller:Offer.New Event


```json
{
  "type": "Seller:Offer.New",
  "sellerId": "MYSELLERID",  
  "offerId": 1,  
  "mainPicture": "https://s3.api.jtl-software.com/scx-api/public/ca95311f233973a4a6b8a7415051096702e32110df8fac86b1d446ab54adf2eb812dc59e88d32cd9917d83425be5ea3999a89ab759ac8db1f0e872dd9c1b0872.jpg",
  "pictureList": [
    "https://s3.api.jtl-software.com/scx-api/public/ff5a3c1b2e9f8d7c6b5a4e3d2c1f0a9b8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3.jpg",
    "https://s3.api.jtl-software.com/scx-api/public/11aa22bb33cc44dd55ee66ff77gg88hh99ii00jj11kk22ll33mm44nn55oo66pp77.png"
  ],
  "channelAttributeList": [
    {
      "attributeId": "thumbnailImage",  
      "value": "https://s3.api.jtl-software.com/scx-api/public/aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899.pdf"
    }
  ]
}
```