Ersatzteilshop

Der Ersatzteilshop kann in eine beliebige Seite eingebunden werden.

Folgende Stylesheets und Scripte müssen (vor)geladen werden:
Am besten im <head>(<body> ist auch möglich):

<link href="https://ets.serviceparts24.com/css/app.css" rel="preload" as="style">
<link href="https://ets.serviceparts24.com/js/app.js" rel="preload" as="script">
<link href="https://ets.serviceparts24.com/css/app.css" rel="stylesheet">

Im <body>, am besten am Ende der Seite:

<script src="https://ets.serviceparts24.com/js/app.js"></script>

Der Ersatzeilshop wird im TAG et-store eingebunden:

<et-store token="händler token" logourl="url logo" agburl="url agb" > </et-store>

Innerhalb des et-store Tags, kann beliebiges Markup eingebunden werden, z.B. zur Anzeige eines Loaders. Dieses Markup wird durch den Ersatzteilshop ersetzt, sobald er geladen ist.

<et-store token="händler token" logourl="url logo" agburl="url agb" strWelcome='

optionaler Begrüßungstext' >
   <!-- Das Markup innerhalb des et-store Tags wird ersetzt, sobald der Ersatzteilshop geladen ist.-->
   <div class="d-flex justify-content-center">
      <div class="spinner-border" role="status">
         <span class="sr-only">Loading...</span>
      </div>
   </div>
</et-store>

Parameter im Tag et-store

Parameter
token

Unbedingt erforderlich

Das Token wird von der Hans Sauer GmbH vergeben

logourl

Vollständige URI zu einem Logo ihrer Firma, das auf der Home-Seite angezeigt wird

agburl

Vollständige URI zu den AGB ihrer Firma

strWelcome

optional - Begrüßungstext auf der Home-Seite, kann html Tags enthalten.
Standard: Willkommen im Ersatzteilshop der Firma {Firmenname}

nocheckout

optional - Mit nocheckout="1" wird der Warenkorb im Shop nicht angezeigt (kein Check-Out). Artikel können dann nur über die Schnittstelle etsAddToCart in einen externen Warenkorb übergeben werden.
Standard: 0 (Warenkorb wird angezeigt)

showmachineid

optional - Id einer Maschine, die direkt angezeigt werden soll. Die Startseite wird dann übersprungen.
Ist der Parameter nicht gesetzt oder 0, wird zusätzlich der URL-Parameter ?showmachineid= der Seite ausgewertet.
Beispiel: showmachineid="100035"

Vorbelegen der Rechnungsadresse:

Zum Vorbelegen der Rechnungsadresse, kann auf ihrer Seite eine JavaScript Funktion eingebunden werden, die ein Objekt mit den Kundendaten zurückgibt. Diese Funktion muss getEtsAddress heißen.
Die Funktion darf ein Promise (z.B. async function) oder direkt das Objekt zurückgeben. Die Antwort muss innerhalb von 2 Sekunden vorliegen, andernfalls wird die Rechnungsadresse nicht vorbelegt.

Hinweis zur Ladezeit: Der Shop wartet beim Start auf die Antwort der Funktion. Dadurch verlängert sich die Ladezeit des Shops. Die Funktion sollte deshalb möglichst schnell antworten.

Das zurückgegebene Objekt muss folgende Form haben:

Das Feld Kundennummer ist im Shop nicht veränderbar und wird nur angezeigt, wenn das Feld gefüllt ist.

{
   company: 'Firmenname',
   salutation:'Herr/Frau',
   firstname: 'Vorname',
   lastname: 'Nachname',
   street: 'Strasse',
   street_no: 'Hausnummer',
   postalcode: 'Postleitzahl',
   city: 'Ort',
   country_id: 'DE',
   telephone: 'Telefonnummer',
   telefax: 'Telefax',
   email:'E-Mail-Adressse'
   custno:'Kundennummer'
   invoicing:1|0
}

Beispiel:

async function getEtsAddress(){
   return {
      company: 'ETS Firma',
      salutation:'Frau',
      firstname: 'Franziska',
      lastname: 'Fröhlich',
      street: 'Frohstr',
      street_no: '1',
      postalcode: '45678',
      city: 'Frohrath',
      country_id: 'DE',
      telephone: '0123 456789',
      telefax: '0123 456789',
      email:'franz@froh.de'
      custno:'12345-1'
      invoicing:1
   }
}

Kauf auf Rechnung (Abwicklung über den Händler)

Um Kunden den Kauf auf Rechnung zu ermöglichen, kann den Kundendaten, die über getEtsAddress zurückgegeben werden, ein Feld invoicing angehängt werden. Ist der Wert von invoicing === 1 so wird beim Check-Out zusätzlich ein Button 'Kauf auf Rechnug' aktiviert.
Diese Funktion muss für Ihren Zugang von der Hans Sauer GmbH freigeschaltet werden, ansonsten hat das Feld keine Wirkung.

Externe Warenkörbe befüllen

Um Artikel in einen Warenkorb auf ihrer Seite zu übergeben, kann eine JavaScript Funktion eingebunden werden, die den Artikel entgegennimmt. Diese Funktion muss etsAddToCart heißen und ist optional.
Sie wird aufgerufen, sobald ein Kunde im Shop einen Artikel in den Warenkorb legt, und erhält ein Objekt mit den Artikeldaten und der gewählten Menge. Die Funktion wird zusätzlich zum Shop-Warenkorb aufgerufen. Soll der Shop-Warenkorb ausgeblendet werden, verwenden Sie den Parameter nocheckout.

Voraussetzung: Die Schnittstelle erhält die Artikelnummern der Hans Sauer GmbH (sku). Diese Sauer-Artikelnummern müssen auf ihrer Seite bekannt sein bzw. ihren eigenen Artikeln zugeordnet werden können.

Parameter
Ein Objekt mit den Artikeldaten, unter anderem:

  • id - Id des Artikels im Shop
  • name - Bezeichnung
  • sku - Artikelnummer
  • price, store_price, gross_store_price - Preise
  • available, delivery_days - Verfügbarkeit und Lieferzeit
  • qty - gewählte Menge

Die Funktion muss keinen Wert zurückgeben. Die Rückgabe wird nicht ausgewertet.

Beispiel:

function etsAddToCart(product){
   meinWarenkorb.add(product.sku, product.qty)
}

Verfügbarkeiten aus ihrem System anzeigen

Sollen in der Explosionszeichnung die Verfügbarkeiten aus ihrem Warenwirtschaftssystem angezeigt werden, kann auf ihrer Seite eine JavaScript Funktion eingebunden werden, die die Verfügbarkeiten zu einer Liste von Artikeln zurückgibt. Diese Funktion muss etsGetAvailability heißen und ist optional. Ist sie nicht vorhanden, werden die Verfügbarkeiten des Shops angezeigt.
Die Funktion wird einmal beim Öffnen eines Geräts aufgerufen und erhält alle Artikel des Geräts (alle Zeichnungen). Sie darf ein Promise (empfohlen, z.B. async function) oder direkt das Ergebnisobjekt zurückgeben. Antwortet die Funktion nicht innerhalb von 5 Sekunden oder tritt ein Fehler auf, werden die Verfügbarkeiten des Shops angezeigt.

Voraussetzung: Die Schnittstelle erhält die Artikelnummern der Hans Sauer GmbH (articleNumber). Diese Sauer-Artikelnummern müssen auf ihrer Seite bekannt sein bzw. ihren eigenen Artikeln zugeordnet werden können.

Hinweis zur Ladezeit: Der Shop wartet auf die Antwort der Funktion, bevor die Artikel angezeigt werden. Durch die Abfrage verlängern sich daher die Ladezeiten, und zwar bei jedem Öffnen eines Geräts und bei jeder Suche bzw. jedem Seitenwechsel in der Artikelsuche. Die Funktion sollte deshalb möglichst schnell antworten.

Eine TypeScript-Definition der Schnittstelle steht hier zum Download bereit: etsGetAvailability.d.ts

Parameter (Anfrage)
Ein Objekt mit der Liste items. Jeder Eintrag enthält:

  • id - Ganzzahl, innerhalb der Anfrage eindeutig. Dient als Schlüssel in der Antwort.
  • articleNumber - Artikelnummer (SKU) als String
{
   items: [
      { id: 101, articleNumber: 'ABC-123' },
      { id: 102, articleNumber: 'XYZ-789' }
   ]
}

Rückgabe (Antwort)
Ein Objekt, dessen Schlüssel die id aus der Anfrage sind. Jeder Eintrag enthält:

  • articleNumber - Pflicht. Muss der Artikelnummer entsprechen, die in der Anfrage zu dieser id stand.
  • status - Pflicht. Ganzzahl 0 bis 4 (siehe Tabelle).
  • deliveryDays - optional. Lieferzeit in Tagen (Ganzzahl, 0 bis 100000).

Einträge zu unbekannten ids, mit abweichender articleNumber, ungültigem status oder unbekannten Feldern werden ignoriert. Für ignorierte oder fehlende Artikel bleibt die Verfügbarkeit des Shops erhalten.

{
   101: { articleNumber: 'ABC-123', status: 1 },
   102: { articleNumber: 'XYZ-789', status: 2, deliveryDays: 5 }
}

Status

0Nicht mehr lieferbar
1(Sehr) gute Verfügbarkeit
2Befriedigende Verfügbarkeit
3Kritische Verfügbarkeit
4Auf Anfrage

Beispiel:

async function etsGetAvailability(request){
   const response = {}
   for (const item of request.items) {
      const stock = await meinWawiLookup(item.articleNumber)
      response[item.id] = {
         articleNumber: item.articleNumber,
         status: stock.available ? 1 : 0
      }
   }
   return response
}

Einbindung des Shops über einen iframe

Die definierten Stylesheets der Seite in den der Shop eingebunden wird, wirken auch auf den Ersatzteilshop. Das kann unter Umständen zu unerwünschten effekten führen.
Um den Shop von der umgebenden Seite zu isolieren, empfehlen wir in solchen Fällen die Einbindung des Shops übber einen iframe. Die Quelldatei (src) des iframes sollte dann keinerlei Stylesheets des umgebendem CMS / Shopsystems enthalten.

iframe auf der Seite des einbindenden Systems
Beispiel hier: shop_in_iframe.html

<div class='ihr_content_bereich'>
.
.
.
<iframe src='dokument_ohne_css.html' ></iframe>
.
.
.
</div>

(Beispiel) Quellcode der Seite die vom iframe geladen wird
Beispiel hier : iframe_src.html

<!DOCTYPE html>
<html lang="de">
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
   <link href="https://ets.serviceparts24.com/css/app.css" rel="preload" as="style">
   <link href="https://ets.serviceparts24.com/js/app.js" rel="preload" as="script">
   <link href="https://ets.serviceparts24.com/css/app.css" rel="stylesheet">
 </head>
 <body>
   <style>
     #app{
       height:100vh;
     }
   </style>
   <et-store
     token="ihr Token"
     logourl="ihre Url"
     agburl="ihre Url"
     strwelcome="Ihr Text"
   >
   </et-store>
   <script type="text/javascript" src="https://ets.serviceparts24.com/js/app.js"></script>
 </body>
</html>

Für Fälle in der das Bereitstellen der Seite, welche das iframe laden soll Probleme bereitet, bieten wir ihnen ein Skript an, das das Laden des iframes übernimmt.

Beispiel:
siehe auch hier: etsIframeLoader.html

<iframe id="ets" style="height:90vh;width:100%"></iframe>
<script type="module">
 import {etsIFrameLoader} from "https://ets.serviceparts24.com/util/etsIFrameLoader.js"
  etsIFrameLoader({
  iFrameID:'ets', //optional default ets
   token:"ihr Token",
   logourl:"ihre Url",
   agburl:"ihre Url",
   strwelcome:"ihr Text",
  })
</script>
ACME Logo
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...