Entity · products

Product Schema

Schema-ID

product

Collection

products

Permissions

Lesenproduct_view
Anlegenproduct_create
Ändernproduct_edit
Löschenproduct_delete

Felder

Product Schema

products4 Permissions

Schema for validating product entities (product portfolio items)

namestringerforderlich

Product name

1–300 Zeichen

descriptionstringoptional

Product description (plain text). SSoT for the long marketing text shown in the customer-portal shop across all linked articles. See ADR 0094c.

max 4000 Zeichennullable

descriptionHtmlstringoptional

Rich text HTML description — SSoT for the cluster-wide marketing description shown in the customer-portal shop for all linked articles. See ADR 0094c.

nullable

productCategoryIduuidoptional

Product category UUID

nullable

manufacturerstringoptional

Manufacturer or vendor name (e.g. "Microsoft", "Acronis"). SSoT — articles fall back to this when their own manufacturer is empty; articles may override for OEM cases (see ADR 0094a).

max 200 Zeichennullable

websitestringoptional

Product or manufacturer website URL

max 500 Zeichennullable

logoS3Keystringoptional

Product logo S3 key

nullable

imageFileIdsuuid[]optional

Image file IDs (resolved via /api/v1/files/{fileId}/download-url). SSoT for the cluster gallery — Index 0 is the main image. Articles may override per-variant via article.imageFileIds (see ADR 0094a).

Default: []

attachmentFileIdsuuid[]optional

Loose non-image attachments — primary source for the customer-portal Downloads tab. Variant-specific attachments live on article.attachmentFileIds and appear in a separate section. For richer metadata (category, visibility, version) use the documents field instead. See ADR 0094a.

Default: []

tagsstring[]optional

Tags for categorization

Default: []

isActivebooleanoptional

Whether this product is active

Default: true

sortOrderintegeroptional

Display sort order

≥ 0Default: 0

internalNotestringoptional

Internal note (not visible to customers)

max 4000 Zeichennullable

matchingKeywordsstring[]optional

Keywords for AI-based article-to-product matching (e.g. "m365", "office 365")

Default: []

articleCountintegeroptional

Number of articles assigned to this product (cached)

≥ 0Default: 0read-only

priceRangeobjectoptional

Price range across assigned articles (cached)

read-onlynullable

minstringoptional

Lowest article price

Pattern

maxstringoptional

Highest article price

Pattern

infoPagesobject[]optional

Product info pages with rich content for proposals and customer portal

Default: []

iduuiderforderlich

titlestringerforderlich

1–300 Zeichen

slugstringoptional

max 200 Zeichennullable

contentHtmlstringoptional

nullable

sortOrderintegeroptional

≥ 0Default: 0

isPublishedbooleanoptional

Default: false

featuresobject[]optional

Lieferumfang positions: what is included in the product delivery

Default: []

namestringerforderlich

1–200 Zeichen

descriptionstringoptional

max 500 Zeichennullable

iconstringoptional

max 100 Zeichennullable

includedbooleanoptional

Default: true

qtyintegeroptional

Quantity per delivery (e.g. "2 × Akku") — null means unspecified

1 – 999nullable

documentsobject[]optional

Datasheets, manuals, certificates etc. — reference files via fileId. SSoT for cluster-wide structured documents shown in the customer-portal Downloads tab. Richer per-file metadata than attachmentFileIds (category, visibility, version, download counter). Variant-specific files belong on article.attachmentFileIds. See ADR 0094a.

Default: []

iduuiderforderlich

fileIduuiderforderlich

titlestringerforderlich

1–300 Zeichen

categorystringoptional

Werte

datasheetmanualsafetycertificatemarketingother

Default: "other"

visibilitystringoptional

Werte

internalcustomers

Default: "customers"

versionstringoptional

max 50 Zeichenread-onlynullable

languagestringoptional

max 10 ZeichenDefault: "de"

sizeBytesintegeroptional

≥ 0nullable

mimeTypestringoptional

max 200 Zeichennullable

downloadsintegeroptional

≥ 0Default: 0

uploadedBystringoptional

max 200 Zeichennullable

uploadedAtdatetimeoptional

nullable

technicalSpecsobject[]optional

Technical specifications organized by group (e.g. "Performance" → "RAM" / "16 GB"). SSoT for the cluster — variant-specific values belong in article.attributes. See ADR 0094a.

Default: []

groupstringerforderlich

1–100 Zeichen

keystringerforderlich

1–100 Zeichen

valuestringerforderlich

max 500 Zeichen

pricingCalculatorConfigobjectoptional

Pricing calculator configuration

nullable

enabledbooleanoptional

Default: false

basisPricestringoptional

Listenpreis (Basis) for the calculator KPI strip

Patternnullable

marginnumberoptional

Marge in percent (0–100) — informational only, not applied to formula

0 – 100nullable

discountTiersobject[]optional

Volume discount tiers — quantity-band × multiplicative factor

Default: []

fromintegererforderlich

Minimum quantity (inclusive)

≥ 1

tointegeroptional

Maximum quantity (inclusive); null means open-ended

≥ 1nullable

factornumbererforderlich

Multiplier on basisPrice (e.g. 0.95 for 5% volume discount)

0 – 2

labelstringoptional

max 200 Zeichennullable

surchargesobject[]optional

Additive surcharges (express, weekend, on-site) — percent or absolute

Default: []

titlestringerforderlich

1–200 Zeichen

kindstringerforderlich

Werte

PERCENTABSOLUTE

valuenumbererforderlich

formulastringoptional

Pricing formula expression (e.g. "basePrice * users")

max 500 Zeichennullable

variablesobject[]optional

Variables for the pricing calculator (legacy formula model)

Default: []

keystringerforderlich

max 50 Zeichen

labelstringerforderlich

max 200 Zeichen

typestringerforderlich

Werte

numberselect

defaultValuestringoptional

nullable

minnumberoptional

nullable

maxnumberoptional

nullable

optionsobject[]optional

nullable

labelstringoptional

valuestringoptional

tiersobject[]optional

Volume pricing tiers (legacy — see discountTiers for the simpler factor-based model)

Default: []

minQuantityintegererforderlich

≥ 0

pricePerUnitstringerforderlich

Pattern

labelstringoptional

max 200 Zeichennullable

mediaobject[]optional

Product media gallery (images, videos, documents, brochures)

Default: []

idstringerforderlich

typestringerforderlich

Werte

IMAGEVIDEODOCUMENTBROCHURE

titlestringerforderlich

max 300 Zeichen

urlstringoptional

Default: nullnullable

s3Keystringoptional

Default: nullnullable

mimeTypestringoptional

Default: nullnullable

thumbnailS3Keystringoptional

Default: nullnullable

sortOrderintegeroptional

≥ 0Default: 0

isPublishedbooleanoptional

Default: false

demoConfigobjectoptional

Demo booking configuration

Default: nullnullable

testimonialsobject[]optional

Customer testimonials / case studies

Default: []

idstringerforderlich

quotestringerforderlich

max 2000 Zeichen

authorNamestringerforderlich

max 200 Zeichen

authorTitlestringoptional

max 200 ZeichenDefault: nullnullable

authorCompanystringoptional

max 200 ZeichenDefault: nullnullable

logoS3Keystringoptional

Default: nullnullable

sortOrderintegeroptional

≥ 0Default: 0

Standard-Endpoints

Diese Resource folgt dem generischen CRUD-Vertrag der Plattform. Lesen Sie die Konventionen für Pagination, Idempotenz, Optimistic Locking und Audit. Die wichtigsten Endpoints:

GET /api/v1/products — Liste, paginiert + filterbar
GET /api/v1/products/<id> — Einzelne Entity
POST /api/v1/products — Anlegen
PATCH /api/v1/products/<id> — Teil-Update
DELETE /api/v1/products/<id> — Soft-Delete
GET /api/v1/products/<id>/timeline — Audit + Aktivitäten