Diese Schnittstelle steht derzeit noch nicht zur Verfügung und für eine zukünftige Version geplant.

Über die CustomOfferAPI ist es möglich, Produkte in den Warenkorb zu legen die in dieser Konfiguration im Webshop nicht existieren oder bestellbar sind.

Hierbei werden 2 verschiedene Möglichkeiten unterstützt wie diese Produkte übergeben bzw. referenziert werden:

Ein Produkt existiert nicht als Standardprodukt im Webshop: Dies ermöglicht es individuelle oder dynamische Angebote mithilfe externer Tools flexibel zusammenstellen zu können – beispielsweise durch Konfiguratoren, Kalkulationssysteme oder CRM-Anwendungen. Die daraus entstehenden Produktofferte ist nicht als Standardprodukt im Webshop gelistet, sondern wird dynamisch generiert.
Ein Produkt existiert als Standardprodukt im Webshop, es können aber ausgewählte Produktdatenfelder wie z.B. der Preis oder die Rabattierfähigkeit individuell “überschrieben” werden: Dies ermöglicht es, individuell angepasste Angebote mithilfe externer Tools zu erstellen und gleichzeitig die vorhandenen Standardprodukte und Features zu nutzen

Über einen speziell erzeugten Link kann das individuell konfigurierte Angebot direkt im Webshop in den Warenkorb gelegt werden. So wird es dem Kunden ermöglicht, das personalisierte Angebot direkt zu bestellen – ohne dass es im regulären Shop-Sortiment auftauchen muss.

Da es sich um nicht standardisierte Produkte handelt, muss das angebundene Warenwirtschaftssystem bzw. das System zur Weiterverarbeitung von Bestellungen in der Lage sein, diese individuellen oder abweichenden Artikel korrekt zu interpretieren und zu verarbeiten.

Technische Spezifikation

1. Zugriff und Aufruf

Die Schnittstelle zu WEBSALE ist als REST-Schnittstelle mit einem festen Zugangspunkt implementiert, Daten werden als Payload in einem JSON-WebToken (JWT) per POST übergeben.

Die REST-Schnittstelle ist nur per SSL aufrufbar (Transportsicherheit), auf eine Authentifizierung mittels Berechtigungstoken wird verzichtet. Die Validierung erfolgt durch die Signatur des JSON-WebTokens, dafür wird ein eigenes SharedSecret in der Konfiguration des Webshops hinterlegt.

Die Übergabe der Daten erfolgt also vollständig clientseitig über den Deeplink, ohne nachträgliche API-Kommunikation.

2. Inhalt des Payloads (JWT)

Das übergebene JWT enthält alle erforderlichen Produktinformationen sowie weitere optionale Angaben und Sicherungsmechanismen.

Pflichtinhalte:

Produktdaten
- entweder in Form von technischen Feldern (Key-Value-Paare), wie in der Import-Dokumentation beschrieben (Variante Import-Format).
  Dem Angebot liegt kein Standardprodukt zugrunde.
- oder aber in Form von technischen Eingabeparametern (Key-Value-Paare), analog der technischen Parameter der Produkteinzelansicht (Variante POST-Parameter-Format).
  Das Angebot basiert auf einem Standardprodukt.
Menge des Produkts.

Optionale Angaben Sicherungsmechanismen:

Freies technisches Feld, das zusätzliche Daten als JSON-String enthält.
UserIndex (zur eindeutigen Nutzerzuordnung)
eMail (zur eindeutigen Nutzerzuordnung)
response (Steuerung des Antwortverhaltens)
Gültigkeitstimestamp (validUntil) zur zeitlichen Begrenzung der Token-Nutzung.

3. Verarbeitung im Shop

Nach erfolgreicher Übergabe:

aus den übergebenen Daten wird ein temporäres Produkt gebildet und in den Warenkorb gelegt.
Dabei
Das Produkt wird direkt in den Warenkorb gelegt.
es wird entweder ein JSON-Objekt mit dem Ergebnis zurückgegeben oder es erfolgt ein Redirect auf die Warenkorbseite

4. Einschränkungen und Besonderheiten

Für Angebote denen kein Standardprodukt zugrunde liegt
- werden nur flache Produktdaten unterstützt:
  - Keine Variantenprodukte
  - Keine Set-/Bundle-Produkte
- Es erfolgt keine inhaltliche oder logische Prüfung des Produkts durch den Shop.
Für Angebote denen ein Standardprodukt zugrunde liegt
- es werden alle Produktarten und Features unterstützt welche auch von den Produkteinzelansicht aus unterstützt werden
- Es erfolgen alle logischen und inhaltlichen Prüfungen des Standardprodukts, wie z.B.
  - es müssen alle notwendigen Eingabedaten übergeben werden
  - für ein Produkt müssen alle Varianten existieren / bekannt sein
  - der Lagerbestand muss verfügbar
  - etc
Eine Angebotsposition kann:
- mehrfach in den Warenkorb gelegt werden,
- mehrfach bestellt werden (auch mehrfach gleichzeitig),
- nicht geändert werden,
- nicht zusammengefasst werden (jede Angebotsposition bleibt einzeln bestehen)

5. Integration in den Bestellgenerator

Der Bestellgenerator unterstützt ein neues Feld in das JWT, wie an den Warenkorb übergeben werden kann.
Die gleichen Sicherungsmechanismen (z. B. Timestamp, UserIndex) greifen auch hier.

6. Ausgeschlossene Bereiche

Die folgende Shopfunktionen unterstützen keine individuellen Angebotsprodukte:

Merkliste
Cookie-Warenkorb
Account-Warenkorb

Konfiguration

Die Konfiguration des Secrets zur JWT Signatur erfolgt in der globalen Konfigurationsdatei global.config:

<CustomOfferAPI>
  secret = 
</CustomOfferAPI>

REST-API

JSON-WebToken (JWT)

Endpoint: /_api/shop/customoffer

Die REST-API wird mit einer POST-Anfrage an den Endpoint aufgerufen. Als POST-Daten wird ein JSON-WebToken mit entsprechender Payload übergeben:

Header:
Verwendeter Signatur-Algorithmus: HS256
Verwendeter Typ: JWT

Payload:
(siehe Beschreibung unten)

Verify-Signature:
HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), <sharedSecret des Konnektors>)

Beispielanfrage:

Payload:

{
  "hello": "world"
}

SharedSecret: geheim

Decoded JWT:

{
  "alg": "HS256",
  "typ": "JWT"
}.{
  "hello": "world"
}.HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),geheim
)

Encoded JWT (POST-Data):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJoZWxsbyI6IndvcmxkIn0.S3cQ1a4_kqxaYdY3xlJ_I5pwQFx0_8iP

PayLoad

Feld	Wert	Pflicht	Beschreibung

Feld	Wert	Pflicht	Beschreibung
iss	String	X	ID des aufrufenden Systems
exp	NumericDate/String		Ablaufdatum
email	String		Wenn angegeben kann nur der Kunde mit der angegebenen eMailadresse das Angebot in den Warenkorb legen. Bedeutet auch der Kunde muss angemeldet sein.
quantity	numeric		Menge nur für producttype=free relevant wenn nicht angegeben wird als Menge 1 verwendet
userindex	String		Wenn angegeben kann der Kunde mit dem angegebenen UserIndex das Angebot in den Warenkorb legen. Bedeutet auch der Kunde muss angemeldet sein.
response	String		Steuerung ob als Antwort ein JSON-Objekt zurückgegeben oder ein Redirect zur Warenkorbseite erfolgen soll. Wenn nicht angegeben wird response verwendet. Mögliche Werte: json redirect
producttype	String	X	Definition ob das Angebot auf einem Standardprodukt basiert oder nicht. In Abhängigkeit davon werden andere Daten im Objekt product erwartet. Mögliche Werte: standard free
product	Objekt		Produktdaten als JSON-Objekt. Für producttype=free: Die Daten müssen als Key-Value-Pairs analog zur Importdatendoku angegeben werden: https://websale.atlassian.net/wiki/spaces/Doku/pages/1850343608/Format+und+Inhalt+-+WS-SFTP-Produkte+PRO+DE#FormatundInhalt-WS-SFTP-ProduktePRO(DE)-Produktdaten-(wpupdate.csv%2Fwpcomplete.csv) Für producttype=standard: Die Daten müssen als Key-Value-Pairs analog zur serialisierten Produktform auf der Produkteinzelansicht übergeben werden.
additionaldata	Objekt		In diesem Objekt können beliebige Daten als JSON-Daten übergeben werden. Die Daten können im Warenkorb angezeigt und mit in den Bestelldaten übergeben werden.

PayLoad-Beispiel producttype=free:

{
   "iss":      "OfferPunchout",
   "userindex":    "12345",
   "quantity": 1,
   "producttype":    "free",
   "product":
   {
      "ProdIndex":  "4711-12",
      "Name": "Wunderbares Produkt",
      "Number": "4711-SO",
      "Price": "199.90",
      "Weight": "218",
      "DiscountFactor":   "0",
      "DenyPayments":   "3,4,5,6",
      "ClimateNeutral":   "y",
      "DenyForRating":   "y"
   },
   "additionaldata":
   {
      "OfferDescription" : "Spezialangebot: individuelle Menge von x ..."
      "produktionsverfahren": "Spritzguss & Montage",
      "dispositionskennzeichen": "E",  
      "lagerort": "Halle 3, Regal A5",
      "fertigungstyp": "Einzelfertigung",
      "logistikklasse": "versandbereit"
   }
}

PayLoad-Beispiel producttype=standard:

{
   "iss":      "OfferPunchout",
   "userindex":    "12345",   
   "producttype":    "standard",
   "product":
   {
      "input_extra_input_1_1": "Ohne Gestaltung",
      "input_extra_input_13_1": "false",
      "input_extra_input_15_1": "true",
      "input_var_PFYDL44_1_1": "130 g/m² Bilderdruckpapier",
      "input_var_PFYDL44_2_1": "4-seitig",      
      "cat_index_1": "2c9ceb8174d893a60174e2bbbd8b62b3",
      "prod_index_1": "PFYDL44",
      "input_var_PFYDL44_3_1": "1000",
      "input_qty_1": "1",
      "prod_index_1": "PFYDL44",
      "input_var_ZXXXXZ1Z_1_2": "1-Bruch Falz",
      "input_var_ZFYXXXXA_1_3": "glänzend gestrichen",
      "input_var_ZFYDL5AX_1_4": "bestes Preis-/Leistungsverhältnis",
      "input_var_ZFYXXX1B_1_5": "keine Bündelung",
      "input_var_ZXXXXX3D_1_6": "ohne Datencheck",
      "input_var_ZFYX420Y_1_7": "4 Arbeitstage",
      "customofferapi_price_1": "22.99",
      "customofferapi_discountfactor_1": "0",
      "customofferapi_price_2": "0",
      "customofferapi_discountfactor_2": "0",
      "customofferapi_price_3": "0",
      "customofferapi_discountfactor_3": "0",
      "customofferapi_price_4": "0",
      "customofferapi_discountfactor_4": "0",
      "customofferapi_price_5": "0",
      "customofferapi_discountfactor_5": "0",
      "customofferapi_price_6": "0",
      "customofferapi_discountfactor_6": "0",
      "customofferapi_price_7": "0",
      "customofferapi_discountfactor_7": "0"
   },
   "additionaldata":
   {
      "OfferDescription" : "Spezialangebot: individuelle Menge von x ..."
      "produktionsverfahren": "Spritzguss & Montage",
      "dispositionskennzeichen": "E",  
      "lagerort": "Halle 3, Regal A5",
      "fertigungstyp": "Einzelfertigung",
      "logistikklasse": "versandbereit"
   }
}

Response JSON

Im Fehlerfall antwortet die Schnittstelle, soweit zutreffend, mit den HTTP-Statuscodes 401/403, ansonsten mit HTTP-Statuscode 400. Zusätzlich wird ein JSON-Objekt zurückgegeben mit entsprechendem Fehlercode und ggf. Fehlermeldung.

Beispiel:

{
   "ErrCode": "123",
   "ErrMsg": "Description"
}

Im Erfolgsfall antwortet die Schnittstelle mit HTTP-Statuscode 200.

Response redirect

Sowohl im Fehler als auch im Erfolgsfall erfolgt ein redirect auf die Warenkorbseite.
Falls konfiguriert wird der SEO-Link auf die Warenkorbseite verwendet.

Als Parameter wird dabei immer “origin=customofferapi” angehängt.
Im Fehlerfall die beiden Parameter ErrCode und ErrMsg.
Auf diese kann dann im Template reagiert werden.