# MES.Pack – Lieferanten-Artikelschnittstelle v1

Stand: 24.09.2026. Diese Beschreibung gilt für den implementierten Dateiimport von Lieferantenartikeln.

## 1. Übertragungswege und Zuständigkeit

Unterstützt werden CSV (UTF-8, mit oder ohne BOM) und Excel XLSX. Ein berechtigter Benutzer lädt die Datei unter Lieferanten → Artikel / Upload hoch, prüft die Vorschau und bestätigt die Übernahme. Mandanten verwalten ihren eigenen Katalog; Systemadministratoren können gemeinsame Lieferantenkataloge pflegen. Die Vorschau ist 20 Minuten gültig und an Benutzer und Mandant gebunden. Ein Neustart kann eine erneute Vorschau erforderlich machen.

REST API, SOAP, EDI, SFTP und OCI/Punchout können als Lieferantenfähigkeiten dokumentiert werden. Es gibt derzeit **keine freigegebene externe Maschinen-API** für Artikelimporte, keine API-Schlüssel für diesen Zweck und keinen automatischen Abruf. Die internen Browser-Formularrouten sind keine stabile Integrations-API. Für einen automatischen Adapter sind mit dem Lieferanten Format, Authentifizierung, Datenumfang, Abrufrhythmus, Fehlerbehandlung und Testdaten zu vereinbaren. Zugangsdaten nicht in Artikellisten oder Freitextfeldern speichern.

## 2. Dateiaufbau

- Höchstens 5.000.000 Bytes und 500 Artikel pro Upload.
- Erste Zeile: genau die sieben unten genannten Spalten, jeweils einmal. Die Reihenfolge ist frei; die Groß-/Kleinschreibung der Spaltennamen ist unerheblich.
- CSV: Semikolon, Komma oder Tabulator. Die Erkennung erfolgt anhand der Kopfzeile. Felder bei Bedarf mit doppelten Anführungszeichen umschließen; enthaltene Anführungszeichen verdoppeln. Jede Datenzeile hat dieselbe Spaltenanzahl wie die Kopfzeile.
- XLSX: erstes Arbeitsblatt, sieben Spalten A–G. Formeln werden abgewiesen; vorher als Werte speichern. Alte XLS-Dateien müssen vorher in XLSX umgewandelt werden. Keine zusätzlichen Titelzeilen oder anderen Tabellen auf dem ersten Blatt. Komprimierte Excel-Dateien dürfen insgesamt höchstens 30 MB entpackten Inhalt enthalten.
- Artikelnummern als Text formatieren, um führende Nullen zu bewahren.
- Dezimalzahlen ohne Tausendertrennzeichen, Einheitensuffix oder Exponentialschreibweise. Dezimalpunkt oder Dezimalkomma ist möglich; bei Komma als CSV-Trennzeichen muss ein Dezimalkomma im Feld korrekt zitiert werden. Empfohlen: Semikolon und Dezimalpunkt.
- Texte werden an Anfang und Ende getrimmt.

## 3. Felder

| Spalte | Pflichtwert | Format und Bedeutung |
|---|---|---|
| Number | Ja | Lieferantenartikelnummer, 1–100 Zeichen. Eindeutig innerhalb des jeweiligen Lieferantenkatalogs. |
| Name | Ja | Artikelbezeichnung, 1–160 Zeichen. |
| Unit | Ja | Einer der Werte: Piece, Gram, Kilogram, Metre, SquareMetre, CubicMetre. Keine Zahlencodes. |
| GramsPerUnit | Nein | Gramm pro Basiseinheit, größer als 0 bis 999999999, höchstens 6 Nachkommastellen. Bei Gram gilt immer 1, bei Kilogram immer 1000; abweichende Werte werden abgewiesen. |
| RollLengthMetres | Nein | Nennlänge einer vollen Rolle in Metern, größer als 0 bis 999999999, höchstens 3 Nachkommastellen. Nur bei Unit=Metre zulässig. |
| ProductUrl | Nein | Absolute HTTPS-Produktadresse, höchstens 1000 Zeichen, keine Zugangsdaten im URL-Benutzerteil. |
| DocumentUrl | Nein | Absolute HTTPS-Adresse eines Datenblatts oder Zertifikats, höchstens 1000 Zeichen, keine Zugangsdaten im URL-Benutzerteil. |

Alle sieben Spalten müssen vorhanden sein. Optionale Werte können leer sein. Preise, Bestellmengen, Lagerstände, Materialzusammensetzungen, Bilder und Dokumentdateien werden mit dieser Version nicht importiert.

Einheiten: Piece = Stück, Gram = Gramm, Kilogram = Kilogramm, Metre = Meter, SquareMetre = Quadratmeter, CubicMetre = Kubikmeter. Beispiel: 4.5 bei Metre bedeutet 4,5 Gramm pro Meter, nicht das Gewicht einer ganzen Rolle.

## 4. Beispiel

```csv
Number;Name;Unit;GramsPerUnit;RollLengthMetres;ProductUrl;DocumentUrl
000123;Stretchfolie 100 m;Metre;4.5;100;;
KARTON-200;Faltkarton 200 mm;Piece;220;;;
```

## 5. Identität, Aktualisierung und Dokumentation

Der logische Schlüssel besteht aus Mandant bzw. Systembereich, Lieferant und Artikelnummer. Artikelnummern nicht nur durch Groß-/Kleinschreibung unterscheiden. Doppelte Nummern innerhalb einer Datei werden abgewiesen. Bei einer anderen Produktidentität oder einer neuen Artikelnummer muss ein neuer Artikel angelegt werden; alte Nummern nicht für andere Produkte wiederverwenden.

- Eine neue Nummer legt einen neuen, aktiven Katalogartikel mit Version 1 an.
- Geänderte Angaben zu einer vorhandenen Nummer erzeugen eine neue, unveränderlich gespeicherte Version. Die frühere Version bleibt vollständig erhalten.
- Identische Daten erzeugen keine zusätzliche Artikelversion.
- Ein leerer optionaler Wert leert das Feld in der **neuen** Version. Er bedeutet nicht „alten Wert beibehalten“. Die alte Version bewahrt den früheren Wert.
- Ein nicht mehr in der Datei enthaltener Artikel wird weder gelöscht noch automatisch archiviert. Auch eine als vollständig bezeichnete Lieferantenliste löst keine Löschung aus.
- Nicht mehr angebotene Artikel werden in der Oberfläche ausdrücklich archiviert. Artikel und Historie bleiben sichtbar; neue Materialübernahmen aus archivierten Artikeln sind gesperrt.
- Ein Upload reaktiviert archivierte Artikel nicht. Die Reaktivierung erfolgt ausdrücklich in der Oberfläche und wird ebenfalls versioniert.
- Bereits angelegte Verpackungsmaterialien und Packdokumentationen werden durch Katalog-Updates nicht verändert. Neue Materialübernahmen verweisen auf ihre ursprüngliche Katalogversion. Spätere Anpassungen am Material sind eigene Bearbeitungen.
- Die Artikelhistorie und die Quellenverweise sind Bestandteil des Mandantenexports.

Bei Einführung der Versionierung wird der zu diesem Zeitpunkt vorhandene Katalogstand als Ausgangsversion gesichert. Bereits davor überschriebene Katalogstände können daraus nicht rekonstruiert werden. Frühere Materialien erhalten keinen nachträglich geratenen Versionsverweis.

Die Historie speichert Artikelangaben und die damaligen URL-Texte. Externe Seiten und Dokumente können sich unabhängig davon ändern. Für dauerhafte Nachweise müssen erforderliche Dokumentdateien zusätzlich am Material gespeichert werden; dieser Dateiimport lädt keine verlinkten Dateien herunter.

## 6. Prüfung und Fehlerverhalten

Ungültige Dateistruktur, unbekannte Einheiten, doppelte Nummern, nicht zulässige Zahlen oder URLs führen zur Ablehnung der Vorschau. Es findet keine teilweise Übernahme einer fehlerhaften Datei statt. Die Bestätigung speichert den Import in einer Datenbanktransaktion. Wurde der Lieferant oder Katalog nach der Vorschau geändert, muss die Datei erneut geprüft werden. Eine bereits verarbeitete oder abgelaufene Vorschau kann nicht erneut verwendet werden; ein erneuter Datei-Upload ist möglich.

Die Vorschau unterscheidet neue Nummern von vorhandenen Nummern. Vorhandene Nummern können unverändert sein; eine neue Artikelversion entsteht nur bei tatsächlicher Änderung. Nicht enthaltene Artikel und bestehende Materialdaten sind von der Aktualisierung ausgenommen.

## 7. Vorbereitung einer automatischen Anbindung

Für die Abstimmung bitte bereitstellen: Ansprechpartner, Test- und Produktionsadresse, Schnittstellenart, technische Dokumentation, Authentifizierungsverfahren, Beispieldaten, stabile Artikelnummern, Einheiten, Datenstand, Kennzeichnung abgekündigter Artikel sowie Angaben zu Abrufgrenzen und Fehlerantworten. Zugangsdaten werden erst über einen gesondert vereinbarten sicheren Einrichtungsweg übernommen.

Die Regeln zum Erhalt alter Artikel und Versionen gelten auch als Vorgabe für künftige Adapter. Die konkrete Maschinen-API wird separat beschrieben und versioniert, sobald sie implementiert ist.