PPWR: Verpackungsdaten, Mengen, Mengenmeldung

​

Übersicht

​

Berechtigungen

​

Stammdaten-Intake

​

Endpunkte und Abgleichschlüssel

​

Anfrageformat

{
  "rows": [ { "…": "…" } ],
  "overwrite": false
}

​

Spaltenpolitik: standardmäßig nur befüllen

• Eine leere oder weggelassene optionale Zelle ändert nichts — sie löscht nie einen gespeicherten Wert.
• Pflichtspalten sind auf jeder Zeile nötig, auch auf einer Zeile, die nur einen bestehenden Datensatz aktualisiert: auf Einheiten-Zeilen name, packagingType, role und notes, auf Komponenten-Zeilen code, name und materials. Eine Zeile ohne sie landet in invalid. Ihre Werte werden wie jede andere Zelle mit den gespeicherten verglichen: Ein abweichender name aus Ihrem ERP ist eine Überschreibung.
• Eine Zelle, die ein bisher leeres Feld befüllt, wird automatisch übernommen.
• Eine Zelle, die einen vorhandenen Wert überschreiben würde (auch lieferanten- oder KI-attestierte regulatorische Werte), verlangt overwrite: true. Ohne dieses Flag wird ein Stapel, der eine solche Änderung enthält, mit 409 abgelehnt und es wird nichts geschrieben:
  { "error": "overwriteRequired", "confirmUpdateCount": 3 }
  
  Senden Sie den Stapel erneut mit overwrite: true oder entfernen Sie die betroffenen Zeilen.
• Ein ausdrückliches „nein” schaltet ein Ja/Nein-Merkmal aus. Bei contactSensitive und foodContact (Komponenten) sowie placedUnderOwnBrand, modifiesConformity und reusable (Verpackungseinheiten) behält eine leere Zelle den gespeicherten Wert; false (oder "no") auf einem gespeicherten true ist eine Überschreibung und verlangt overwrite: true.
• Feldübergreifende Regeln prüfen die wirksamen Merkmale. Nennt eine Zeile ein Ja/Nein-Merkmal oder einen PFAS-Wert, zählt die Zelle der Zeile und, wo sie leer ist, der gespeicherte Wert. Eine Zeile mit PFAS-Werten für eine Komponente, die bereits als Lebensmittelkontakt gespeichert ist, wird angenommen. Schaltet eine Zeile ein gespeichertes foodContact aus, werden die gespeicherten PFAS-Daten mitgeprüft: foodContactOffWithPfasData, oder pfasOnlyFoodContact, wenn die Zeile selbst PFAS-Werte enthält.
• Herkunfts- und Dokumentspalten (zuletzt liefernder Lieferant, Zeitstempel, Verweise auf Dokumente) sind über diese API niemals beschreibbar.

​

Lieferanten

• Beim Anlegen erzeugt ein Name, der keinen Ihrer Lieferanten trifft, einen neuen Lieferanten mit diesem Namen (ohne E-Mail, ohne Land, als PPWR-relevant markiert), und der neue Datensatz wird ihm zugeordnet. Das Ergebnis nennt die neuen Namen in suppliersCreated. Prüfen Sie die Schreibweise vor dem Senden: Ein Tippfehler legt einen zweiten Lieferanten an.
• Ein Name, der zwei oder mehr Ihrer Lieferanten trifft, lässt die Zeile mit ambiguousSupplierName scheitern.
• Bei einer bestehenden Komponente oder Verpackungseinheit wird supplierName ignoriert — der Lieferant wird beim Anlegen festgelegt und vom Intake nie geändert.
• Komponenten werden über code im Katalog des genannten Lieferanten gesucht, sonst in Ihrem eigenen. Innerhalb einer Anfrage werden sie allein nach code zusammengefasst: Zwei Zeilen mit demselben code, aber verschiedenen Lieferanten, sind ein Schlüssel, und die zweite scheitert mit duplicateInFile.
• Eine Zeile, deren supplierName noch keinen Lieferanten trifft, für einen code, den es bisher nur bei einem anderen Lieferanten gibt, scheitert mit ambiguousComponentMatch — und für sie wird kein Lieferant angelegt.

​

Einheiten: die Referenz-Falle

​

Größen einer Einheit

{
  "rows": [
    {
      "name": "Teefilter-Faltschachtel", "internalRef": "U-1",
      "packagingType": "sales", "role": "manufacturer",
      "notes": "Faltschachtel für Teefilter",
      "gtin": "4012345678901", "widthMm": 100, "heightMm": 150, "depthMm": 40,
      "sizes": [
        { "reference": "U-1-500", "label": "500 g", "gtin": "4012345678918", "widthMm": 120 },
        { "reference": "U-1-1KG", "label": "1 kg" }
      ]
    }
  ]
}

• Beim Anlegen bricht eine Größe, deren reference schon von einer anderen Verpackungseinheit oder Größe belegt ist, oder die die Einheit über 50 Größen bringen würde, die ganze Zeile ab: Die Verpackungseinheit entsteht nicht, und die Zeile scheitert mit duplicateFormatReference bzw. formatCapReached. Eine Größe, die schon innerhalb der Anfrage abgewiesen wird — dieselbe reference zweimal in einer Einheit (duplicateFormatReference) oder ein conflictingSizeRow —, scheitert allein, und die Verpackungseinheit wird ohne sie angelegt.
• Trifft die Zeile eine bestehende Verpackungseinheit, wird jede Größe für sich aktualisiert; eine abgewiesene Größe scheitert allein. Größen, die die Anfrage nicht nennt, werden nie gelöscht. Ein hier geänderter Größenwert zählt als Überschreibung und verlangt overwrite: true.
• Dieselbe Gruppierung geht auch flach: mehrere Zeilen mit derselben internalRef, jede mit eigener sizeReference. So deklariert das CSV-Blatt seine Größen — eine Zelle kann kein Array tragen. Beide Schreibweisen dürfen sich in einer Anfrage mischen.
• POST /api/v1/ppwr/formats schreibt Größen als eigener Endpunkt, für Aufrufer, die Größen bereits getrennt versenden (siehe unten).

​

Größen und Verknüpfungen: keine Bestätigung

• POST /api/v1/ppwr/links legt eine Verknüpfung zwischen Verpackungseinheit und Komponente an. Eine bestehende Verknüpfung ändert er nie: Eine abweichende quantity oder ein massGrams ohne formatReference auf einer schon vorhandenen Verknüpfung wird ignoriert, und die Zeile kommt als skipped zurück. Ändern Sie diese Werte in der App.
• Eine links-Zeile mit formatReference setzt die Masse der Komponente für diese Größe immer auf das massGrams der Zeile, auch wenn die Verknüpfung schon besteht (die Zeile kommt trotzdem als skipped zurück). Ein leeres massGrams behält dort die gespeicherte Masse dieser Größe.
• POST /api/v1/ppwr/article-links legt eine Verknüpfung zwischen Verpackungseinheit und Artikel an; eine bestehende ist skipped.

​

Limits

​

Ergebnis

{
  "imported": 2,
  "updated": ["K-3"],
  "skipped": ["K-4"],
  "failed": [{ "identifier": "K-5", "error": "ambiguousComponentMatch" }],
  "invalid": [{ "index": 7, "identifier": "K-6", "error": "materialsRequired" }],
  "suppliersCreated": []
}

• invalid enthält Zeilen, die das Zeilenschema abgelehnt hat, bevor etwas geschrieben wurde; index ist die Position der Zeile in der Anfrage (ab 0). failed enthält Zeilen, die die Engine abgelehnt hat.
• Teil-Akzeptanz: Gültige Zeilen werden übernommen, auch wenn andere in invalid oder failed landen. Einzige Ausnahme ist die 409-Überschreibungssperre — die gilt für den ganzen Stapel.
• Idempotenz: Eine identische Anfrage erneut zu senden ändert nichts; getroffene Zeilen kommen als skipped zurück. Ausnahme sind Einheiten-Zeilen ohne internalRef (siehe oben).
• failed enthält auch neue Verpackungseinheiten, die abgelehnt wurden, weil das Verpackungseinheiten-Kontingent Ihres Tarifs erreicht ist, mit packagingUnitQuotaReached (ihre Größen ebenso). Eine abgelehnte Einheit legt nichts an, auch nicht ihren Lieferanten.

​

Fehlerschlüssel

​

Stammdaten zurücklesen

• Der Weg vom Schlüssel zur ID. ?internalRef=U-1 bzw. ?code=K-1 löst den Abgleichschlüssel des Intakes auf die Zeile auf — so kommen Sie an die id, die die Detail-Endpunkte erwarten. Ein leerer Wert ist kein Filter, der nichts trifft, sondern gar kein Filter.
• code trifft eine Menge, keine Zeile. Ein Komponenten-Code ist je Lieferant eindeutig: Derselbe Code kann einmal in Ihrem eigenen Katalog und einmal bei einem antwortenden Lieferanten liegen. ?supplierId=<uuid> grenzt darauf ein, ?supplierId=none auf Ihren eigenen Katalog. Ein anderer Wert trifft nichts, statt die Menge zu erweitern.
• Paging ist begrenzt. Ohne limit kommen die ersten 100 Zeilen (limit max. 1000); blättern Sie mit offset, bis eine Seite kürzer ist. Die Sortierung ist stabil (Verpackungseinheiten nach Name, Komponenten natürlich nach Code, jeweils mit der id als Gleichstand-Kriterium), Seitengrenzen wiederholen oder überspringen also keine Zeile. Ein ungültiger Wert ist ein 400.
• Gelöschtes bleibt draußen, und eine fremde, unbekannte oder syntaktisch falsche ID ist immer 404 — nie 403, das würde die Existenz einer fremden ID bestätigen.

​

Dokumente hochladen

​

Warum zwei Schritte

1. Upload-URL anfordern — mit Dateiname, MIME-Typ und Größe.
2. Die Datei per PUT an diese URL senden, mit demselben Content-Type, innerhalb von 10 Minuten.
3. Den zurückgegebenen s3Key als storageKey an POST /api/v1/ppwr/documents übergeben.

​

Das Ziel: eine UUID, kein Schlüssel

​

Beispiel

# 1. Upload-URL anfordern
curl -X POST "https://app.polygon-one.com/api/v1/ppwr/documents/upload-url" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "fileName": "DoC-U-1.pdf", "contentType": "application/pdf", "fileSize": 482113 }'
# → 200 { "uploadUrl": "https://…", "s3Key": "pending/operator/…/…-DoC-U-1.pdf" }

# 2. Datei hochladen (gleicher Content-Type, innerhalb von 10 Minuten)
curl -X PUT "<UPLOAD_URL>" \
  -H "Content-Type: application/pdf" \
  --data-binary @DoC-U-1.pdf

# 3. An die Verpackungseinheit hängen
curl -X POST "https://app.polygon-one.com/api/v1/ppwr/documents" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "declaration_of_conformity",
    "storageKey": "<S3_KEY>",
    "fileName": "DoC-U-1.pdf",
    "target": { "packagingSpecId": "<UNIT_ID>" }
  }'
# → 201 { "id": "3b7e…", "extractionQueued": true }

​

Dokumenttypen

​

KI-Auswertung: extractionQueued und aiSkippedReason

• extractionQueued: true — die Auswertung ist eingereiht; Vorschläge erscheinen danach in der Prüfansicht der App.
• extractionQueued: false mit aiSkippedReason — die Auswertung wurde nicht eingereiht: disabled (KI-Zusatzmodul nicht aktiv), quota bzw. spend (ein Monatslimit ist erreicht) oder enqueue (das Einreihen ist fehlgeschlagen — das Dokument ist gespeichert, stoßen Sie die Analyse in der App erneut an).

​

Duplikate und Wiederholungen

{ "error": "duplicate", "existing": { "id": "9a1b…", "fileName": "DoC-U-1.pdf", "anchor": { "kind": "unit", "ref": "U-1", "name": "Teefilter-Faltschachtel" } } }

​

Fehler

​

Nicht unterstützt

• Dokumente an Mehrwegsystemen (Pool-Dokumente) — nur in der App.
• Adressierung über internalRef oder code — nur über die UUID.
• Upload in einem einzigen Aufruf (Multipart) — wegen der Größengrenze der Plattform, siehe Warum zwei Schritte.
• Antworten von Lieferanten — die kommen über das Lieferantenportal, nicht über diesen Endpunkt.

​

Konformitätserklärungen lesen

​

GET /api/v1/ppwr/units?include=doc

• docState — derselbe Wert, den die Einheitentabelle der App zeigt:

  docState	Bedeutung
  issued	Eine verifizierte DoC liegt vor und ist aktuell
  outdated	Eine DoC liegt vor, aber die Daten der Verpackungseinheit haben sich seit der Unterzeichnung geändert — neu ausstellen
  in_review	Eine gesammelte DoC liegt vor, ist aber noch nicht verifiziert, oder ihre Datei fehlt
  ready	Noch keine DoC; alle Daten für die Ausstellung sind vorhanden
  blocked	Noch keine DoC; für die Ausstellung fehlen Daten
  collect	Noch keine DoC; als Importeur oder Händler holen Sie die DoC des Herstellers ein
  not_applicable	Für diese Verpackungseinheit ist keine DoC nötig

• activeDeclaration — die aktive Erklärung der Verpackungseinheit, oder null:

{
  "id": "d1e2…", "version": 2, "status": "issued", "origin": "generated",
  "referenceNumber": "DoC-PU-17-v2", "issuedAt": "2026-09-30T10:12:00.000Z",
  "withdrawnAt": null, "supersedesId": "c0ff…", "verified": true, "isFallback": false,
  "pdfUrl": "/api/v1/ppwr/declarations/d1e2…/pdf"
}

​

Erklärungen auflisten und abrufen

​

PDF herunterladen

• Eine erzeugte DoC wird aus dem bei der Unterzeichnung eingefrorenen Snapshot gerendert, nach erneuter Prüfung seines Hashs. lang wählt die Sprache: genau einer der Werte de en fr es it nl bg cs da el et fi hr hu lt lv pl pt ro sk sl sv, ohne Rücksicht auf Groß-/Kleinschreibung (EN = en). Jeder andere Wert — ga, ein Tippfehler — ist ein 400, der die unterstützten Werte nennt. Ohne lang (oder mit leerem Wert) kommt Deutsch.
• lang=all liefert ein ZIP mit einem PDF je Sprache, die die Märkte der Verpackungseinheit verlangen (Art. 39 Abs. 2), ohne Irisch und Maltesisch. Bei einer Familien-DoC kommen die Sprachen von einem aktiven Mitglied (dem mit der kleinsten ID). Eine zurückgezogene oder abgelöste DoC hat kein aktives Mitglied; ihr ZIP enthält nur das deutsche PDF.
• Eine gesammelte DoC ist die hochgeladene Datei des Herstellers, unverändert, als PDF, PNG oder JPEG mit passendem Content-Type (lang gilt dort nicht). Wurde diese Datei gelöscht, lautet die Antwort 404, obwohl pdfUrl gesetzt ist.

​

ERP-Rezept — die DoC in den Artikelstamm zurückschreiben

• Fragen Sie GET /api/v1/ppwr/declarations?changedSince=<letzter Lauf> ab (ohne status-Filter).
• Speichern Sie bei jeder issued-Zeile mit verified: true deren referenceNumber und die Datei aus pdfUrl an jeder Verpackungseinheit in activeSpecIds und überschreiben Sie, was diese Einheit bisher hatte. So wird auch eine abgelöste DoC ersetzt: Ihre Nachfolgerin taucht in der Abfrage auf, die abgelöste ebenfalls (übergehen Sie sie). Verwenden Sie hier nicht specIds — dort stehen auch Einheiten, die eine neuere DoC übernommen hat.
• Eine Zeile mit verified: false liegt nicht vor (eine gesammelte DoC, noch nicht verifiziert, oder ihre Datei ist abgelaufen): Entfernen Sie, was Sie zu dieser Erklärung gespeichert haben.
• Bei withdrawn entfernen Sie, was Sie zu dieser Erklärung gespeichert haben, an jeder Verpackungseinheit in specIds.
• Abgleichen Sie ab und zu mit GET /api/v1/ppwr/units?include=doc: issued heißt, eine verifizierte DoC liegt vor und ist aktuell; outdated und in_review brauchen Arbeit in der App; ready, blocked und collect haben noch keine DoC; not_applicable braucht keine.

​

Mengen-Feed & Tonnage

​

Mengen je SKU, Markt und Jahr

{
  "rows": [
    { "articleNumber": "SKU-1", "periodYear": 2026, "market": "DE", "quantity": 125000 },
    { "articleNumber": "SKU-1", "periodYear": 2026, "market": "FR", "quantity": 31000 }
  ],
  "replaceScope": "period-market"
}

• Jede quantity ist die absolute Gesamtmenge für diese SKU, diesen Markt und dieses Jahr und ersetzt den gespeicherten Wert — sie wird nie dazuaddiert. Senden Sie niemals Zuwächse, Retouren oder Gutschriften als eigene Zeilen: Eine Gutschrift-Zeile würde die Jahresmenge durch den Gutschriftbetrag ersetzen. Verrechnen Sie sie in der Gesamtmenge und senden Sie die korrigierte Gesamtmenge; eine Periode erneut zu senden ist der normale Weg, sie zu korrigieren. Eine quantity muss ≥ 0 sein.
• Eine unbekannte articleNumber ist ein Zeilenfehler (unknownArticleNumber), niemals ein erfundener Artikel; ein innerhalb eines Stapels wiederholter Schlüssel wird beim ersten Vorkommen übernommen, die späteren Zeilen melden duplicateInFile.
• Ein Artikel, der existiert, aber mit keiner Verpackungseinheit verknüpft ist, wird angenommen und in imported/updated gezählt, landet aber bei keiner Verpackungseinheit und in keinem Bericht. Nichts im Ergebnis weist darauf hin — prüfen Sie die SKU-Verknüpfungen, bevor Sie den Summen trauen.
• replaceScope: "period-market" erklärt den Stapel zum vollständigen Stand jeder (periodYear, market)-Kombination, die er enthält: Gespeicherte Zeilen genau dieser Kombinationen, die der Stapel nicht enthält, werden gelöscht. Es zählen nur Kombinationen aus Zeilen, deren Artikelnummer gefunden wurde. Eine Kombination, die der Stapel gar nicht enthält, bleibt unberührt — ein Markt, in dem Sie nicht mehr verkaufen, behält seine alten Zeilen; um ihn auf null zu setzen, senden Sie seine SKUs mit quantity: 0. Ohne replaceScope darf ein Stapel SKUs weglassen, die sich nicht geändert haben. Senden Sie replaceScope nur als "period-market", sonst lassen Sie es weg.
• Mengen je Verpackungseinheit werden abgeleitet, nicht gesendet. Die in Verkehr gebrachte Menge einer Verpackungseinheit ist die Summe der Mengen ihrer verknüpften SKUs. Eine Verpackungseinheit, die alle verknüpften Mengen verliert, zählt keinen Feed-Wert mehr.

​

Tonnage je Materialart

{
  "written": [{ "periodYear": 2026, "market": "DE", "zsvrCategory": "50000" }],
  "skipped": [{ "periodYear": 2026, "market": "DE", "zsvrCategory": "40000", "reason": "manualOverridePresent" }],
  "failed": [],
  "invalid": []
}

​

Mengenmeldung-Berichte

​

Register und Märkte

​

Bericht erzeugen

{
  "periodYear": 2026,
  "market": "DE",
  "format": "lucid_de",
  "reportType": "HJM1",
  "systemOperatorId": "DE1234567890123"
}

• reportType ist für lucid_de Pflicht. systemOperatorId ist für lucid_de Pflicht, außer in der App ist eine gültige SystemOperatorID hinterlegt: Fehlt sie dann in der Anfrage, gilt die hinterlegte, und ein gesendeter Wert hat Vorrang. Der 201 nennt die verwendete systemOperatorId. Die Übertragungshilfe-Register verwenden sie nicht (diese erzeugen immer den Jahresbericht); eine fehlerhafte systemOperatorId ist dort trotzdem ein 400.
• reportType ist die LUCID-Meldeart: HPM1 (Planmengenmeldung), HMM1 (unterjährige Mengenmeldung), HJM1 (Jahresabschlussmengenmeldung), HNM1 (Ergänzungsmengenmeldung), HAM1 (Abzugsmengenmeldung).
• systemOperatorId ist die LUCID-Nummer Ihres dualen Systems: zwei Buchstaben und 13 Ziffern (Kleinschreibung wird angenommen und hochgesetzt).
• market ist ISO-Alpha-2 (Groß-/Kleinschreibung egal), periodYear das Kalenderjahr (2000–2100).

{
  "error": "blocking_errors",
  "blockingErrors": [
    { "kind": "missing_mass", "specRef": "U-1", "componentCode": "K-1", "componentName": "Faltschachtel", "material": null, "familyLabelsDe": null }
  ]
}

​

Berichte auflisten

[
  {
    "id": "3f0e…",
    "periodYear": 2026,
    "market": "DE",
    "format": "lucid_de",
    "reportType": "HJM1",
    "systemOperatorId": "DE1234567890123",
    "xsdVersion": "…",
    "status": "generated",
    "version": 2,
    "supersedesId": "9a1b…",
    "snapshotHash": "…",
    "generatedAt": "2026-08-17T09:30:00.000Z"
  }
]

​

Datei herunterladen

• 403 — { "error": "…", "code": "EXPORTS_BLOCKED" }, wenn Exporte für Ihren Arbeitsbereich gesperrt sind, oder das PPWR-Modul ist nicht aktiv.
• 404 — unbekannte oder fehlerhafte Berichts-ID, einschließlich jeder ID eines anderen Unternehmens.
• 409 — { "error": "Report integrity check failed" }: Die Momentaufnahme passt nicht mehr zu ihrem Hash; die Datei wird verweigert statt ausgeliefert.

​

Integrationsrezept ERP zu LUCID