Öffentliche API

Der Großteil der Funktionen von OXOMI kann über eine Service-Schnittstelle aufgerufen werden. Hierbei werden HTTP-Anfragen mit den entsprechenden Parametern gesendet und eine Antwort als JSON oder XML erzeugt. Sie können diese Funktionen verwenden, um OXOMI an eigene Anwendungen (bspw. Warenwirtschafts- oder ERP-Systeme) anzubinden.

Allgemeines

Auswahl des Ausgabeformats

Die komplette API von OXOMI kann als Ausgabe entweder JSON oder XML erzeugen. Dies wird über den URL-Pfad gesteuert:

Format	Beschreibung
XML	Um eine XML-Antwort zu erhalten, können Sie die URL `https://oxomi.staging.scireum.com/service/xml/<service-name>` verwenden.
JSON	Um eine JSON-Antwort zu erhalten, können Sie die URL `https://oxomi.staging.scireum.com/service/json/<service-name>` verwenden.

Fehlerbehandlung

Tritt während der Verarbeitung ein Fehler auf, so wird in dem Ergebnis das Fehler-Kennzeichen error gesetzt. Weiterhin wird eine Fehlermeldung als message ausgegeben. Zusätzlich wird die Art des Fehlers als code ausgegeben. War die Verarbeitung erfolgreich, wird das Kennzeichen success gesetzt.

Fehlermeldung

<result>
    <error>true</error>
    <success>false</success>
    <message>Es ist ein Fehler aufgetreten.</message>
    <code>ERROR</code>
</result>

Erfolgsmeldung

<result>
    ... Ergebnisstruktur ...
    <error>false</error>
    <success>true</success>
</result>

Nachfolgend sehen Sie eine beispielhafte Fehler- und Erfolgsmeldung im JSON Format.

Fehlermeldung

{
    error: true,
    success: false,
    message: 'Es ist ein Fehler aufgetreten.',
    code: 'ERROR'
}

Erfolgsmeldung

{
    ... Ergebnisstruktur ...
    error: false
    success: true
}

Die nachfolgende Tabelle beschreibt die auftauchenden Fehlercodes.

Code	Beschreibung
ERROR	Allgemeiner Fehler. In `message` ist eine genaue Fehlerbeschreibung enthalten.
AUTH_REQUIRED	Authentifizierungsfehler. Es wurden keine oder ungültige Authentifizierungsinformationen übergeben.
LOGIN_REQUIRED	Authentifizierungsfehler. Es wurden keine oder ungültige Authentifizierungsinformationen übergeben - Es besteht jedoch die Möglichkeit sich per Benutzername und Passwort anzumelden.

Standard-Parameter

Die folgenden Parameter können oder müssen bei jedem Aufruf mitgegeben werden:

Parameter	Beschreibung
portal	Enthält die ID des Portals, welches angesteuert werden soll.
user	Gibt den Login-Namen des Benutzers an, der angemeldet werden soll. Wenn Sie OXOMI Profiles verwenden, müssen Sie hier pro Benutzer einen eindeutigen Wert übermitteln. Sollten das Portal öffentlich sein oder Sie nicht zwischen einzelnen Benutzern unterscheiden, so können Sie diesen Parameter weglassen. Weitere Infos finden Sie bei Authentifizierung.
roles	Gibt eine mit Kommas getrennte Liste von Rollen an, welche dem Benutzer zugeordnet sind. Beispiel: Heizung,Elektro,A-Kunde. Sollten Sie keine Rollen verwenden oder ist das Portal öffentlich, können Sie diesen Parameter weglassen. Weitere Infos finden Sie bei Authentifizierung.
accessToken	Sollte das Portal nicht öffentlich sein, müssen Sie hier einen Authentifizierungs-Token angeben. Werden die Parameter `user` oder `roles` verwendet, so müssen Sie diese bei der Berechnung des Tokens berücksichtigen. Sollte das Portal öffentlich sein, können Sie diesen Parameter weglassen. Weitere Infos finden Sie bei Authentifizierung.

Ein beispielhafter Service-Aufruf könnte also so aussehen:

https://oxomi.staging.scireum.com/service/xml/portal/auth-info?portal=<PORTAL-ID>&user=test&roles=Test1,Test2&accessToken=<...>

Artikelbezogene Inhalte

Bilder zu einem Artikel

Der Service item/images ermittelt ein oder mehrere Abbildungen für einen Artikel.

Beispiel

https://oxomi.staging.scireum.com/service/xml/item/images?portal=demo&item=MT.001.A

Neben den Standard-Parametern werden die folgenden weiteren Parameter erwartet:

Parameter	Beschreibung
item	Gibt die Artikel- oder Werksnummer an des betreffenden Artikels an.
supplierNumber	Hiermit wird die artikelzugehörige Lieferantennummer festgelegt. Wird keine Lieferantennummer angegeben, so wird nur innerhalb der "Eigenmarke" gesucht und nicht markenübergreifend. Um Lieferantennummern verwenden zu können, müssen diese in OXOMI hinterlegt sein. Pflegen Sie Lieferantennummern über die Partnerschaft zum jeweiligen Lieferanten ( Lieferantennummern).
tag	Gibt einen Tag an, nach dem gefiltert werden soll. Geben Sie mehrere Tags durch Kommas getrennt an.
filterLang	Gibt die Sprache (als 2-buchstabigen ISO-Code) an, nach der gefiltert werden soll.
filterCountry	Gibt das Land (als 2-buchstabigen ISO-Code) an, nach dem gefiltert werden soll.
type	Gibt den Bild-Typ an, nach dem gefiltert werden soll.

Dateien zu einem Artikel

Der Service item/attachments ermittelt ein oder mehrere verknüpfte Dateien für einen Artikel.

Beispiel

https://oxomi.staging.scireum.com/service/xml/item/attachments?portal=demo&item=AS.001.A

Neben den Standard-Parametern werden die folgenden weiteren Parameter erwartet:

Parameter	Beschreibung
item	Gibt die Artikel- oder Werksnummer an des betreffenden Artikels an.
supplierNumber	Hiermit wird die artikelzugehörige Lieferantennummer festgelegt. Wird keine Lieferantennummer angegeben, so wird nur innerhalb der "Eigenmarke" gesucht und nicht markenübergreifend. Um Lieferantennummern verwenden zu können, müssen diese in OXOMI hinterlegt sein. Pflegen Sie Lieferantennummern über die Partnerschaft zum jeweiligen Lieferanten ( Lieferantennummern).
tag	Gibt einen Tag an, nach dem gefiltert werden soll. Geben Sie mehrere Tags durch Kommas getrennt an.
filterLang	Gibt die Sprache (als 2-buchstabigen ISO-Code) an, nach der gefiltert werden soll.
filterCountry	Gibt das Land (als 2-buchstabigen ISO-Code) an, nach dem gefiltert werden soll.
type	Gibt den Datei-Typ an, nach dem gefiltert werden soll.

Videos zu einem Artikel

Der Service item/videos ermittelt ein oder mehrere Videos für einen Artikel.

Beispiel

https://oxomi.staging.scireum.com/service/xml/item/videos?portal=demo&item=EK.001.A

Neben den Standard-Parametern werden die folgenden weiteren Parameter erwartet:

Parameter	Beschreibung
item	Gibt die Artikelnummer des betreffenden Artikels an.
supplierItemNumber	Gibt die Werksnummer des betreffenden Artikels an.
supplierNumber	Hiermit wird die artikelzugehörige Lieferantennummer festgelegt. Um Lieferantennummern verwenden zu können, müssen diese in OXOMI hinterlegt sein. Pflegen Sie Lieferantennummern über die Partnerschaft zum jeweiligen Lieferanten ( Lieferantennummern).
tag	Gibt einen Tag an, nach dem gefiltert werden soll. Geben Sie mehrere Tags durch Kommas getrennt an.
filterLang	Gibt die Sprache (als 2-buchstabigen ISO-Code) an, nach der gefiltert werden soll.
filterCountry	Gibt das Land (als 2-buchstabigen ISO-Code) an, nach dem gefiltert werden soll.
type	Gibt den Video-Typ an, nach dem gefiltert werden soll.
includeOutdated	Belegen Sie diesen Parameter mit dem Wert `true`, damit auch archivierte Videos in den Ergebnissen angezeigt werden.
onlyOutdated	Belegen Sie diesen Parameter mit dem Wert `true`, damit nur archivierte Videos in den Ergebnissen angezeigt werden. Dieser Parameter überschreibt den Parameter `includeOutdated`.

Langtext zu einem Artikel

Der Service item/text ermittelt einen Langtext für einen Artikel.

Beispiel

https://oxomi.staging.scireum.com/service/xml/item/text?portal=demo&item=MT.002.B

Neben den Standard-Parametern werden die folgenden weiteren Parameter erwartet:

Parameter	Beschreibung
item	Gibt die Artikel- oder Werksnummer an des betreffenden Artikels an.
supplierNumber	Hiermit wird die artikelzugehörige Lieferantennummer festgelegt. Wird keine Lieferantennummer angegeben, so wird nur innerhalb der "Eigenmarke" gesucht und nicht markenübergreifend. Um Lieferantennummern verwenden zu können, müssen diese in OXOMI hinterlegt sein. Pflegen Sie Lieferantennummern über die Partnerschaft zum jeweiligen Lieferanten ( Lieferantennummern).
tag	Gibt einen Tag an, nach dem gefiltert werden soll. Geben Sie mehrere Tags durch Kommas getrennt an.
filterLang	Gibt die Sprache (als 2-buchstabigen ISO-Code) an, nach der gefiltert werden soll.
filterCountry	Gibt das Land (als 2-buchstabigen ISO-Code) an, nach dem gefiltert werden soll.
type	Gibt den Langtext-Typ an, nach dem gefiltert werden soll.

Dokumente

Passende Seiten zu einem Artikel

Derzeit bieten wir keinen API-Zugriff auf Dokumente (Seiten), da eine Integration über unsere JavaScript-Komponenten einfacher ist und zum Abspielen sowieso ein Viewer benötigt wird.

Eine Beschreibung der entsprechenden JavaScript-API Funktion finden Sie hier: Einbinden von Dokumenten

Direkter PDF-Download eines Dokuments

Der Service catalog/pdf liefert ein Dokument als PDF-Download aus.

Beispiel

https://oxomi.staging.scireum.com/service/xml/catalog/pdf?portal=demo&catalog=ST_KATALOG&page=1

Neben den Standard-Parametern werden die folgenden weiteren Parameter erwartet:

Parameter	Beschreibung
catalog	Der Bezeichner des gewünschten Dokuments.
page	Optionale Seitenzahl, falls explizit nur eine einzelne Seite gewünscht wird.

Achtung: Damit dieser Service die Dokumente eines Portals ausliefert, muss in den Sicherheitseinstellungen des jeweiligen Portals die Option "PDF-Download zulassen" aktiviert sein.

Videos

Derzeit bieten wir keinen API-Zugriff auf Videos, da eine Integration über unsere JavaScript-Komponenten einfacher ist und zum Abspielen sowieso eine HTML-Anzeige nötig ist.

Eine Beschreibung der entsprechenden JavaScript-API Funktion finden Sie hier: Einbinden von Videos

Sollte Sie dennoch Zugriff benötigen, da Ihre Anwendung Videos abspielen kann, können Sie sich gerne an uns wenden.

Exposés

Derzeit bieten wir keinen API-Zugriff auf Exposés, da eine Integration über unsere JavaScript-Komponenten einfacher ist und zum Anzeigen sowieso eine HTML-Anzeige nötig ist.

Eine Beschreibung der entsprechenden JavaScript-API Funktion finden Sie hier: Einbinden von Exposés

Sollte Sie dennoch Zugriff benötigen, da Ihre Anwendung Exposés anzeigen kann, können Sie sich gerne an uns wenden.

Vorschaubild eines Artikels

Sollten Sie die Anforderung haben ein Vorschaubild eines Artikels verwenden zu wollen, dann können Sie mithilfe einer gezielten URL-Adresse auf das Vorschaubild zugreifen.

Die URL-Adresse lässt sich einfach Generieren indem Sie die nachfolgenden Parameter in richtiger Reihenfolge zusammenbauen. Es kann zwischen zwei Bildgrößen gewählt werden: normal und groß.

Für ein Vorschaubild in normaler Größe benutzen Sie dieses Format
/p/:PORTAL/item/thumbnail/:LIEFERANTENNUMMER/:ARTIKELNUMMER/:AUTHENTIFIZIERUNGS-HASH.

Möchten Sie ein Vorschaubild in großer Bildgröße einsetzen, dann gehen Sie nach diesem Format vor
/p/:PORTAL/item/large-thumbnail/:LIEFERANTENNUMMER/:ARTIKELNUMMER/:AUTHENTIFIZIERUNGS-HASH.

Eine Beschreibung der hierfür notwendigen Parameter finden Sie in der nachfolgenden Tebelle.

Parameter	Beschreibung
:PORTAL	Der Bezeichner des Portals zu dem der Artikel gehört.
:LIEFERANTENNUMMER	Der Lieferantennummer der zu dem gewünschten Artikel gehört.
:ARTIKELNUMMER	Die Artikelnummer des Artikels.
:AUTHENTIFIZIERUNGS-HASH	Ein authentifizierenden Hash-Wert mit dem Sie Zugriff auf das Vorschaubild bekommen. Genauere Details wie Sie diesen Hash berechnen, finden Sie im Unterkapitel Authentifizierung.

Nutzen Sie als manuelles Hilfsmittel unseren Vorschaubild-Link Generator, um beispielhaft einen Link zu einem der Vorschaubilder zu generieren: Vorschaubild-Link Generator

Standard-Bild ändern

Das Standardbild, das ausgeliefert wird, wenn kein Bild gefunden wird können Sie ändern, indem Sie die Adresse des Bilds, das stattdessen ausgeliefert werden soll, im fallback Parameter mitgeben.

Authentifizierung

Für den Zugriff auf Vorschaubilder müssen Sie einen speziellen Authentifizierungs-Hash berechnen. Ohne diesen wird Ihnen der Zugriff auf die Vorschaubilder vom System verweigert.

Für den Authentifizierungs-Hash benötigen Sie den Geheimschlüssel des Portals, die Lieferanten- und die Artikelnummer des gewünschten Artikels. Diese drei Werte setzen Sie hinereinander und wenden einen MD5 Hash-Algorithmus darauf an.

Beispiel: Pseudocode Authentifizierungs-Hash Berechnung

MD5(Geheimschluessel + Lieferantennummer + Artikelnummer)

Hinweis: Wenn Sie auf Artikel Ihrer Eigenmarke zugreifen wollen, dann benutzen Sie das Zeichen - als Lieferantennummer, sowohl in der URL-Adresse als auch im Authentifizierungs-Hash.

Zurück zur Übersicht