WebService Open API 3.0

Owned by Ansgar Redder
25.11.2019
54 min read

Die Open API 3.0 Spezifikation definiert einen programmiersprachenunabhängige Standard um RESTfull APIs beschreiben zu können. Diese ist sowohl für Menschen als auch für Computer lesbar und kann als Basis für Dokumentation, Codegenerierung von Client und Server in verschiedenen Programmiersprachen verwendet werden.

Open API hat sich in Verbindung mit der Beschreibungssprache “Swagger” als ein “Quasi Standard” durchgesetzt.

Über die Beschreibungssprache können die verschiedenen relevanten Aspekte einer API Eindeutig definiert werden. Diese sind:

  • Allgemeine Informationen zur API

    • Titel

    • Beschreibung

    • Version

  • Angaben zum Server

    • Liste der URLs inkl. Beschreibung

  • Angaben zur Authentifizierung

    • Art der möglichen Authentifizierung z. B. oAuth2

  • Pfade der API

    • Angabe der verschiednen Methoden / Endpunkte die in der API definiert sind

  • Parameter

    • Definition der Anfragemethode “GET”, “POST”, …

    • Beschreibung

  • Anfragestruktur

    • Definition der möglichen Parameter

      • Name

      • Beschreibung

      • Format

      • Pflicht

  • Antwort

    • Definition der mögliche Fehlerfälle

      • Fehlercode

      • Beschreibung

    • Definition der Antwortstruktur bei erfolgreicher Anfrage

      • Datenfelder

        • Name

        • Beschreibung

        • Format

        • ..

Beispiel:

{
  "openapi" : "3.0.0",
  "servers" : [ {
    "description" : "SwaggerHub API Auto Mocking",
    "url" : "https://virtserver.swaggerhub.com/ITEK-GmbH/OpenMasterData-ProductAPI/v1.0.1"
  } ],
  "info" : {
    "description" : "OpenMasterData OnDemand Service",
    "version" : "1.0.1",
    "title" : "OpenMasterData Product API",
    "contact" : {
      "email" : "info@itek.de"
    }
  },
  "paths" : {
    "/product/byGTIN" : {
      "get" : {
        "summary" : "Liefert einen Artikel anhand der GTIN",
        "operationId" : "getProductByGTIN",
        "security" : [ {
          "oAuth2Password" : [ "read" ]
        } ],
        "parameters" : [ {
          "in" : "query",
          "name" : "gtin",
          "description" : "GTIN",
          "required" : true,
          "schema" : {
            "$ref" : "#/components/schemas/GTIN"
          }
        }, {
          "in" : "query",
          "name" : "datapackage",
          "style" : "pipeDelimited",
          "required" : true,
          "explode" : false,
          "schema" : {
            "type" : "array",
            "items" : {
              "type" : "string",
              "enum" : [ "basic", "additional", "prices", "descriptions", "logistics", "pictures", "documents" ],
              "minItems" : 1
            }
          }
        }, {
          "in" : "query",
          "name" : "customerId",
          "description" : "Die Kundennummer kann als zusätzliche Angabe genutzt werden, wenn der Login für mehrerer Kunden gültig ist.",
          "schema" : {
            "$ref" : "#/components/schemas/CustomerID"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/Product"
                }
              }
            }
          },
          "400" : {
            "description" : "Bad Request"
          },
          "401" : {
            "description" : "Unauthorized"
          },
          "403" : {
            "description" : "Forbidden"
          },
          "404" : {
            "description" : "Not Found"
          },
          "429" : {
            "description" : "Too Many Requests"
          },
          "500" : {
            "description" : "Internal Server Error"
          },
          "503" : {
            "description" : "Service Unavailable"
          },
          "x-950" : {
            "description" : "Alternative Product (Code: 950)"
          },
          "x-951" : {
            "description" : "Followup Product (Code: 951)"
          }
        }
      }
    },
    "/product/bySupplierPID" : {
      "get" : {
        "summary" : "Liefert einen Artikel anhand der Artikelnummer / Großhandelsnummer",
        "operationId" : "getProductBySupplierProductID",
        "security" : [ {
          "oAuth2Password" : [ "read" ]
        } ],
        "parameters" : [ {
          "in" : "query",
          "name" : "supplierPid",
          "description" : "Artikelnummer innerhalb des angefragten Lieferanten (Großhandelsnummer)",
          "required" : true,
          "schema" : {
            "$ref" : "#/components/schemas/SupplierPID"
          }
        }, {
          "in" : "query",
          "name" : "datapackage",
          "style" : "pipeDelimited",
          "required" : true,
          "explode" : false,
          "schema" : {
            "type" : "array",
            "items" : {
              "type" : "string",
              "enum" : [ "basic", "additional", "prices", "descriptions", "logistics", "pictures", "documents" ],
              "minItems" : 1
            }
          }
        }, {
          "in" : "query",
          "name" : "customerId",
          "description" : "Die Kundennummer kann als zusätzliche Angabe genutzt werden, wenn der Login für mehrerer Kunden gültig ist.",
          "schema" : {
            "$ref" : "#/components/schemas/CustomerID"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/Product"
                }
              }
            }
          },
          "400" : {
            "description" : "Bad Request"
          },
          "401" : {
            "description" : "Unauthorized"
          },
          "403" : {
            "description" : "Forbidden"
          },
          "404" : {
            "description" : "Not Found"
          },
          "429" : {
            "description" : "Too Many Requests"
          },
          "500" : {
            "description" : "Internal Server Error"
          },
          "503" : {
            "description" : "Service Unavailable"
          },
          "x-950" : {
            "description" : "Alternative Product (Code: 950)"
          },
          "x-951" : {
            "description" : "Followup Product (Code: 951)"
          }
        }
      }
    },
    "/product/byManufacturerData" : {
      "get" : {
        "summary" : "Liefert einen Artikel anhand der HerstellerID und der Artikelnummer",
        "operationId" : "getProductByManufacturerData",
        "security" : [ {
          "oAuth2Password" : [ "read" ]
        } ],
        "parameters" : [ {
          "in" : "query",
          "name" : "manufacturerId",
          "description" : "Identifikation des Herstellers",
          "required" : true,
          "schema" : {
            "$ref" : "#/components/schemas/ManufacturerID"
          }
        }, {
          "in" : "query",
          "name" : "manufacturerPid",
          "description" : "Herstellerartikelnummer",
          "required" : true,
          "schema" : {
            "$ref" : "#/components/schemas/ManufacturerPID"
          }
        }, {
          "in" : "query",
          "name" : "datapackage",
          "style" : "pipeDelimited",
          "required" : true,
          "explode" : false,
          "schema" : {
            "type" : "array",
            "items" : {
              "type" : "string",
              "enum" : [ "basic", "additional", "prices", "descriptions", "logistics", "pictures", "documents" ],
              "minItems" : 1
            }
          }
        }, {
          "in" : "query",
          "name" : "customerId",
          "description" : "Die Kundennummer kann als zusätzliche Angabe genutzt werden, wenn der Login für mehrerer Kunden gültig ist.",
          "schema" : {
            "$ref" : "#/components/schemas/CustomerID"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "OK",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/Product"
                }
              }
            }
          },
          "400" : {
            "description" : "Bad Request"
          },
          "401" : {
            "description" : "Unauthorized"
          },
          "403" : {
            "description" : "Forbidden"
          },
          "404" : {
            "description" : "Not Found"
          },
          "429" : {
            "description" : "Too Many Requests"
          },
          "500" : {
            "description" : "Internal Server Error"
          },
          "503" : {
            "description" : "Service Unavailable"
          },
          "x-950" : {
            "description" : "Alternative Product (Code: 950)"
          },
          "x-951" : {
            "description" : "Followup Product (Code: 951)"
          }
        }
      }
    }
  },
  "components" : {
    "securitySchemes" : {
      "oAuth2Password" : {
        "type" : "oauth2",
        "description" : "Die client_id wird in diesem Authenticationflow als \"Shared Secret\" verwendet. Sie stellt einen zusätzlichen Faktor dar, der pro Installation der Software vergeben wird. Siehe https://developers.getbase.com/docs/rest/articles/oauth2/requests",
        "flows" : {
          "password" : {
            "tokenUrl" : "https://<server>/oauth2/token",
            "scopes" : {
              "read" : "Grant read-only access to all your data"
            }
          }
        }
      }
    },
    "schemas" : {
      "CustomerID" : {
        "type" : "string",
        "description" : "Die Kundennummer kann als zusätzliche Angabe genutzt werden, wenn der Login für mehrerer Kunden gültig ist."
      },
      "GTIN" : {
        "type" : "integer",
        "minLength" : 8,
        "maxLength" : 14,
        "description" : "GTIN des Artikels"
      },
      "SupplierPID" : {
        "type" : "string",
        "description" : "Artikelnummer innerhalb des angefragten Lieferanten (Großhandelsnummer)"
      },
      "ManufacturerPID" : {
        "type" : "string",
        "description" : "Identifikation des Herstellers"
      },
      "ManufacturerID" : {
        "type" : "string",
        "description" : "Herstellerartikelnummer"
      },
      "Unit" : {
        "type" : "string",
        "description" : "Units (Mengeneinheiten) -- Code Beschreibung\n- CMK = Quadratzentimeter\n- CMQ = Kubikzentimeter\n- CMT = Zentimeter\n- DZN = Dutzend\n- GRM = Gramm\n- HLT = Hektoliter\n- KGM = Kilogramm\n- KTM = Kilometer\n- LTR = Liter\n- MMT = Millimeter\n- MTK = Quadratmeter\n- MTQ = Kubikmeter\n- MTR = Meter\n- PCE = Stück\n- PR = Paar\n- SET = Satz\n- TNE = Tonne\n",
        "enum" : [ "CMK", "CMQ", "CMT", "DZN", "GRM", "HLT", "KGM", "KTM", "LTR", "MMT", "MTK", "MTQ", "MTR", "PCE", "PR", "SET", "TNE" ]
      },
      "EnergyEfficiencyClass" : {
        "type" : "string",
        "description" : "Energieeffizienzklasse",
        "enum" : [ "A+++", "A++", "A+", "A", "B", "C", "D", "E", "F", "G" ]
      },
      "TaxCode" : {
        "type" : "integer",
        "description" : "Umsatzsteuer\nCode Beschreibung\n  - 0 = voller Satz Ust.-Artikel\n  - 1 = halber Satz Ust.-Artikel\n  - 7 = Umkehr der Steuerschuld nach §13b UstG\n  - 8 = Umsatzsteuerfrei nach §13b UstG „Bauleistungen“ \n",
        "enum" : [ 0, 1, 7, 8 ]
      },
      "ProductType" : {
        "type" : "string",
        "description" : "Artikeltyp -- Code Beschreibung\n- STD = Standardartikel\n- ERA = Ersatzteil A\n- ERB = Ersatzteil B\n- ERC = Ersatzteil C\n- VA = Variante\n- MA = Maßanfertigung\n- DLS = Dienstleistung / Software\n- PAK = Paket / Set\n- SON = Sonderartikel\n- KAL = Kalkulationsartikel\n- STG = Schüttgut\n",
        "enum" : [ "STD", "ERA", "ERB", "ERC", "VA", "MA", "DLS", "PAK", "SON", "KAL", "STG" ]
      },
      "LinkedProduct" : {
        "type" : "object",
        "required" : [ "productShortDescr", "link" ],
        "properties" : {
          "supplierPid" : {
            "$ref" : "#/components/schemas/SupplierPID"
          },
          "manufacturerId" : {
            "$ref" : "#/components/schemas/ManufacturerID"
          },
          "manufacturerPid" : {
            "$ref" : "#/components/schemas/ManufacturerPID"
          },
          "gtin" : {
            "$ref" : "#/components/schemas/GTIN"
          },
          "productShortDescr" : {
            "type" : "string"
          },
          "imageLink" : {
            "type" : "string",
            "format" : "url",
            "description" : "Url zum Bild"
          }
        }
      },
      "SetsProduct" : {
        "description" : "Artikel im Artikelset",
        "allOf" : [ {
          "$ref" : "#/components/schemas/LinkedProduct"
        } ],
        "required" : [ "amount" ],
        "properties" : {
          "amount" : {
            "type" : "string",
            "description" : "Anzahl der zugeordneten Artikel im Set (bezogen auf Grundeinheit des Artikels)",
            "pattern" : "^\\d{1,16}\\.\\d{1,3}?$"
          }
        }
      },
      "AccessoriesProduct" : {
        "description" : "Zubehörartikel",
        "allOf" : [ {
          "$ref" : "#/components/schemas/SetsProduct"
        } ],
        "required" : [ "necessaryForFunction" ],
        "properties" : {
          "necessaryForFunction" : {
            "type" : "boolean",
            "description" : "Kennzeichnung, ob der Zubehörartikel zur Produktverwendung erforderlich ist."
          }
        }
      },
      "AttributeSystem" : {
        "type" : "string",
        "description" : "Angabe eines Attributsystems auf das sich das Attribut bezieht, z. B. Klassifizierung\n\nCode Beschreibung\n- ETIM 6   = Version ETIM 6\n- ETIM 7   = Version ETIM 7\n- ERP 1.15 = ERP-Daten nach Anforderungen der Version 1.15\n- ERP 2.0  = ERP-Daten nach Anforderungen der Version 2.0\n- INDIV    = Individuelle Attribute z. B. Schlagworte\n- ZVSHK    = Haftungsübernahmevereinbarung des ZVSHK \n",
        "enum" : [ "ETIM 6", "ETIM 7", "ERP 1.15", "ERP 2.0", "INDIV", "ZVSHK" ]
      },
      "Currency" : {
        "type" : "string",
        "description" : "Währung\nCode Beschreibung\n- EUR = Euro \n",
        "enum" : [ "EUR" ]
      },
      "Price" : {
        "type" : "object",
        "description" : "Informationen zum Preis",
        "required" : [ "value", "currency", "basis", "quantityUnit" ],
        "properties" : {
          "value" : {
            "type" : "string",
            "pattern" : "^\\d{1,15}\\.\\d{1,2}?$",
            "description" : "Preis des Artikels"
          },
          "currency" : {
            "$ref" : "#/components/schemas/Currency"
          },
          "basis" : {
            "type" : "integer",
            "maxLength" : 9,
            "description" : "Menge des Artikels, auf die sich der Preis bezieht\nAusschließlich die Werte 1,10,100,1000 erlaubt\n",
            "enum" : [ 1, 10, 100, 1000 ]
          },
          "quantityUnit" : {
            "description" : "Mengeneinheit des Artikels, auf die sich der Preis bezieht",
            "allOf" : [ {
              "$ref" : "#/components/schemas/Unit"
            } ]
          }
        }
      },
      "RawMaterial" : {
        "type" : "string",
        "description" : "Rohstoffangaben\nCode Beschreibung\n-  AL = Aluminium\n-  PB = Blei\n-  CR = Chrom\n-  AU = Gold\n-  CD = Kadmium\n-  CU = Kupfer\n-  MG = Magnesium\n-  MS = Messing\n-  NI = Nickel\n-  PL = Platin\n-  AG = Silber\n-  W  = Wolfram\n-  ZN = Zink\n-  SN = Zinn\n",
        "enum" : [ "AL", "PB", "CR", "AU", "CD", "CU", "MG", "MS", "NI", "PL", "AG", "W", "ZN", "SN" ]
      },
      "Material" : {
        "type" : "object",
        "description" : "Rohstoff",
        "required" : [ "material", "weightBasis", "basisUnit", "proportionByWeight", "proportionUnit", "quotationOfRawMaterial" ],
        "properties" : {
          "material" : {
            "$ref" : "#/components/schemas/RawMaterial"
          },
          "weightBasis" : {
            "type" : "string",
            "pattern" : "^\\d{1,18}\\.\\d{1,4}?$",
            "description" : "Gewichtsbasis. Basisangabe, auf die sich das Gewicht bezieht."
          },
          "basisUnit" : {
            "$ref" : "#/components/schemas/Unit"
          },
          "proportionByWeight" : {
            "type" : "string",
            "pattern" : "^\\d{1,18}\\.\\d{1,4}?$",
            "description" : "Gewichtsanteil des Rohstoffs"
          },
          "proportionUnit" : {
            "$ref" : "#/components/schemas/Unit"
          },
          "quotationOfRawMaterial" : {
            "type" : "string",
            "pattern" : "^\\d{1,15}\\.\\d{1,2}?$",
            "description" : "Notierung (pro 100 KG) des Rohstoffs, welcher im Preis bereits einkalkuliert ist."
          }
        }
      },
      "ProductAttribute" : {
        "type" : "object",
        "required" : [ "attributeSystem", "attributeName", "attributeValue1", "attributeValue2" ],
        "properties" : {
          "attributeSystem" : {
            "$ref" : "#/components/schemas/AttributeSystem"
          },
          "attributeClass" : {
            "type" : "string",
            "description" : "Klasse des Attributs",
            "maxLength" : 60
          },
          "attributeName" : {
            "type" : "string",
            "description" : "Name des Attributs",
            "maxLength" : 60
          },
          "attributeValue1" : {
            "type" : "string",
            "description" : "Wert des Attributs",
            "maxLength" : 60
          },
          "attributeValue2" : {
            "type" : "string",
            "description" : "Wert 2 des Attributs",
            "maxLength" : 60
          },
          "attributeUnit" : {
            "type" : "string",
            "description" : "Einheit des Attributs",
            "maxLength" : 60
          },
          "attributeValueDescr" : {
            "type" : "string",
            "description" : "Ergänzende Beschreibung des Attributwertes",
            "maxLength" : 60
          },
          "attributeClassDesc" : {
            "type" : "string",
            "description" : "Name der Klasse bei ETIM Klassifizieung",
            "maxLength" : 60
          },
          "attributeDesc" : {
            "type" : "string",
            "description" : "Name des Merkmals bei ETIM Klassifizeirung",
            "maxLength" : 60
          },
          "attributeValueDesc" : {
            "type" : "string",
            "description" : "Name des Merkmalswerts bei ETIM Klassifizeirung",
            "maxLength" : 60
          },
          "attributeUnitDesc" : {
            "type" : "string",
            "description" : "Name der einheit bei ETIM Klassifizeirung",
            "maxLength" : 60
          }
        }
      },
      "LengthUnit" : {
        "type" : "string",
        "description" : "Längenmaßeinheit\nCode Beschreibung\n- MMT = Millimeter\n",
        "enum" : [ "MMT" ]
      },
      "WeightUnits" : {
        "type" : "string",
        "description" : "Gewichtsmaßeinheit\nCode Beschreibung\n- KGM = Kilogramm\n",
        "enum" : [ "KGM" ]
      },
      "Measure" : {
        "type" : "object",
        "description" : "Massangabe",
        "required" : [ "measure", "unit" ],
        "properties" : {
          "measure" : {
            "type" : "string",
            "description" : "Maß des Grundartikels",
            "pattern" : "^\\d{1,16}\\.\\d{1,3}?$"
          },
          "unit" : {
            "$ref" : "#/components/schemas/LengthUnit"
          }
        }
      },
      "Weight" : {
        "type" : "object",
        "description" : "Gewichtsangabe",
        "properties" : {
          "weight" : {
            "type" : "string",
            "description" : "Gewicht des Grundartikels",
            "pattern" : "^\\d{1,16}\\.\\d{1,3}?$"
          },
          "unit" : {
            "$ref" : "#/components/schemas/WeightUnits"
          }
        }
      },
      "CountryCode" : {
        "type" : "string",
        "description" : "Länder / Herkunftsländer\nCode Beschreibung\n- AF = Afghanistan\n- EG = Ägypten\n- AX = Åland\n- AL = Albanien\n- DZ = Algerien\n- AS = Amerikanisch-Samoa\n- VI = Amerikanische Jungferninseln\n- AD = Andorra\n- AO = Angola\n- AI = Anguilla\n- AQ = Antarktis\n- AG = Antigua und Barbuda\n- GQ = Äquatorialguinea\n- AR = Argentinien\n- AM = Armenien\n- AW = Aruba\n- AC = Ascension \n- AZ = Aserbaidschan\n- ET = Äthiopien\n- AU = Australien\n- BS = Bahamas\n- BH = Bahrain\n- BD = Bangladesch\n- BB = Barbados\n- BY = Belarus (Weißrussland)\n- BE = Belgien\n- BZ = Belize\n- BJ = Benin\n- BM = Bermuda\n- BT = Bhutan\n- BO = Bolivien\n- BQ = Bonaire, Sint Eustatius und Saba (Niederlande)\n- BA = Bosnien und Herzegowina\n- BW = Botswana\n- BV = Bouvetinsel \n- BR = Brasilien\n- VG = Britische Jungferninseln\n- IO = Britisches Territorium im Indischen Ozean\n- BN = Brunei Darussalam\n- BG = Bulgarien\n- BF = Burkina Faso\n- BU = Burma (jetzt Myanmar)\n- BI = Burundi\n- EA = Ceuta, Melilla\n- CL = Chile\n- CN = China, Volksrepublik\n- CP = Clipperton (reserviert für ITU)\n- CK = Cookinseln\n- CR = Costa Rica\n- CI = Côte d’Ivoire (Elfenbeinküste)\n- CW = Curaçao\n- DK = Dänemark\n- DE = Deutschland\n- DG = Diego Garcia (reserviert für ITU)\n- DM = Dominica\n- DO = Dominikanische Republik\n- DJ = Dschibuti\n- EC = Ecuador\n- SV = El Salvador\n- ER = Eritrea\n- EE = Estland\n- CE = Europäische Gemeinschaft\n- EU = Europäische Union\n- FK = Falklandinseln\n- FO = Färöer\n- FJ = Fidschi\n- FI = Finnland\n- FR = Frankreich\n- FX = Frankreich, France métropolitaine\n- GF = Französisch-Guayana\n- PF = Französisch-Polynesien\n- TF = Französische Süd- und Antarktisgebiete\n- GA = Gabun\n- GM = Gambia\n- GE = Georgien\n- GH = Ghana\n- GI = Gibraltar\n- GD = Grenada\n- GR = Griechenland\n- GL = Grönland\n- GP = Guadeloupe\n- GU = Guam\n- GT = Guatemala\n- GG = Guernsey (Kanalinsel)\n- GN = Guinea\n- GW = Guinea-Bissau\n- GY = Guyana\n- HT = Haiti\n- HM = Heard und McDonaldinseln\n- HN = Honduras\n- HK = Hongkong\n- IN = Indien \n- ID = Indonesien\n- IM = Insel Man\n- IQ = Irak\n- IR = Iran, Islamische Republik\n- IE = Irland\n- IS = Island\n- IL = Israel\n- IT = Italien\n- JM = Jamaika\n- JP = Japan\n- YE = Jemen\n- JE = Jersey (Kanalinsel)\n- JO = Jordanien\n- YU = Jugoslawien (ehemalig)\n- KY = Kaimaninseln\n- KH = Kambodscha\n- CM = Kamerun\n- CA = Kanada\n- IC = Kanarische Inseln\n- CV = Kap Verde\n- KZ = Kasachstan\n- QA = Katar\n- KE = Kenia\n- KG = Kirgisistan\n- KI = Kiribati\n- CC = Kokosinseln\n- CO = Kolumbien\n- KM = Komoren\n- CD = Kongo, Demokratische Republik (ehem. Zaire)\n- CG = Republik Kongo\n- KP = Korea, Demokratische Volksrepublik (Nordkorea)\n- KR = Korea, Republik (Südkorea)\n- HR = Kroatien\n- CU = Kuba\n- KW = Kuwait\n- LA = Laos, Demokratische Volksrepublik\n- LS = Lesotho\n- LV = Lettland\n- LB = Libanon\n- LR = Liberia\n- LY = Libyen\n- LI = Liechtenstein\n- LT = Litauen\n- LU = Luxemburg\n- MO = Macao\n- MG = Madagaskar\n- MW = Malawi\n- MY = Malaysia\n- MV = Malediven\n- ML = Mali\n- MT = Malta\n- MA = Marokko\n- MH = Marshallinseln\n- MQ = Martinique\n- MR = Mauretanien\n- MU = Mauritius\n- YT = Mayotte\n- MK = Mazedonien, ehem. Jugoslawische Republik [2b]\n- MX = Mexiko\n- FM = Mikronesien\n- MD = Moldawien (Republik Moldau)\n- MC = Monaco\n- MN = Mongolei\n- ME = Montenegro\n- MS = Montserrat\n- MZ = Mosambik\n- MM = Myanmar (Burma)\n- NA = Namibia\n- NR = Nauru\n- NP = Nepal\n- NC = Neukaledonien\n- NZ = Neuseeland\n- NT = Neutrale Zone (Saudi-Arabien und Irak bis 1993)\n- NI = Nicaragua\n- QU = Nicht spezifizierte Länder und Gebiete\n- NL = Niederlande\n- AN = Niederländische Antillen (ehemalig)\n- NE = Niger\n- NG = Nigeria\n- NU = Niue\n- MP = Nördliche Marianen\n- NF = Norfolkinsel\n- NO = Norwegen\n- OM = Oman\n- AT = Österreich\n- TL = Osttimor (Timor-Leste)\n- PK = Pakistan\n- PS = Palästinensische Autonomiegebiete\n- PW = Palau\n- PA = Panama\n- PG = Papua-Neuguinea\n- PY = Paraguay\n- PE = Peru\n- PH = Philippinen\n- PN = Pitcairninseln \n- PL = Polen\n- PT = Portugal\n- PR = Puerto Rico\n- RE = Réunion\n- RW = Ruanda\n- RO = Rumänien\n- RU = Russische Föderation\n- SB = Salomonen\n- BL = Saint-Barthélemy\n- MF = Saint-Martin (franz. Teil)\n- ZM = Sambia\n- WS = Samoa\n- SM = San Marino\n- ST = São Tomé und Príncipe\n- SA = Saudi-Arabien\n- SE = Schweden\n- CH = Schweiz (Confoederatio Helvetica)\n- SN = Senegal\n- RS = Serbien \n- CS = Serbien und Montenegro (ehemalig)\n- SC = Seychellen\n- SL = Sierra Leone\n- ZW = Simbabwe\n- SG = Singapur\n- SX = Sint Maarten (niederl. Teil)\n- SK = Slowakei\n- SI = Slowenien\n- SO = Somalia\n- ES = Spanien\n- LK = Sri Lanka\n- SH = St. Helena\n- KN = St. Kitts und Nevis\n- LC = St. Lucia\n- PM = Saint-Pierre und Miquelon\n- VC = St. Vincent und die Grenadinen\n- ZA = Südafrika\n- SD = Sudan\n- GS = Südgeorgien und die Südlichen Sandwichinseln\n- SS = Südsudan\n- SR = Suriname\n- SJ = Svalbard und Jan Mayen\n- SZ = Swasiland\n- SY = Syrien, Arabische Republik\n- TJ = Tadschikistan\n- TW = Republik China (Taiwan)\n- TZ = Tansania, Vereinigte Republik\n- TH = Thailand\n- TG = Togo\n- TK = Tokelau\n- TO = Tonga\n- TT = Trinidad und Tobago\n- TA = Tristan da Cunha (verwaltet von St. Helena, reserviert für UPU)\n- TD = Tschad\n- CZ = Tschechische Republik\n- CS = Tschechoslowakei (ehemalig)\n- TN = Tunesien\n- TR = Türkei \n- TM = Turkmenistan\n- TC = Turks- und Caicosinseln\n- TV = Tuvalu\n- SU = UdSSR (jetzt> Russische Föderation)\n- UG = Uganda\n- UA = Ukraine\n- HU = Ungarn\n- UM = United States Minor Outlying Islands\n- UY = Uruguay\n- UZ = Usbekistan\n- VU = Vanuatu\n- VA = Vatikanstadt\n- VE = Venezuela\n- AE = Vereinigte Arabische Emirate\n- US = Vereinigte Staaten von Amerika\n- GB = Vereinigtes Königreich Großbritannien und Nordirland\n- VN = Vietnam\n- WF = Wallis und Futuna\n- CX = Weihnachtsinsel\n- EH = Westsahara\n- ZR = Zaire (jetzt Demokratische Republik Kongo)\n- CF = Zentralafrikanische Republik\n- CY = Zypern\n",
        "enum" : [ "AF", "EG", "AX", "AL", "DZ", "AS", "VI", "AD", "AO", "AI", "AQ", "AG", "GQ", "AR", "AM", "AW", "AC", "AZ", "ET", "AU", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "VG", "IO", "BN", "BG", "BF", "BU", "BI", "EA", "CL", "CN", "CP", "CK", "CR", "CI", "CW", "DK", "DE", "DG", "DM", "DO", "DJ", "EC", "SV", "ER", "EE", "CE", "EU", "FK", "FO", "FJ", "FI", "FR", "FX", "GF", "PF", "TF", "GA", "GM", "GE", "GH", "GI", "GD", "GR", "GL", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "HN", "HK", "IN", "ID", "IM", "IQ", "IR", "IE", "IS", "IL", "IT", "JM", "JP", "YE", "JE", "JO", "YU", "KY", "KH", "CM", "CA", "IC", "CV", "KZ", "QA", "KE", "KG", "KI", "CC", "CO", "KM", "CD", "CG", "KP", "KR", "HR", "CU", "KW", "LA", "LS", "LV", "LB", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MA", "MH", "MQ", "MR", "MU", "YT", "MK", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MZ", "MM", "NA", "NR", "NP", "NC", "NZ", "NT", "NI", "QU", "NL", "AN", "NE", "NG", "NU", "MP", "NF", "NO", "OM", "AT", "TL", "PK", "PS", "PW", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "RE", "RW", "RO", "RU", "SB", "BL", "MF", "ZM", "WS", "SM", "ST", "SA", "SE", "CH", "SN", "RS", "CS", "SC", "SL", "ZW", "SG", "SX", "SK", "SI", "SO", "ES", "LK", "SH", "KN", "LC", "PM", "VC", "ZA", "SD", "GS", "SS", "SR", "SJ", "SZ", "SY", "TJ", "TW", "TZ", "TH", "TG", "TK", "TO", "TT", "TA", "TD", "CZ", "TN", "TR", "TM", "TC", "TV", "SU", "UG", "UA", "HU", "UM", "UY", "UZ", "VU", "VA", "VE", "AE", "US", "GB", "VN", "WF", "CX", "EH", "ZR", "CF", "CY" ]
      },
      "CarryingCategory" : {
        "type" : "integer",
        "description" : "Befoerderungskategorie. \nBei Gefahrgutartikeln (Kennzeichen Gefahrgut = <true>) ist die Angabe sinnvoll.\nIm Bereich gemischte Produkte gibt es Gefahrgüter ohne weitere Informationen. \n\nCode Beschreibung\n0 = Höchstzulässige Gesamtmenge (in kg bzw. Liter) je Beförderungseinheit 0\n1 = Höchstzulässige Gesamtmenge (in kg bzw. Liter) je Beförderungseinheit 20\n2 = Höchstzulässige Gesamtmenge (in kg bzw. Liter) je Beförderungseinheit 333\n3 = Höchstzulässige Gesamtmenge (in kg bzw. Liter) je Beförderungseinheit: 1000\n4 = Höchstzulässige Gesamtmenge (in kg bzw. Liter) je Beförderungseinheit: unbegrenzt\n",
        "enum" : [ 0, 1, 2, 3, 4 ]
      },
      "PackageType" : {
        "type" : "string",
        "description" : "Art der Verpackungseinheit\nCode Beschreibung\n- BB = Rolle\n- BG = Sack\n- BH = Bund/Bündel\n- BK = Korb\n- CF = Kiste\n- CG = Käfig\n- CH = Gitterbox\n- CT = Karton\n- PA = Päckchen\n- PC = Paket\n- PG = Einwegpalette\n- PK = Colli\n- PN = Europalette\n- PU = Kasten\n- RG = Ring\n- SC = Mischpalette\n- HP = Halbpalette\n- TU = Rohr\n- BTL = Beutel (Tüte)\n- BX = Box \n- CO = Container\n- DY = Display\n- STG = Stange\n- TRO = Trommel\n- PLA = Platte\n- CI = Kanister\n- GEB = Gebinde \n",
        "enum" : [ "BB", "BG", "BH", "BK", "CF", "CG", "CH", "CT", "PA", "PC", "PG", "PK", "PN", "PU", "RG", "SC", "HP", "TU", "BTL", "BX", "CO", "DY", "STG", "TRO", "PLA", "CI", "GEB" ]
      },
      "PackagingUnit" : {
        "type" : "object",
        "description" : "Verpackungseinheit",
        "required" : [ "packagingType", "quantity", "measureA", "measureB", "measureC", "weight" ],
        "properties" : {
          "packagingType" : {
            "$ref" : "#/components/schemas/PackageType"
          },
          "quantity" : {
            "type" : "string",
            "pattern" : "^\\d{1,15}\\.\\d{1,2}?$"
          },
          "gtin" : {
            "$ref" : "#/components/schemas/GTIN"
          },
          "measureA" : {
            "$ref" : "#/components/schemas/Measure"
          },
          "measureB" : {
            "$ref" : "#/components/schemas/Measure"
          },
          "measureC" : {
            "$ref" : "#/components/schemas/Measure"
          },
          "weigth" : {
            "$ref" : "#/components/schemas/Weight"
          }
        }
      },
      "DocumentType" : {
        "type" : "string",
        "description" : "Typ des Dokuments\nCode Beschreibung\n- 2D = 2D-Draufsicht\n- 2F = 2D-Frontale\n- 2S = 2D-Seitenansicht\n- 3C = 3D-Daten\n- 3B = 3D-Daten\n- 3A = 3D-Daten zur Darstellung im Browser\n- AN = Animation\n- DB = Datenblatt\n- GG = Gefahrgut – Datenblatt\n- IS = Instruktion/Bedienungsanleitung\n- MA = Montageanleitung\n- VM = Montagevideo\n- TI = Technische Info\n- VT = Tutorial\n- TZ = Technische Zeichnung \n- VI = Video\n- WA = Wartungsanleitung\n- VP = Produktvideo\n- PA = Planungsanleitung\n- PP = Prospekte\n- ZL = Zulassung\n- SB = Schaltbild\n- SF = Schulungsfolie\n- PF = Pflegeanleitung\n- LE = Bauproduktenverordnung\n- EL = ErP-Label\n- EP = Einzelprospekt\n- UP = UBA-Positivliste\n- WL = WELL-Label\n- EP = Einzelprospekt  Dokumenttyp\n- UP = UBA-Positivliste  Dokumenttyp\n- WL = WELL-Label  Dokumenttyp\n- BS = Brandschutz  Dokumenttyp\n- EX = EX-Schut  Dokumenttyp\n- AS = Arbeitsschutz  Dokumenttyp\n- KS = Korrisionsschutz  Dokumenttyp\n- CS = CE-Konformitätserklärung  Dokumenttyp\n- VD = VDS-Zulassung  Dokumenttyp\n- SS = Schallschutznachweis  Dokumenttyp\n",
        "enum" : [ "2D", "2F", "2S", "3C", "3B", "3A", "AN", "DB", "GG", "IS", "MA", "VM", "TI", "VT", "TZ", "VI", "WA", "VP", "PA", "PP", "ZL", "SB", "SF", "PF", "LE", "EL", "EP", "UP", "WL" ]
      },
      "Document" : {
        "type" : "object",
        "description" : "Die Dokumente des Produktes.",
        "required" : [ "url", "type" ],
        "properties" : {
          "url" : {
            "type" : "string",
            "format" : "url",
            "description" : "Dokument"
          },
          "type" : {
            "$ref" : "#/components/schemas/DocumentType"
          },
          "description" : {
            "type" : "string",
            "description" : "Beschreibung",
            "maxLength" : 40
          },
          "sortOrder" : {
            "type" : "integer",
            "description" : "Reihenfolge",
            "maxLength" : 2
          },
          "size" : {
            "type" : "integer",
            "description" : "Dokumentgröße in Byte"
          }
        }
      },
      "PictureType" : {
        "type" : "string",
        "description" : "Typ des Bildes\nCode Beschreibung\n- B_ = Fotorealistisches Produktbild in Farbe\n- S_ = Fotorealistisches Schwarz-Weiß-Bild\n- U_ = Unvermaßtes Bild (Strichzeichnung)\n- V_ = Vermaßtes Bild (Strichzeichnung)\n- X_ = Explosionszeichnung\n- MI = Milieubild, Badszene\n- DT = Detailbild/-ansicht\n- KV = Keyvisuals – Leitbilder\n- LO = Logo\n- LS = Lifestyle (Emotionsbilder mit Menschen)\n",
        "enum" : [ "B_", "S_", "U_", "V_", "X_", "MI", "DT", "KV", "LO", "LS" ]
      },
      "PictureUse" : {
        "type" : "string",
        "description" : "Verwendung des Dokumentes\nCode Beschreibung\n- Druck = Bild ist für die Verwendung in Printmedien geeignet\n- Web   = Bild ist für die Verwendung im Web geeignet   \n",
        "enum" : [ "Web", "Druck" ],
        "default" : "Druck"
      },
      "Picture" : {
        "type" : "object",
        "description" : "Die Bilder des Produktes.",
        "required" : [ "url", "type", "use", "substituteId" ],
        "properties" : {
          "url" : {
            "type" : "string",
            "format" : "url",
            "description" : "Bild"
          },
          "type" : {
            "$ref" : "#/components/schemas/PictureType"
          },
          "use" : {
            "$ref" : "#/components/schemas/PictureUse"
          },
          "substituteId" : {
            "type" : "boolean",
            "description" : "Stellvertreterkennzeichen"
          },
          "description" : {
            "type" : "string",
            "description" : "Beschreibung",
            "maxLength" : 40
          },
          "sortOrder" : {
            "type" : "integer",
            "description" : "Reihenfolge",
            "maxLength" : 2
          },
          "size" : {
            "type" : "integer",
            "description" : "Bildgröße in Byte"
          }
        }
      },
      "Basic" : {
        "type" : "object",
        "description" : "Die Basisinformationen des Produktes",
        "required" : [ "startOfValidity", "productShortDescr", "priceOnDemand" ],
        "properties" : {
          "productType" : {
            "$ref" : "#/components/schemas/ProductType"
          },
          "startOfValidity" : {
            "type" : "string",
            "format" : "date",
            "description" : "Gültigkeitsbeginn"
          },
          "productShortDescr" : {
            "type" : "string",
            "description" : "Artikelkurzbeschreibung (neuer Text aus dem Textgipfel)"
          },
          "priceOnDemand" : {
            "type" : "boolean",
            "description" : "Angabe, ob der Preis des Artikels nur auf Anfrage übermittelt wird"
          },
          "rrp" : {
            "$ref" : "#/components/schemas/Price"
          },
          "mainCommodityGroupId" : {
            "type" : "string",
            "description" : "Hauptwarengruppe Handel",
            "maxLength" : 3
          },
          "mainCommodityGroupDescr" : {
            "type" : "string",
            "description" : "Hauptwarengruppe Beschreibung Handel",
            "maxLength" : 40
          },
          "commodityGroupId" : {
            "type" : "string",
            "description" : "Warengruppe Handel",
            "maxLength" : 10
          },
          "commodityGroupDescr" : {
            "type" : "string",
            "description" : "Warengruppe Beschreibung Handel",
            "maxLength" : 40
          },
          "noteOfUse" : {
            "type" : "string",
            "description" : "Verwendungshinweis",
            "maxLength" : 512
          }
        }
      },
      "Additional" : {
        "type" : "object",
        "description" : "Die Zusatzinformationen des Produktes",
        "required" : [ "minOrderQuantity", "minOrderUnit", "expiringProduct" ],
        "properties" : {
          "minOrderQuantity" : {
            "type" : "string",
            "pattern" : "^\\d{1,16}\\.\\d{1,3}?$",
            "description" : "Mindestbestellmenge"
          },
          "minOrderUnit" : {
            "$ref" : "#/components/schemas/Unit"
          },
          "articleNumberCatalogue" : {
            "type" : "string",
            "description" : "Werksartikelnummer Katalog",
            "maxLength" : 15
          },
          "alternativeProduct" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/components/schemas/LinkedProduct"
            }
          },
          "followupProduct" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/components/schemas/LinkedProduct"
            },
            "maxItems" : 3
          },
          "deepLink" : {
            "type" : "string",
            "description" : "Deeplink zum Artikel",
            "format" : "url",
            "maxLength" : 256
          },
          "expiringProduct" : {
            "type" : "string",
            "description" : "Auslaufartikel\n  - Yes = Artikel ist Auslauf\n  - Yes-Successor = Artikel ist Auslauf und Nachfolgeartikel existiert\n  - No = Artikel ist nicht Auslauf\n",
            "enum" : [ true, "Yes-Successor", false ]
          },
          "expiringDate" : {
            "type" : "string",
            "description" : "Auslaufdatum",
            "format" : "date"
          },
          "energyEfficiencyClass" : {
            "$ref" : "#/components/schemas/EnergyEfficiencyClass"
          },
          "commodityGroupIdManufacturer" : {
            "type" : "string",
            "description" : "Warengruppen ID des Herstellers",
            "maxLength" : 3
          },
          "commodityGroupDescrManufacturer" : {
            "type" : "string",
            "description" : "Warengruppen Bezeichnung des Herstellers",
            "maxLength" : 40
          },
          "productGroupIdManufacturer" : {
            "type" : "string",
            "description" : "Produktgrupppen ID",
            "maxLength" : 10
          },
          "productGroupDescrManufacturer" : {
            "type" : "string",
            "description" : "Produktgruppen Bezeichnung",
            "maxLength" : 40
          },
          "discoundGroupIdManufacturer" : {
            "type" : "string",
            "description" : "Rabattgruppen ID",
            "maxLength" : 4
          },
          "discountGroupDescrManufacturer" : {
            "type" : "string",
            "description" : "Rabattgruppen Bezeichnung",
            "maxLength" : 40
          },
          "bonusGroupIdManufacturer" : {
            "type" : "string",
            "description" : "Bonusgruppen ID",
            "maxLength" : 35
          },
          "bonusGroupDescrManufacturer" : {
            "type" : "string",
            "description" : "Bonusgruppen Bezeichnung",
            "maxLength" : 40
          },
          "accessories" : {
            "type" : "array",
            "description" : "Liste von Zubehörartikeln",
            "items" : {
              "$ref" : "#/components/schemas/AccessoriesProduct"
            }
          },
          "sets" : {
            "type" : "array",
            "description" : "Artikelsets",
            "items" : {
              "$ref" : "#/components/schemas/SetsProduct"
            }
          },
          "attribute" : {
            "type" : "array",
            "description" : "Liste von Artikelattributen",
            "items" : {
              "$ref" : "#/components/schemas/ProductAttribute"
            }
          }
        }
      },
      "Prices" : {
        "type" : "object",
        "description" : "Die Preisinformationen des Produktes",
        "required" : [ "listPrice", "taxCode" ],
        "properties" : {
          "listPrice" : {
            "$ref" : "#/components/schemas/Price"
          },
          "rrp" : {
            "$ref" : "#/components/schemas/Price"
          },
          "netPrice" : {
            "$ref" : "#/components/schemas/Price"
          },
          "taxCode" : {
            "$ref" : "#/components/schemas/TaxCode"
          },
          "billBasis" : {
            "type" : "string",
            "description" : "Abrechnungsbasis"
          },
          "rawMaterial" : {
            "type" : "array",
            "description" : "Liste von Materialzuschlägen",
            "items" : {
              "$ref" : "#/components/schemas/Material"
            }
          }
        }
      },
      "Descriptions" : {
        "type" : "object",
        "description" : "Die Beschreibungstexte des Produktes.",
        "properties" : {
          "productDescr" : {
            "type" : "string",
            "description" : "Artikelbeschreibung",
            "maxLength" : 10000
          },
          "marketingText" : {
            "type" : "string",
            "description" : "Vermarktungstext",
            "maxLength" : 10000
          }
        }
      },
      "Logistics" : {
        "type" : "object",
        "description" : "Die Logistikinformationen des Produktes",
        "required" : [ "exportable", "hazardousMaterial" ],
        "properties" : {
          "exportable" : {
            "type" : "boolean",
            "description" : "Exportfähig. Angabe, ob ein Artikel exportfähig ist"
          },
          "commodityNumber" : {
            "type" : "integer",
            "description" : "Warennummer. Enthält inhaltlich die Intrastatnummer",
            "maxLength" : 8
          },
          "countryOfOrigin" : {
            "$ref" : "#/components/schemas/CountryCode"
          },
          "hazardousMaterial" : {
            "type" : "boolean",
            "description" : "Angabe, ob Artikel Gefahrgut ist"
          },
          "unNumber" : {
            "type" : "string",
            "description" : "UN-Nummer. Bei Gefahrgutartikeln (Kennzeichen Gefahrgut = <true>) ist die Angabe sinnvoll.\nIm Bereich gemischte Produkte gibt es Gefahrgüter ohne weitere Informationen. \n",
            "maxLength" : 35
          },
          "dangerClass" : {
            "type" : "string",
            "description" : "Gefahrenklasse. Bei Gefahrgutartikeln (Kennzeichen Gefahrgut = <true>) ist die Angabe sinnvoll. Im Bereich gemischte Produkte gibt es Gefahrgüter ohne weitere Informationen. \n",
            "maxLength" : 35
          },
          "carryingCategory" : {
            "$ref" : "#/components/schemas/CarryingCategory"
          },
          "durabilityPeriod" : {
            "type" : "integer",
            "description" : "Haltbarkeitszeitraum des Artikels in Monaten. Der Wert 99 steht für unbegrenzte Haltbarkeit.\n",
            "minimum" : 1,
            "maximum" : 99
          },
          "standardDeliveryPeriod" : {
            "type" : "integer",
            "description" : "Angabe der Standardlieferzeit in Tagen (gerechnet in Arbeitstagen von Mo-Fr)\nHinweis> Pflichtangabe für die Artikeltypen Standard, Variante, Ersatzteil A, Ersatzteil B,\nSchüttgut\n",
            "maxLength" : 8
          },
          "measureA" : {
            "$ref" : "#/components/schemas/Measure"
          },
          "measureB" : {
            "$ref" : "#/components/schemas/Measure"
          },
          "measureC" : {
            "$ref" : "#/components/schemas/Measure"
          },
          "weight" : {
            "$ref" : "#/components/schemas/Weight"
          },
          "packagingQuantity" : {
            "type" : "integer",
            "description" : "Anzahl Packstücke",
            "maxLength" : 8
          },
          "packagingUnits" : {
            "type" : "array",
            "description" : "Liste von Verpackungseinheiten",
            "items" : {
              "$ref" : "#/components/schemas/PackagingUnit"
            },
            "minItems" : 1,
            "maxItems" : 5
          }
        }
      },
      "Pictures" : {
        "type" : "array",
        "description" : "Die Bilder des Produktes.",
        "items" : {
          "$ref" : "#/components/schemas/Picture"
        }
      },
      "Documents" : {
        "type" : "array",
        "description" : "Dokumente des Produktes",
        "items" : {
          "$ref" : "#/components/schemas/Document"
        }
      },
      "Product" : {
        "type" : "object",
        "properties" : {
          "supplierPid" : {
            "type" : "string"
          },
          "manufacturerId" : {
            "type" : "string"
          },
          "manufacturerPid" : {
            "type" : "string"
          },
          "gtin" : {
            "$ref" : "#/components/schemas/GTIN"
          },
          "basic" : {
            "$ref" : "#/components/schemas/Basic"
          },
          "additional" : {
            "$ref" : "#/components/schemas/Additional"
          },
          "prices" : {
            "$ref" : "#/components/schemas/Prices"
          },
          "descriptions" : {
            "$ref" : "#/components/schemas/Descriptions"
          },
          "logistics" : {
            "$ref" : "#/components/schemas/Logistics"
          },
          "pictures" : {
            "$ref" : "#/components/schemas/Pictures"
          },
          "documents" : {
            "$ref" : "#/components/schemas/Documents"
          }
        }
      }
    }
  }
}