EDM Mehrwegquote REST Schnittstelle v1.0.0
Schnittstellenbeschreibung
Bundesministerium für Klimaschutz, Umwelt, Energie, Mobilität, Innovation und Technologie (BMK)
Stubenbastei 5, 1010 Wien
Inhalt und Zweck der Schnittstellenbeschreibung
Zielgruppe der Schnittstellenbeschreibung
Verwendung der Schnittstellenbeschreibung
Genutzte Standards und Technologien
Dateien und Ordner im Spezifikationspaket
Produktiv- und Test-Umgebungen
Spezifikations-Änderungsverzeichnis
PACK_BEVERAGE_REUSE_WS v1.00 Contact: edm-helpdesk@umweltbundesamt.at Commissioned by the Austrian Federal Ministry of Environment (BMK) Licensed under the EUPL, Version 1.2 or – as soon they will be approved by the European Commission – subsequent versions of the EUPL (the "Licence"); You may not use this work except in compliance with the Licence. You may obtain a copy of the Licence at: http://joinup.ec.europa.eu/software/page/eupl Unless required by applicable law or agreed to in writing, work distributed under the licence is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the Licence for the specific language governing permissions and limitations under the Licence.
Diese Spezifikation verwendet die in Definitionen und Verweise definierten Begriffe und Akronyme und basiert auf den dort aufgeführten technischen Standards und rechtlichen Vorgaben.
Das Ziel dieser Anwendung ist der Ausbau von Mehrwegsystemen für Getränkeverpackungen.
Dafür soll der Anteil der insgesamt in Österreich in Verkehr gesetzten Getränke in Regelgebinden mit Mehrwegverpackungen (=Mehrwegqoute) bis 2025 auf zumindest 25% und bis 2030 auf zumindest 30% zu erhöhen.
Die Applikation zum Ausbau der Mehrwegquote ist gesetzlich im § 14b des AWG 2002 verankert
Die Meldung der Mehrwegquote (kurz MWQ) kann auf verschiedene Arten eingebracht werden, eine davon ist mittels REST Schnittstelle.
Dieses Dokument beschreibt die REST Schnittstelle der Anwendung Mehrwegquote.
Es wird in zwei Meldevarianten unterschieden: Angebotsseitig und Absatzseitig. Für beide Meldevarianten ein JSON über die REST Schnittstelle übermittelt, jedoch gibt es jeweils unterschiedliche Kriterien, die erfüllt sein müssen, welche im Detail in den späteren Kapitel beschrieben werden.
Das Dokument richtet sich in erster Linie an solche IT-Analytiker und Entwickler, die für die zentrale Stelle mit der Umsetzung der jährlichen Übermittlungen gemäß § 14b Abs. 6 des AWG 2002 an das BMK befasst sind.
Zusätzlich kann das Dokument auch von Umwelt- und Abfallwirtschaft Fachpersonal genutzt werden, um genauen Aufschluss über Art und Struktur der über das Webservice übermittelten Daten zu erlangen.
Die Schnittstellenbeschreibung ist für die Verwendung in Kombination mit den anderen Dateien aus dem Schnittstellenspezifikations-Paket vorgesehen, Siehe Dateien und Ordner im Spezifikationspaket.
Für Auskünfte zur Schnittstelle steht der EDM Helpdesk zur Verfügung. Den EDM Helpdesk erreichen Sie unter der E-Mail-Adresse edm-helpdesk@umweltbundesamt.at.
Das Portal edm.gv.at enthält im öffentlich zugänglichen Bereich unter Helpdesk weitere Informationen zur Kontaktaufnahme mit dem EDM Helpdesk.
[JSON] ECMA-404
Mittels REST Schnittstelle an die Behörde übermittelte Daten müssen im JSON-Format vorliegen.
Beispiel-Request-Meldung-Absatzseitig.json
Beispiel für den Request einer absatzseitigen Meldung, mit zwei Verkaufsstellen.
Beispiel-Request-Meldung-Angebotsseitig.json
Beispiel für den Request einer angebotsseitigen Meldung, mit zwei Verkaufsstellen und jeweils zwei Artikeln.
Beispiel-Response-GetAllReports-Absatzseitig.json
Beispiel für den Response des GET-Requests der alle eingebrachten absatzseitigen Meldungen zurückliefert.
Beispiel-Response-GetAllReports-Angebotsseitig.json
Beispiel für den Response des GET-Requests der alle eingebrachten angebotsseitigen Meldungen zurückliefert.
Beispiel-Response-GetReportById-Absatzseitig.json
Beispiel für den Response des GET-Requests der nach Angabe einer UUID Details zu einer bestimmten Meldung zurückliefert.
Beispiel-Response-GetReportById-Angebotsseitig.json
Beispiel für den Response des GET-Requests der nach Angabe einer UUID Details zu einer bestimmten Meldung zurückliefert.
Beispiel-Response-PostReport-Absatzseitig.json
Beispiel für den Response des POST-Requests der eine Meldung einbringt.
Beispiel-Response-PostReport-Angebotsseitig.json
Beispiel für den Response des POST-Requests der eine Meldung einbringt.
Endpunkte-Absatzseitig.pdf
Gibt eine Übersicht über alle Endpunkte für die absatzseitige Meldevariante.
Endpunkte-Angebotsseitig.pdf
Gibt eine Übersicht über alle Endpunkte für die angebotsseitige Meldevariante.
Produktiv-Umgebung | https://edm.gv.at/mwq |
Benutzertest-Umgebung | https://vprod.umweltbundesamt.at/mwq/ |
Die beiden Umgebungen erfordern jeweils eigene Zugangsdaten bzw. Freischaltungen. Vergleiche dazu auch den Abschnitt Authentifizierung.
Codifizierte Information spielt eine wichtige Rolle in der Informationstechnologie und der automatisierten Informationsverarbeitung.
Ein Beispiel für eine Codeliste ist die ISO 3166-1 Liste der Länder, mit Einträgen wie »AT« für Österreich und »DE« für Deutschland.
Software nutzt Codelisten unter anderem dafür, um die in Datenbanken und EDI-Dateninstanzen enthaltene codifizierte Information für Benutzeroberflächen, Ausdrucke, usw. in „lesbare“ Information zu „übersetzen“, also beispielsweise um anstelle eines eines Länder-Codes »AT« die Landesbezeichnung »Österreich« darzustellen.
Das BMK verwaltet in edm.gv.at die für EDM-Anwendungen und Schnittstellen relevanten Codelisten, und stellt diese öffentlich zur Verfügung. Darunter auch die von der MWQ-Anwendung genutzten Codelisten.
Das BMK veröffentlicht die in edm.gv.at genutzten Codelisten auf zwei Wegen:
Alle der in dieser Spezifikation genutzten Codelisten stehen auf beiden Wegen - Portal und Webservice - zur Verfügung.
Die Codelisten, welche für die MWQ-Anwendung verwendet werden, werden dynamisch verwendet. Das bedeutet, die zu verwendeten Werte sind nicht im XML-Schema festgelegt, sondern werden dynamisch zur Laufzeit während des Uploads validiert.
Dadurch müssen folgende Punkte beachtet werden:
Der XML Upload verwendet folgende Codelisten:
Im Folgenden sind für beide Meldevarianten - absatzseitig und angebotsseitig - die einzelnen Endpunkte mit zugehöriger Beschreibung und dergleichen tabellarisch aufgelistet.
Weitere Details zu Format und Beispieldateien befinden sich im Spezifikationspaket
Methode |
Beschreibung |
Endpunkt |
Request Format |
Request Parameter |
Beispiel Request Parameter |
Response Format |
||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
GET |
Abfrage einer eingebrachten Meldung über eine UUID. |
/sales/{id} |
application/json |
|
aab97b49-26fe-4796-b174-ad52a1e40922 |
application/json |
||||||
GET |
Listet alle eingebrachten absatzseitigen Meldungen auf. |
/sales |
application/json |
|
|
application/json |
||||||
POST |
Einbringen einer absatzseitigen Meldung. |
/sales |
application/json |
application/json |
Methode |
Beschreibung |
Endpunkt |
Request Format |
Request Parameter |
Beispiel Request Parameter |
Response Format |
||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
GET |
Abfrage einer eingebrachten Meldung über eine UUID. |
/offers/{id} |
application/json |
|
aab97b49-26fe-4796-b174-ad52a1e40922 | |||||||
GET |
Listet alle eingebrachten angebotsseitigen Meldungen auf. |
/offers |
application/json |
|
|
application/json |
||||||
POST |
Einbringen einer angebotsseitigen Meldung. |
/offers |
application/json |
application/json |
Die Authentifizierung für die REST Schnittstelle erfolgt über Basic HTTP-Authentifizierung mit Logindaten des EDM-Portals
Die Schnittstelle kann, abhängig von der Art der Meldung wie folgt angesprochen werden
Angebotsseitig: https://edm.gv.at/mwq/api/offers
Absatzseitig: https://edm.gv.at/mwq/api/sales
Wird ein JSON über die REST Schnittstelle übermittelt, finden verschiedene Validierungen statt.
Dies stellt die syntaktische und technische Richtigkeit des JSON sicher.
Ist diese Validierung erfolgreich, gibt es einige Prüfregeln, die das JSON in erster Linie inhaltlich und fachlich überprüfen soll.
Hier wird zwischen Muss- und Soll-Prüfregeln unterschieden.
Muss-Prüfregeln müssen eingehalten werden, damit die Mehrwegquote erfolgreich berechnet und die Meldung eingebracht werden kann.
Soll-Prüfregeln dienen dazu, Benutzer:innen Hinweise zu möglichen Unstimmigkeiten oder Auffälligkeiten zu geben. Bei Verletzungen von Soll-Prüfregeln kann die Mehrwegquote jedoch trotzdem berechnet und die Meldung eingebracht werden.
Prüfregel | Prüfregel-ID | Text im Prüfprotokoll |
---|---|---|
Das Meldejahr muss gültig sein. Das meldende Unternehmen kann frühestens ab dem Jahr 2025 einen Bericht einbringen. Das im Bericht eingetragene Meldejahr darf 2024 nicht unterschreiten, nicht dem aktuellen Jahr entsprechen und nicht in der Zukunft liegen. | 010.010 |
Das Jahr <im Bericht eingetragenes Meldejahr> des Berichtszeitraumes ist ungültig. Die Meldung muss für eines der folgenden Jahre erfolgen: <kommaseparierte Liste gültiger Meldejahre bezogen auf das aktuelle Kalenderjahr>. Bzw. Das Jahr <im Bericht eingetragenes Meldejahr> des Berichtszeitraumes ist ungültig. Für das aktuelle Jahr kann keine Meldung eingebracht werden. |
Die Getränkekategorie muss einem Eintrag in der Reda-Liste 7023 entsprechen. |
020.010 |
Ungültige Getränkekategorie. Betroffene Werte: "<Liste ungültiger Kategorien>". Gültige Werte für REDA Liste 7023 "Liste von Getränkekategorien gemäß § 14b Abfallwirtschaftsgesetz 2002" sind: <Liste gültiger Werte>. Ein Fehler dieser Art tritt <Anzahl Fehler> Mal auf. |
Die Getränkeverpackung muss einem Eintrag in der Reda-Liste 9011 entsprechen. |
020.012 |
Ungültiges Verpackungsmaterial. Betroffene Werte: "<Liste ungültiger Kategorien>". Gültige Werte für REDA Liste 9111 "Liste von Packstoffen und Verbundverpackungs-Arten gemäß § 22 Abs. 4 Z 7 Verpackungsverordnung 2014 idF BGBl. II Nr. 597/2021" sind: <Liste gültiger Werte>. Ein Fehler dieser Art tritt <Anzahl Fehler> Mal auf. |
Die GLN jeder Filiale muss eindeutig sein. | 030.010 |
Angaben für Standort-GLN sind nicht eindeutig und werden für mehr als eine Filiale verwendet. Betroffene GLN Nummern sind: "<Liste betroffener Standort-GLN>". Ein Fehler dieser Art tritt <Anzahl Fehler> Mal auf. |
Das meldende Unternehmen muss mittels gültiger Personen-GLN angegeben werden, welche der Personen-GLN des eingeloggten Benutzers entspricht. |
030.011 | Die Personen-GLN <im Bericht eingetragene Personen-GLN> der Meldung stimmt nicht mit der Personen-GLN <Personen-GLN des eingeloggten Benutzers> des angemeldeten Benutzers überein. |
Die Standort-GLN jeder Filiale muss der Personen-GLN des eingeloggten Benutzers zugehörig sein. |
030.012 | Die Filialen mit folgenden Standort-GLN konnten nicht dem meldenden Betrieb zugeordnet werden: "<betreffende GLN>". |
Der eingeloggte Registrierte muss in seinen Stammdaten Standorte angelegt haben (mindestens einen). |
030.013 | Es wurde keine Standort-GLN für den Betrieb gefunden. |
Zu jeder Standort-GLN, die in der Meldung vorkommt, muss in den Stammdaten eine Adresse angegeben worden sein. Die Angabe eines Grundstücks, ohne Adresse, ist ungültig. |
030.014 | Zur folgenden Standort-GLN liegen keine Adressdaten vor. Bitte tragen Sie diese Daten in ihren Stammdaten ein: "<betreffende GLN>". |
Das meldende Unternehmen darf nur eine einzelne Filiale als Online-Shop kennzeichnen. |
030.015 |
Es darf nur einen Online-Shop geben. Es wurden <Anzahl OnlineShops> Filialen als Online-Shop gekennzeichnet. |
Jede Filiale, die nicht als Online-Shop gekennzeichnet ist, muss eine Standort-GLN enthalten. |
030.016 |
Filialen, die nicht als Online-Shop gekennzeichnet sind, müssen eine Standort-GLN enthalten. Ein Fehler dieser Art tritt <Anzahl Fehler> Mal auf. |
Jede Filiale, die als Online-Shop gekennzeichnet ist, muss keine Standort-GLN enthalten. |
030.017 |
Filialen, die als Online-Shop gekennzeichnet sind, dürfen keine Standort-GLN enthalten. Betroffene GLN Nummern sind "<Liste betroffener Standort-GLN>". Ein Fehler dieser Art tritt <Anzahl Fehler> Mal auf. |
Prüfregel | Prüfregel-ID | Text im Prüfprotokoll |
---|---|---|
Das Meldejahr muss gültig sein. Das meldende Unternehmen kann frühestens ab dem Jahr 2025 einen Bericht einbringen. Das im Bericht eingetragene Meldejahr darf 2024 nicht unterschreiten, nicht dem aktuellen Jahr entsprechen und nicht in der Zukunft liegen. | 010.010 |
Das Jahr <im Bericht eingetragenes Meldejahr> des Berichtszeitraumes ist ungültig. Die Meldung muss für eines der folgenden Jahre erfolgen: <kommaseparierte Liste gültiger Meldejahre bezogen auf das aktuelle Kalenderjahr>. Bzw. Das Jahr <im Bericht eingetragenes Meldejahr> des Berichtszeitraumes ist ungültig. Für das aktuelle Jahr kann keine Meldung eingebracht werden. |
Die Getränkekategorie muss einem Eintrag in der Reda-Liste 7023 entsprechen. |
040.010 |
Ungültige Getränkekategorie. Betroffene Werte: "<Liste betroffener Werte>", betroffene Artikel: "<betroffene Artikel>", betroffene Filialen: "<betroffene Filialen>". Gültige Werte für REDA Liste 7023 "Liste von Getränkekategorien gemäß § 14b Abfallwirtschaftsgesetz 2002" sind: <Liste gültiger Werte>. Ein Fehler dieser Art tritt <Anzahl Fehler> Mal auf. |
Die Getränkeverpackung muss einem Eintrag in der Reda-Liste 9111 entsprechen. | 040.012 |
Ungültiges Verpackungsmaterial. Betroffene Werte: "<Ungültige Verpackung>", betroffene Artikel: "<betroffene Artikel>", betroffene Filialen: "<betroffene Filialen>". Gültige Werte für REDA Liste 9111 "Liste von Packstoffen und Verbundverpackungs-Arten gemäß § 22 Abs. 4 Z 7 Verpackungsverordnung 2014 idF BGBl. II Nr. 597/2021" sind: <Liste gültiger Werte>. Ein Fehler dieser Art tritt <Anzahl Fehler> Mal auf. |
Der Angebotszeitraum jedes Artikels, der kein Saisonartikel ist, muss ein gültiges Datum für den Start im Format "YYYY-MM-DD" besitzen. |
040.013 |
Ungültiger Start des Angebotszeitraumes. Betroffene Daten: "<Liste betroffener Daten>", betroffene Artikel: "<betroffene Artikel>", betroffene Filialen: "<betroffene Filialen>". Ein Fehler dieser Art tritt <Anzahl Fehler> Mal auf. Das Datum muss im Format "YYYY-MM-DD" sein. |
Der Angebotszeitraum jedes Artikels, der kein Saisonartikel ist, muss ein gültiges Datum für das Ende im Format "YYYY-MM-DD" besitzen. |
040.014 |
Ungültiges Ende des Angebotszeitraumes. Betroffene Daten: "<Liste betroffener Daten>", betroffene Artikel: "<betroffene Artikel>", betroffene Filialen: "<betroffene Filialen>". Ein Fehler dieser Art tritt <Anzahl Fehler> Mal auf. Das Datum muss im Format "YYYY-MM-DD" sein. |
Das Startdatum des Angebotszeitraumes jedes Artikels muss vor dem Enddatum des Angebotszeitraumes liegen oder diesem entsprechen. |
040.015 |
Start des Angebotszeitraumes darf nicht nach Ende des Angebotszeitraumes liegen. Betroffene Start- u. Enddaten: "<Liste betroffener Start- u. Enddaten>", betroffene Artikel: "<betroffene Artikel>", betroffene Filialen: "<betroffene Filialen>". Ein Fehler dieser Art tritt <Anzahl Fehler> Mal auf. |
Das Jahr des Starts des Angebotszeitraumes jedes Artikels, der kein Saisonartikel ist, muss einem gültigen Jahr laut obiger Regel für das Meldejahr entsprechen. |
040.016 |
Ungültiges Jahr für Start des Angebotszeitraumes. Betroffene Daten: "<Liste betroffener Daten>", betroffene Artikel: "<betroffene Artikel>", betroffene Filialen: "<betroffene Filialen>". Ein Fehler dieser Art tritt <Anzahl Fehler> Mal auf. |
Das Jahr des Ende des Angebotszeitraumes jedes Artikels, der kein Saisonartikel ist, muss einem gültigen Jahr laut obiger Regel für das Meldejahr entsprechen. |
040.017 |
Ungültiges Jahr für Ende des Angebotszeitraumes. Betroffene Daten: "<Liste betroffener Daten>", betroffene Artikel: "<betroffene Artikel>", betroffene Filialen: "<betroffene Filialen>". Ein Fehler dieser Art tritt <Anzahl Fehler> Mal auf. |
Die GLN jeder Filiale muss eindeutig sein. | 030.010 |
Angaben für Standort-GLN sind nicht eindeutig und werden für mehr als eine Filiale verwendet. Betroffene GLN Nummern sind: "<Liste betroffener Standort-GLN>". Ein Fehler dieser Art tritt <Anzahl Fehler> Mal auf. |
Das meldende Unternehmen muss mittels gültiger Personen-GLN angegeben werden, welche der Personen-GLN des eingeloggten Benutzers entspricht. |
030.011 | Die Personen-GLN <im Bericht eingetragene Personen-GLN> der Meldung stimmt nicht mit der Personen-GLN <Personen-GLN des eingeloggten Benutzers> angemeldeten Benutzers überein. |
Die Standort-GLN jeder Filiale muss der Personen-GLN des eingeloggten Benutzers zugehörig sein. |
030.012 |
Die Filialen mit folgenden Standort-GLN konnten nicht dem meldenden Betrieb zugeordnet werden: "<betreffende GLN>". |
Der eingeloggte Registrierte muss in seinen Stammdaten Standorte angelegt haben (mindestens einen). |
030.013 | Es wurde für den Betrieb keine Standort-GLN gefunden. |
Zu jeder Standort-GLN, die in der Meldung vorkommt, muss eine Adresse in den Stammdaten angegeben worden sein. Die Angabe eines Grundstücks, ohne Adresse, ist ungültig. |
030.014 |
Zur folgenden Standort-GLN liegen keine Adressdaten vor. Bitte tragen Sie diese Daten in ihren Stammdaten ein: "<betreffende GLN>". |
Das meldende Unternehmen darf nur eine einzelne Filiale als Online-Shop kennzeichnen. |
030.015 |
Es darf nur einen Online-Shop geben. Es wurden <Anzahl OnlineShops> Filialen als Online-Shop gekennzeichnet. |
Jede Filiale, die nicht als Online-Shop gekennzeichnet ist, muss eine Standort-GLN enthalten. |
030.016 |
Filialen, die nicht als Online-Shop gekennzeichnet sind, müssen eine Standort-GLN enthalten. Ein Fehler dieser Art tritt <Anzahl Fehler> Mal auf. |
Jede Filiale, die als Online-Shop gekennzeichnet ist, muss keine Standort-GLN enthalten. |
030.017 |
Filialen, die als Online-Shop gekennzeichnet sind, dürfen keine Standort-GLN enthalten. Betroffene GLN Nummern sind "<Liste betroffener Standort-GLN>". Ein Fehler dieser Art tritt <Anzahl Fehler> Mal auf. |
Prüfregel | Prüfregel-ID | Text im Prüfprotokoll |
---|---|---|
Es müssen Artikel einer Kategorie angeboten werden wenn in dieser auch Absatz gemeldet wird. | 110.010 | In folgenden Getränkekategorien wurde Absatz gemeldet, doch keine Artikel wurden in der jeweiligen Kategorie angeboten: "<Liste der betroffenen Getränkekategorien>". |
BMK
Bundesministerium für Klimaschutz, Umwelt, Energie, Mobilität, Innovation und Technologie, https://www.bmk.gv.at/
EDI
Electronic Data Interchange (Elektronischer Datenaustausch)
MWQ
Mehrwegquote
EDM
Elektronisches Datenmanegement in der Umwelt- und Abfallwirtschaft, vom BMK betriebene e-Government-Lösung, https://edm.gv.at/
GLN
Global Location Number, ein von GS1 spezifiziertes und verwaltetes Identifikationsschema für (Unternehmens-)Standorte
GS1
Global Standards One, ein Netzwerk von Non-Profit-Organisationen, das mit Unternehmensverbänden, Behörden, Regierungen und Hochschulen arbeitet um standardbasierte Lösungen für den elektronischen Datenaustausch (EDI) zu entwickeln, https://www.gs1.org/
GTIN
Global Trade Item Number, ein von GS1 spezifiziertes und verwaltetes Identifikationsschema für Handelsartikel
ISO
International Organization for Standardization, ein internationales Normungsgremium, das sich aus Vertretern der verschiedenen nationalen Normungsorganisationen zusammensetzt, https://www.iso.org/
W3C
World Wide Web Consortium, eine internationale Organisation, die offene Internet-bezogene Standards entwickelt, https://www.w3.org/
Bundesgesetz über eine nachhaltige Abfallwirtschaft (Abfallwirtschaftsgesetz 2002), BGBl. I Nr. 102/2002, idgF.
HTTP/1.1
Hypertext Transfer Protocol, RFC 723x, IETF Internet Standard.
JSON ECMA-404
[XML] Schema Definition Language, W3C Recommendation.
Version | Datum | Beschreibung / Änderungen |
---|---|---|
0.01 | 2024‑11-15 |
Interner Erstentwurf |
1.0.0 | 2024-12-03 |
Version 1.0.0 |