youorder.de - API-Leitfaden

Inhaltsübersicht

Allgemeines - Strukturierung

youorder.de verwendet eine Kategoriestruktur mit theoretisch unbegrenzter Tiefe. Ein beispielhafter Ausschnitt aus unserer Struktur sieht vereinfacht wie folgt aus:

Produkte sind ausschließlich einer einzigen Kategorie zugeordnet. Für jede Kategorie der obersten Ebene (in diesem Fall: "Dunstabzugshauben") werden sogenannte "Filter" definiert. Dies entspricht einem Schlüssel-Werte-Paar für detailliertere Produkteigenschaften, die bei jedem Produkt dieser sowie aller untergeordneter Kategorien eingegeben werden kann. Ein Beispiel: In der Kategorie "Dunstabzugshauben" existieren die Filter "Hersteller", "Montageart" und "Merkmale". Alle Produkte in der Kategorie Dunstabzugshauben, Wandhaube, Inselhaube, etc. können (müssen aber nicht zwangsweise) Werte für diese Filter besitzen.

Produkte bestehen immer aus einer Grundstruktur und verschiedenen Ausführungen. Jedes Produkt besitzt mindestens eine Ausführung, meist jedoch noch weitere mit abweichenden, eindeutigen IDs.

Datenformat und Anfrage-URLs

Generell werden die abgefragten Daten als XML (text/xml) mit dem Zeichensatz UTF-8 zurückgegeben.

Die Grundstruktur einer erzeugten XML-Datei sieht wie folgt aus:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<status>
<function>Aufgerufene Methode</function>
<version>Versionsnummer der aufgerufenen Methode, irrelevant</version>
<message>Statusnachricht</message>
<messageCode>Statuscode (Bei Erfolg: 0, siehe unten)</messageCode>
</status>
<!-- Inhalte hier -->
</response>

Anfragen richten sich nach dem Schema:

https://api.youorder.de/methode?parameter1=wert1&parameter2=wert2&dAuth=ihreDomain&dHash=ihrIndividuellerTagesschluessel

Eine verschlüsselte Verbindung via SSL wird stark empfohlen.

Allgemeine Parameter

Wenn nicht explizit gekennzeichnet sind alle in diesem Leitfaden angegebenen Parameter optional.

Parameter-Name: Wert-Typ: Beschreibung:
dAuth (erforderlich) string Domain zum angegebenen Schlüssel, siehe unten.
dHash (erforderlich) string Individueller, tagesabhängiger Schlüssel, siehe unten.
raw boolean (0/1) Erzwingt eine Ausgabe mit dem Inhaltstyp text/plain, vorrangig für Testzwecke

Methoden und Rückgabewerte

Übersicht

Methode: Parameter: Beschreibung:
getStatusCodes Keine Abfrage aller verfügbaren Fehlermeldungen mit Statuscodes
getCategories categoryID
noSubCategories
Abfrage einzelner Kategorien oder Kategoriestrukturen
getProductsFromCategory categoryID (erforderlich)
noSubCategories
Produkte einer Kategorie laden
getProduct productID (erforderlich)
versionID (veraltet)
Einzelne Produktausführung laden
getTraders traderID Abfrage von Lieferanten
getFilterList categoryID Filter und Filterwerte einer Kategorie laden
getAddresses withDeleted In youorder hinterlegte Adressen Ihres Zugangs inkl. IDs laden
sendRequest (Mehrere) Bestellung an youorder senden. Siehe dazu die Bestell-Dokumentation.

getStatusCodes

Mit dieser Methode können alle verfügbaren Fehlermeldungen mit den zugehörigen Statuscodes abgefragt werden.

Diese Methode hat keine speziellen Parameter.

<?xml version="1.0" encoding="UTF-8"?>
<response>
<status>
<function>getStatusCodes</function>
<version>1.0</version>
<message>Die Anfrage war erfolgreich.</message>
<messageCode>0</messageCode>
</status>
<statusCodes>
<code messageCode="0">Die Anfrage war erfolgreich.</code>
<code messageCode="1001">Es wurde keine Anfrage übergeben.</code>
<!-- [...] -->
</statusCodes>
</response>

getCategories

Mit dieser Methode können einzelne Kategorien oder Kategoriebäume abgefragt werden. Standardmäßig wird die gewählte Kategorie inklusive aller Unterkategorien zurückgegeben.

Parameter-Name: Wert-Typ: Beschreibung:
categoryID int Die angegebene Kategorie wird geladen.
Ohne Angabe wird die gesamte Kategoriestruktur geladen.
noSubCategories boolean (0/1) Gibt an, ob Unterkategorien geladen werden sollen.

Beispielantwort für die oben angegebene Kategoriestruktur:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<status>
<function>getCategories</function>
<version>1.0</version>
<parentCategoryID>43</parentCategoryID>
</status>
<categoryList>
<category categoryID="43">
<categoryName><![CDATA[Dunstabzugshauben]]></categoryName>
<children>
<category categoryID="63">
<categoryName><![CDATA[Wandhaube]]></categoryName>
<children/>
</category>
<category categoryID="64">
<categoryName><![CDATA[Inselhaube]]></categoryName>
<children/>
</category>
[...]
</children>
</category>
</categoryList>
</response>

getProductsFromCategory

Mit dieser Methode können alle Produkte aus einer Kategorie geladen werden. Standardmäßig werden auch Unterkategorien der angegebenen Kategorie mit berücksichtigt.

Parameter-Name: Wert-Typ: Beschreibung:
categoryID (erforderlich) int Produkte der angegebenen Kategorie werden geladen.
noSubCategories boolean (0/1) Gibt an, ob Unterkategorien geladen werden sollen.

Beispielantwort für die oben angegebene Kategoriestruktur:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<status>
<function>getProductsFromCategory</function>
<version>1.0</version>
<categoryIDs>
<categoryID>43</categoryID>
<categoryID>63</categoryID>
[...]
</categoryIDs>
<message>Die Anfrage war erfolgreich.</message>
<messageCode>0</messageCode>
</status>
<productList>
<product productID="320" isVersionOf="0" versionID="-1">
<productName><![CDATA[domatix Ferrara 685 / 985 NX]]></productName>
<versionName><![CDATA[685 NX CN/Glas schwarz 60 cm]]></versionName>
<articleNumber><![CDATA[domo 11151117.01]]></articleNumber>
<versionDescription><![CDATA[ ... ]]></versionDescription>
<packagingUnits>1</packagingUnits>
<productSizeD>345</productSizeD>
<productSizeW>600</productSizeW>
<productSizeH>1020</productSizeH>
<productShippingTime>5-7 Werktage</productShippingTime>
<traderID>163</traderID>
<price>799,00</price>
<priceCurrency>€</priceCurrency>
<priceType>0</priceType>
<priceGroup>RG50</priceGroup>
<availability>1</availability>
<eanCode/>
<category categoryID="63"><![CDATA[Wandhaube]]></category>
<filterValue filterID="83" valueID="5364"><![CDATA[domatix]]></filterValue>
<filterValue filterID="84" valueID="6580"><![CDATA[Kopffreie Hauben]]></filterValue>
<filterValue filterID="82" valueID="6579"><![CDATA[Wandhauben]]></filterValue>
<numImages>4</numImages>
</product>
<product productID="14995" isVersionOf="0" versionID="-1">
<productName><![CDATA[domatix Ferrara 685 / 985 NX]]></productName>
<versionName><![CDATA[985 NX CN/Glas schwarz 90 cm]]></versionName>
<articleNumber><![CDATA[domo 11151118.01]]></articleNumber>
<versionDescription><![CDATA[ ... ]]></versionDescription>
<packagingUnits>1</packagingUnits>
<productSizeD>345</productSizeD>
<productSizeW>600</productSizeW>
<productSizeH>1020</productSizeH>
<productShippingTime>5-7 Werktage</productShippingTime>
<traderID>163</traderID>
<price>819,00</price>
<priceCurrency>€</priceCurrency>
<priceType>0</priceType>
<priceGroup>RG50</priceGroup>
<availability>1</availability>
<eanCode/>
<category categoryID="63"><![CDATA[Wandhaube]]></category>
<filterValue filterID="83" valueID="5364"><![CDATA[domatix]]></filterValue>
<filterValue filterID="84" valueID="6580"><![CDATA[Kopffreie Hauben]]></filterValue>
<filterValue filterID="82" valueID="6579"><![CDATA[Wandhauben]]></filterValue>
<numImages>4</numImages>
</product>
[...]
</productList>
</response>

getProduct

Mit dieser Methode kann ein einzelnes Produkt oder eine gewünschte Ausführung abgefragt werden.

Parameter-Name: Wert-Typ: Beschreibung:
productID (erforderlich) int ID des gesuchten Produkts
versionID (veraltet!) int ID der gesuchten Produktausführung (veraltet). Mittlerweile hat jede Ausführung eine eigene Produkt-ID.

Der Rückgabewert dieser Methode entspricht dem der Methode getProductsFromCategory.

getTraders

Mit dieser Methode können Daten eines Lieferanten oder aller Lieferanten abgefragt werden.

Parameter-Name: Wert-Typ: Beschreibung:
traderID int oder array(int) ID des Lieferanten.
Wenn nicht gesetzt werden alle Lieferanten zurückgegeben.

Beispielantwort für den oben angegebenen Lieferanten (ID 163):

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>
        <function>getTraders</function>
        <version>1.0</version>
        <message>Die Anfrage war erfolgreich.</message>
        <messageCode>0</messageCode>
        <traderIDs>
            <traderID>163</traderID>
        </traderIDs>
      </status>
      <trader traderID="163">
          <company>domo-sanifer Küche</company>
      </trader>
</response>

getFilterList

Mit dieser Methode können alle verfügbaren Filter sowie deren derzeit mögliche Werte einer oder mehrerer Kategorien abgefragt werden.

Da nur die oberste Kategorie Filter besitzen kann, werden für Unterkategorien automatisch die zugehörigen Wurzelkategorien geladen und verwendet.

Werden die Filter einer Unterkategorie geladen, so ist das Ergebnis identisch mit dem der Wurzelkategorie. Im Statusknoten steht zu den geladenen Kategorien dann ggf. die zugehörige Wurzelkategorie (als Parameter rootNode="x"). Siehe folgendes Beispiel.

Parameter-Name: Wert-Typ: Beschreibung:
categoryID int oder array(int) Beschränkt die Ausgabe auf eine (Wurzel-)Kategorie.
Dieser Parameter kann eine einzelne ID oder mehrere IDs als Array sein:
categoryID[]=1&categoryID[]=2&cate...

Beispielantwort für die oben angegebenen Kategorien. Beachten Sie, dass es sich bei der Kategorie 63 um eine Unterkategorie der Kategorie 43 handelt:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<status>
<function>getFilterList</function>
<version>1.1</version>
<message>Die Anfrage war erfolgreich.</message>
<messageCode>0</messageCode>
<categoryIDs>
<categoryID>43</categoryID>
<categoryID rootNode="43">63</categoryID>
</categoryIDs>
</status>
<filterList categoryID="43" categoryName="Dunstabzugshauben">
<filter filterID="83" filterName="Hersteller">
<value valueID="6578"><![CDATA[Baumann]]></value>
<value valueID="6052"><![CDATA[Cata]]></value>
[...]
</filter>
<filter filterID="82" filterName="Montageart">
<value valueID="5641"><![CDATA[Arbeitsplattenhauben]]></value>
<value valueID="5625"><![CDATA[Deckenhauben (integrierbar)]]></value>
[...]
</filter>
<filter filterID="84" filterName="Merkmale">
<value valueID="6580"><![CDATA[Kopffreie Hauben]]></value>
</filter>
</filterList>
</response>

getAddresses

Mit dieser Methode können die hinterlegten Adressen Ihres Kontos abgefragt werden.

Parameter-Name: Wert-Typ: Beschreibung:
withDeleted boolean (0/1) Liefere auch gelöschte bzw. einmalig verwendete Adressen zurück. Standard: 0.

Beispielantwort:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <function>getAddresses</function>
    <version>1.0</version>
    <message>Die Anfrage war erfolgreich.</message>
    <messageCode>0</messageCode>
  </status>
  <addresses>
    <address>
      <addressID>(Ihre ID)</addressID>
      <deleted>0</deleted>
      <description>Standardadresse</description>
      <company></company>
      <userTitle>Herr</userTitle>
      <firstName>Max</firstName>
      <lastName>Mustermann</lastName>
      <division>Rechnungsabteilung</division>
      <street>Musterstraße 3</street>
      <addressAddition></addressAddition>
      <postcode>92155</postcode>
      <residence>Musterstadt</residence>
      <country>Deutschland</country>
    </address>
    <address>
      <addressID>(Ihre ID)</addressID>
      <deleted>0</deleted>
      <description>Versandadresse</description>
      <company></company>
      <userTitle>Herr</userTitle>
      <firstName>Max</firstName>
      <lastName>Mustermann</lastName>
      <division></division>
      <street>Musterplatz 10</street>
      <addressAddition></addressAddition>
      <postcode>12055</postcode>
      <residence>Musterdorf</residence>
      <country>Deutschland</country>
    </address>
  </addresses>
</response>

sendRequest

Mit dieser Methode können Sie nach Freischaltung durch unser Team automatisiert Bestellungen an unser System aufgeben. Sehen Sie dazu unsere ausführliche Anleitung für die Bestell-API.

Erläuterung einiger Rückgabewerte und Hinweise

Produkt-Knoten:

In manchen Fällen sind Zubehörartikel als Produktausführung eingetragen. Derzeit wird daran gearbeitet, das Zubehör stets als Einzelartikel verfügbar zu machen.

Hinweis zu den Anfragen: Da zum Teil sehr komplexe Abfragen hinter den einzelnen Methoden stehen, kann die Antwortzeit in Einzelfällen (z.B. Abfrage aller Kategorien mit allen Produkten) einige Zeit in Anspruch nehmen und im schlimmsten Fall sogar durch den Webserver aufgrund von Speichermangel abgebrochen werden. Dies ist eine Problematik, die uns bekannt ist, derzeit aber nicht gelöst werden kann. Sollten Sie eine nicht-XML-Antwort erhalten, versuchen Sie die Anfrage einzuschränken (z.B. weniger Produkte oder Kategorien auf einmal abfragen).

Produkt-Updates

Selbstverständlich bleiben die Artikel nicht immer so, wie sie sind. Daher bieten wir einen Ping-Service an, der eine von Ihnen vorgegebene URL aufruft, sobald ein Produkt, eine Kategorie, eine Ausführung oder ein Filter geändert, hinzugefügt oder gelöscht wird. Dabei wird die Art der Änderung (insert, update, delete) und die jeweilige ID übergeben.

Beispiel: http://example.com/api/product/update?id={productID}&hash=[...]

Die Struktur der URL ist dabei beliebig. Es werden nur GET-Abfragen durchgeführt. Sie können beliebige Adressvorgaben bezüglich geänderter Produkte, Versionen, Kategorien sowie Filter machen.

Wann Sie das Update mit den oben beschriebenen Methoden durchführen bleibt Ihnen überlassen, wir würden es jedoch begrüßen, derartige Updates nur einmal pro Tag und in der Zeit zwischen 3:00 und 5:00 durchzuführen.

Wichtiger Hinweis: Es ist ausdrücklich nicht erwünscht, bei jedem Update-Durchlauf sämtliche Produkte und Kategorien erneut abzufragen. Bitte verwenden Sie dieses Update-System, um den Datentransfer und die Systembelastung auf beiden Seiten niedrig zu halten.

Zugriffs-Schlüssel

Der Zugriff auf die API erfordert einen individuellen, tagesabhängigen Schlüssel. Eine Referenzimplementation für PHP-basierte Systeme sowie Ihren persönlichen, domainspezifischen Initialschlüssel können Sie nach Rücksprache mit youorder / Herrn Weyh per E-Mail zugesandt bekommen. Eine Weitergabe des für Sie persönlich erzeugten Initialschlüssels ist untersagt.

Update-Benachrichtigungen an Ihren Server werden ebenfalls mit diesem Algorithmus abgesichert, um (D)DoS-Angriffe zu erschweren. Eine Erläuterung der Funktionsweise bekommen Sie zusammen mit Ihrem Initialschlüssel per E-Mail mitgeteilt.

Haben Sie Fragen?

Bei Fragen oder Problemen mit der youorder-API wenden Sie sich bitte per E-Mail an technik [ at ] @youorder.de.

(Wir übernehmen keine Garantie für die Richtigkeit der Daten. Bitte prüfen Sie die Daten ggf. vor Verwendung selbst.)

Kontakt

Derzeit eingeschränkte telefonische Erreichbarkeit.

Wir bitten Sie Anfragen an: verwaltung@weyh.de zu senden.
Unser Online-Shop youorder.de ist 24h und 365 Tage für Sie erreichbar.

Telefon: +49 (0)6626 8099 88-0
E-Mail: info@weyh.de