In der Amadeus360 Third Party API (TP API) werden an den verschiedenen Endpunkten Daten gelesen/geschrieben.
Bei den Artikelstammdaten werden die Rezepturen der Verkaufsartikel aus der Richtung der Einkaufsartikel (Lieferanten, Rezepturen, Inhaltsstoffe, Wareneinsatz usw.) definiert.
Voraussetzungen für den Zugriff auf merchendiseman sind in Endpunkte Artikelstammdaten - Allgemein beschrieben.
INHALTSVERZEICHNIS
- Alle Rezepte auflisten
- Einzelnes Rezept abfragen
- Einzelnes Rezept updaten
- Mehrere Rezepte bearbeiten
- Mehrere Rezepte anlegen
- Fehlerbehandlung für Rezepte
- Datenstruktur von Verkaufsartikeln (Tabelle)
- Attributarten Inhaltsstoffe und Allergene (LMIV), Nährwerte
Alle Rezepte auflisten
Um die Rezepte abzufragen werden keine speziellen Parameter benötigt. Der Aufruf erfolgt nach Authentifizierung
Aufruf:
GET https://login.amadeus360.de/extern/merchandiseman/recipe
Antwort-Beispiel:
[ { "id": "jvAE-T6I7gYp8p0BVREbCcnzmoI", "number": 1234, "name": "Testartikel", "active": false, "function": "MAIN", "detailcategory": 0, "meccode": null, "productUse": 0, "prices": [ { "active": true, "priceperunit": 0, "pricefixed": 0, "menucard": 0, "site": 0, "vat1": null, "vat2": null, "vat3": null, "pricelevels": [ { "number": 1, "price": "0" }, { "number": 2, "price": "0" }, { "number": 3, "price": "0" } ] } ], "attributes": [ { "attribute": 53, "value": 1 }, { "attribute": 54, "value": 1 } ] } ]
Einzelnes Rezept abfragen
Mittels ID besteht die Möglichkeit ein einzelnes Rezept abzufragen. Die Struktur bleibt gegenüber der Liste aller Rezepte unverändert. Statt einem Array von Rezepten wird nur ein einzelnes Rezept (JSON-Objekt) zurückgegeben.
Aufruf:
GET https://login.amadeus360.de/extern/merchandiseman/recipe/id/{id}
Der Teil {id} muss hierbei durch die Artikel-ID ersetzt werden.
API-Doku: https://documenter.getpostman.com
Einzelnes Rezept updaten
Mithilfe einer ID, welche in der URL übergeben wird, kann ein einzelnes Rezept bearbeitet werden. Anstatt mit GET wird im Aufruf mit PUT gearbeitet.
Aufruf:
PUT https://login.amadeus360.de/extern/merchandiseman/recipe/id/{id}
Der Teil {id} muss hierbei durch die Artikel-ID ersetzt werden. Bei der Abfrage muss der Content-Type auf application/json stehen. Beim Updaten eines Rezepts muss die ID des Rezepts in den Daten nochmals mitgegeben werden!
API-Doku: https://documenter.getpostman.com
Daten mitsenden:
{ "id": 1234, "number": 22000, "name": "Testartikel2", "active": true, "function": "MAIN", "detailcategory": 5, "meccode": 2 }
Alle Attribute, welche ausgegeben werden beim Abfragen der Artikel (siehe Rezept auflisten) können auch aktualisiert werden - mit Ausnahme des Wareneinsatzes (productUse), welcher errechnet wird. Werden bestimmte Attribute nicht übermittelt, so werden diese nicht aktualisiert.
Antwort-Beispiel (Status 200):
Falls alles erfolgreich war, wird der Status 200 zurückgegeben.
{ "status": "success", "message": "Item update was successful" "editedIds": [1234] }
Mehrere Rezepte bearbeiten
Durch Übermitteln einer ähnlichen Struktur, welche beim Auflisten der Rezepte ausgegeben wird, können mehrere Rezepte aktualisiert werden.
API-Doku: https://documenter.getpostman.com
Der PUT Befehl macht exakt das, was im Datensatz steht. Artikelstammdaten werden sofort umkonfiguriert. Vor allem bei Verwendung von Massenoperationen und Schleifen ist dies genau zu prüfen. Es gibt kein 'UnDo' für die Befehle.
Aufruf:
PUT https://login.amadeus360.de/extern/merchandiseman/recipe
Daten mitsenden:
[ { "id": 1234, "number": 22000, "name": "Testartikel2", "active": true, "function": "MAIN", "detailcategory": 5, "meccode": 2 }, { "id": 1235, "number": 22001, "name": "Testartikel3", "active": true, "function": "MAIN", "detailcategory": 5, "meccode": 2 }, ]
Hierbei gelten die gleichen Regeln wie beim Bearbeiten eines einzelnen Artikels.
Antwort-Beispiel (Status 201):
Falls alles erfolgreich war, wird der Status 201 zurückgegeben.
{ "status": "success", "message": "Item create or update was successful", "editedIds": [1234, 1235] }
Mehrere Rezepte anlegen
Wird keine ID übermittelt, werden neue Rezepte hinzuzugefügt. Durch Übermitteln einer ähnlichen Struktur, welche beim Auflisten der Rezepte ausgegeben wird, können mehrere Rezepte angelegt werden.
API-Doku: https://documenter.getpostman.com
Aufruf:
PUT https://login.amadeus360.de/extern/merchandiseman/recipe
Daten mitsenden:
[ {"id": 1234,"number": 22000, "name": "Testartikel2", "active": true, "function": "MAIN", "detailcategory": 5, "meccode": 2 }, { "number": 22001, "name": "Testartikel3", "active": true, "function": "MAIN", "detailcategory": 5, "meccode": 2 }, ]
Werden neue Artikel mit fehlenden Attributen angegeben, dann werden die gleichen Standardwerte wie beim Anlegen eines neuen Artikels über die Oberfläche von Amadeus 360 verwendet.
Werden Artikel ohne Preis-Objekte angelegt, so werden die Preisobjekte vom ersten Artikel im gleichen MEC-Code übernommen. Auf diese Weise werden alle Einstellungen für Steuern oder auch die Druckersteuerung übernommen.
Antwort-Beispiel (Status 201):
Falls alles erfolgreich war, wird der Status 201 zurückgegeben.
{ "status": "success", "message": "Item create or update was successful", "editedIds": [1234, 1235] }
Fehlerbehandlung für Rezepte
Nachfolgende Liste gibt einen Überblick über die möglichen Fehler, die von Amadeus 360 zurückgegeben werden.
Antwort-Beispiel (Status 400):
Falls der Content-Type falsch gesetzt wurde, oder keine Daten übermittelt wurde, wird der Fehler 400 ausgegeben.
{
"status": "error",
"message": "Content-Type is not application/json"
}
Antwort-Beispiel (Status 403):
Falls das Hochladen von Artikeln nicht als Modul in Amadeus 360 gebucht ist, dann wird der Fehler 403 ausgegeben.
{
"status": "error",
"message": "Module is not enabled for payment"
}
Möglicher Fehler bei: POST, PUT
Antwort-Beispiel (Status 404):
Falls das Rezept nicht gefunden wird, erhält man bei der Abfrage den Status 404.
{
"status": "error",
"message": "Resource not found"
}
Möglicher Fehler bei: GET (mit ID), PUT
Antwort-Beispiel (Status 405):
Falls etwas anderes als GET, PUT oder POST übergeben wird, antwortet der Server mit Status 405.
{
"status": "error",
"message": "Verb not allowed"
}
Antwort-Beispiel (Status 500):
Falls ein oder mehrere Artikel wegen eines Serverfehlers nicht gespeichert werden können, wird Status 500 zurückgegeben.
{
"status": "success",
"message": "Processing data (partially) failed"
}
Datenstruktur von Verkaufsartikeln (Tabelle)
Nachfolgende Liste beschreibt die Daten, welche von der API abgerufen werden oder welche beim Anlegen oder Aktualisieren von Rezepten geschickt werden müssen.
Feld | Datentyp | Beschreibung |
---|---|---|
id | null, integer | ID des Artikels; wird von Amadeus 360 generiert. Beim Anlegen eines neuen Artikels wird dieser Wert automatisch gesetzt. |
number | integer | Artikelnummer des Artikels |
name | string | Name des Artikels |
active | boolean | Status des Artikels (aktiv oder inaktiv) |
function | string | Artikelfunktion; kann folgende Werte annehmen:
|
detailcategory | integer | ID der Feinsparte |
meccode | null, integer | ID des MEC-Codes |
productUse | double | Berechneter Wareneinsatz, readonly-Feld, welches von Amadeus360 beim Ändern der Rezeptur berechnet wird. |
fixedwe | double | fixer Wareneinsatz; er legt den netto Wareneinsatz des Artikels fest |
prices | array | Array von Preisen |
prices[].active | boolean | Status des Preises (aktiv oder inaktiv) |
prices[].priceperunit | double | Auf zwei Nachkommastellen beschränkter Preis pro Einheit (Standardpreis) |
prices[].pricefixed | double | Auf zwei Nachkommastellen beschränkter fixierter Preis |
prices[].menucard | integer | ID des Angebots |
prices[].site | integer | ID der Verkaufsstelle |
prices[].vat1 | null, integer | ID der Steuer 1 |
prices[].vat2 | null, integer | ID der Steuer 2 |
prices[].vat3 | null, integer | ID der Steuer 3 |
prices[].pricelevels | array | Array von Preisen im Zusammenhang mit den Preisleveln |
prices[].pricelevels[].number | integer | ID des Preislevels |
prices[].pricelevels[].price | double | Preis mit zwei Nachkommastellen |
attributes | array | Array der Attribute (Zusatzstoffe und Allergene) |
attributes[].attribute | integer | ID des Attributs (siehe nachfolgende Tabelle) |
attributes[].value | integer | Falls das Attribut Ja/Nein ist, dann kann der Wert 0 oder 1 sein. Ansonsten kann eine Nummer angegeben werden. |
Attributarten Inhaltsstoffe und Allergene (LMIV), Nährwerte
Attribut | Typ | Einheit | ID | Erlaubte Werte |
---|---|---|---|---|
mit Farbstoff | Additiv | - | 1 | int: 0, 1 |
mit Konservierungsstoff | Additiv | - | 2 | int: 0, 1 |
mit Antioxidationsmittel | Additiv | - | 3 | int: 0, 1 |
mit Geschmacksverstärker | Additiv | - | 4 | int: 0, 1 |
geschwefelt | Additiv | - | 5 | int: 0, 1 |
geschwärzt | Additiv | - | 6 | int: 0, 1 |
gewachst | Additiv | - | 7 | int: 0, 1 |
mit Süßungsmittel | Additiv | - | 8 | int: 0, 1 |
Aspartam- Phenylalaninquelle | Additiv | - | 9 | int: 0, 1 |
mit Phosphat | Additiv | - | 10 | int: 0, 1 |
coffeinhaltig | Additiv | - | 11 | int: 0, 1 |
chininhaltig | Additiv | - | 12 | int: 0, 1 |
glutenhaltig | Allergen | - | 46 | int: 0, 1 |
enthält Krebstiere | Allergen | - | 47 | int: 0, 1 |
enthält Eier | Allergen | - | 48 | int: 0, 1 |
enthält Fisch | Allergen | - | 49 | int: 0, 1 |
enthält Erdnüsse | Allergen | - | 50 | int: 0, 1 |
enthält Soja | Allergen | - | 51 | int: 0, 1 |
enthält Milch | Allergen | - | 52 | int: 0, 1 |
enthält Schalenfrüchte | Allergen | - | 53 | int: 0, 1 |
enthält Sellerie | Allergen | - | 54 | int: 0, 1 |
enthält Senf | Allergen | - | 55 | int: 0, 1 |
enthält Sesamsamen | Allergen | - | 56 | int: 0, 1 |
enthält Schwefeldioxid/ Sulfite | Allergen | - | 57 | int: 0, 1 |
enthält Lupinen | Allergen | - | 58 | int: 0, 1 |
enthält Weichtiere | Allergen | - | 59 | int: 0, 1 |
Energie | Nährwert | kcal | 60 | float |
Fett | Nährwert | g | 61 | float |
davon gesättigte Fettsäuren | Nährwert | g | 62 | float |
Kohlenhydrate | Nährwert | g | 63 | float |
davon Zucker | Nährwert | g | 64 | float |
Ballaststoffe | Nährwert | g | 65 | float |
Eiweiß | Nährwert | g | 66 | float |
Salz | Nährwert | g | 67 | float |