Dies ist die Dokumentation zum aktuell implementierten Web-Service:
Dieser Absatz umfasst den fachlichen Teil der API-Dokumentation. Es werden alle möglichen Anwendungsfälle der Web-Service-SSt. nacheinander aufgeführt und kurz erläutert. Danach erfolgt eine Auflistung der übertragenen Daten und deren Konventionen hinsichtlich Bezeichnung, Typ und Länge. Pflichtangaben werden durch Fettschrift hervorgehoben. Möglicherweise an der Schnittstelle auftretende Fehler werden aufgeführt.
Die anzuwendenden Datentypen befinden sich direkt nach dem Namen der zu übertragenden Daten. Sie korrelieren mit den Standard-SOAP-Datentypen. Weitere Einschränkungen bezüglich der Länge bzw. des Gültigkeitsbereiches befinden sich in Klammern. Eine Überschreitung dieser Einschränkungen führt nicht zur Ablehnung der Transaktion, verändert aber den Inhalt der übertragenen Daten.
String(X): Stringdatentyp, ab dem X. Zeichen wird der String abgeschnitten
Int: Ganzzahliger Datentyp mit einem Wertebereich von -2.147.483.648 bis 2.147.483.648
Int(X): Ganzzahliger Datentyp, welcher vor der X.Dezimalstelle abgeschnitten wird (Beschränkung ist hier inhaltlicher Natur, so macht bei der Mehrwertsteuer nur eine zweistellige Dezimalzahl Sinn)
Decimal: Dezimalzahl mit Nachkommastellen
Decimal(X,Y): Dezimalzahl mit der maximalen Länge X (ohne Komma) und maximal Y Nachkommastellen (Beschränkung ist hier inhaltlicher Natur und soll die verwendete Genauigkeit verdeutlichen, so werden beispielsweise bei Eurobeträgen bis zu 4 Nachkommastellen berücksichtigt)
DateTime: Datum und Zeit nach
ISO 8601 (Bsp.: 2008-12-31T23:59:59)
Struktur: Sammlung von Daten verschiedenen Typs (in dieser
API immer von einfachen Datentypen)
Array: Container für eine (theoretisch) beliebige Anzahl von Daten des gleichen Typs (in dieser
API immer vom komplexen Datentyp Struktur)
Jeder Zugriff auf den Webservice erfolgt über die Angabe von Zugangsdaten. Diese stellen Pflichtangaben für jeden Request dar. Sie werden von Serversystem zur Verfügung gestellt. Der Response sind Meldungen im Fehlerfall und können ebenfalls als Antwort bei jeder Transaktion auftreten.
Name der Transaktion:
Request:
Response:
Fehlermeldungen:
„login not found“ wenn User(Shop) nicht gefunden wurde, die Kombination aus login, shop und password nicht korrekt ist oder der User keine Rechte auf Login mittels Webservice besitzt
„transaction not permitted“ wenn User(Shop) kein Recht auf die angeforderte Funktion des Webservice besitzt
Die im Folgenden aufgeführten Anwendungsfälle sind im SOAP-Server implementiert. Sie können vom Client mit dem Namen der Transaktion als Methode aufgerufen werden. Der Aufbau der Anfrage als SOAP-Request und die Antwort des Servers als SOAP-Response sind je Anwendungsfall nachstehend dokumentiert. Im Fehlerfall erfolgt die Antwort als SOAP-Server-Fehler mit der dokumentierten Fehlermeldung als Faultstring.
Diese Transaktion dient der Prüfung des aktuellen Artikelbestandes und der aktuellen Verfügbarkeit. Zur Identifizierung des Artikels wird bevorzugt das Feld clientOptionId verwendet, die Angabe der beim Anlegen des Artikels zurückgemeldete serverOptionId ist aber ebenfalls möglich.
Name der Transaktion:
Request:
Response:
Fehlermeldungen:
„article option not found“ wenn Artikel nicht gefunden wurde
„find more than one article“ wenn mehr als ein Artikel gefunden wurde
„article option id is mandatory“ wenn beide Felder clientOptionId und serverOptionId fehlen bzw. nicht korrekt gesetzt sind, die Angabe einer Option-ID ist Pflicht
„database error“ wenn die Abfrage in der Datenbank fehlschlägt
Diese Transaktion dient der Übergabe einer Bestellung. Sie besteht aus genau einer Struktur für die Bestellungsdaten, genau einer Struktur für die Kundendaten und einem Array aus (theoretisch) beliebig vielen Strukturen für die Daten jeweils eines Artikels. Zur Identifizierung der Artikel wird bevorzugt das Feld clientOptionId verwendet, die Angabe der beim Anlegen des Artikels zurückgemeldete serverOptionId ist aber ebenfalls möglich. Wird ein Artikel nicht gefunden, ist die Bestellung nicht korrekt und muss komplett abgewiesen werden.
Name der Transaktion:
Request:
loginData - Struktur - Zugangsdaten
orderData - Struktur - Daten zur Bestellung
clientOrderId - String(50) - eindeutige Id der Bestellung im Clientsystem
postage_name - String(50) - Name der Versandart
postage_price - Decimal(16,4) - Kosten der Versandart
postage_vat - Decimal(16,4) - MWSt der Versandart
payment_name - String(50) - Name der Bezahlart
payment_price - Decimal(16,4) - Kosten der Bezahlart
currency_symbol - String(50) -
HTML-Entitie zur Darstellung des Währungssymbols (bspw. € für €)
currency_code - String(50) - Währungs-Code nach
ISO 4217 (bspw. EUR)
currency_decimal_separator - String(1) - dezimales Trennzeichen zur Darstellung von Preisen (, oder .)
products_price_netto - Decimal(16,4) - Preis aller Produkte der Bestellung ohne MWSt
products_price_brutto - Decimal(16,4) - Preis aller Produkte der Bestellung mit MWSt
products_mwst - Decimal(16,4) - in allen Produkten der Bestellung enthaltenene MWSt
total_price_netto - Decimal(16,4) - Preis der gesamten Bestellung ohne MWSt
total_price_brutto - Decimal(16,4) - Preis der gesamten Bestellung mit MWSt
total_mwst - Decimal(16,4) - in der gesamten Bestellung enthaltenene MWSt
targetStatus - String(50) - Zielstatus der Bestellung im Serversystem
ordered - DateTime - Erstellungzeit der Bestellung im Clientsystem
customerData - Struktur - Kundendaten
clientCustomerId - String(50) - eindeutige Id des Kunden im Clientsystem
salutation - String(50) - Anrede
title - String(50) - Titel
firstname - String(250) - Vorname
lastname - String(250) - Nachname
birthday - String(10) - Geburtstag nach
ISO 8601 (Format: JJJJ-MM-TT)
company - String(250) - Firma
address - String(250) - Straße
address_nr - String(50) - Hausnummer und Zusätze
additional - String(250) - Zusätzliches
zip - String(50) - PLZ und Zusätze
city - String(250) - Stadt
country - String(250) - Land/Staat
email - String(250) - E-Mail-Adresse
phone - String(50) - Telefonnummer
fax - String(50) - Faxnummer
delivery_salutation - String(50) - Lieferadresse Anrede
delivery_title - String(50) - Lieferadresse Titel
delivery_firstname - String(250) - Lieferadresse Vorname
delivery_lastname - String(250) - Lieferadresse Nachname
delivery_company - String(250) - Lieferadresse Firma
delivery_address - String(250) - Lieferadresse Strasse
delivery_address_nr - String(50) - Lieferadresse Hausnummer und Zusätze
delivery_additional - String(250) - Lieferadresse Zusätzliches
delivery_zip - String(50) - Lieferadresse PLZ
delivery_city - String(250) - Lieferadresse Stadt
delivery_country - String(250) - Lieferadresse Land/Staat
delivery_email - String(250) - Lieferadresse E-Mail-Adresse
delivery_phone - String(250) - Lieferadresse Telefonnummer
delivery_fax - String(250) - Lieferadresse Faxnummer
allArticlesData - Array - Container für alle Artikel
Response:
Fehlermeldungen:
„order already exists serverOrderId: [serverOrderId] created: [Zeit]“ wenn diese Bestellung bereits zum Serversystem übermittelt wurde
„order target status not permitted - supported states: [unterstützte Status]“ wenn der Zielstatus der Bestellung im Serversystem nicht bekannt ist
„article option id is mandatory“ wenn beide Felder clientOptionId und serverOptionId fehlen bzw. nicht korrekt gesetzt sind, die Angabe einer Option-ID ist Pflicht
„article [identInformation] not found“ wenn ein Artikel nicht gefunden wurde
„database error“ wenn die Abfrage in der Datenbank fehlschlägt
Diese Transaktion dient der Anfrage beim Serversystem zum aktuellen Status einer Bestellung.
Dabei sind folgende Status möglich:
„pending“ → ausstehend
„new“ → neu
„queue“ → vorgemerkt
„in process“ → in Bearbeitung
in process confirm“ → Bestätigt
„mail“ → versand
„mail_part“ → teilweise versand
„back“ → retour
„archive“ → archiviert
„trash“ → gelöscht
Die Trackingnummer kann erst geliefert werden, wenn Sie dem Serversystem bekannt ist. Dies erfolgt im Allgemeinen erst, wenn die Bestellung versendet wurde.
Name der Transaktion:
Request:
Response:
Fehlermeldungen:
Diese Transaktion dient der Übergabe von Artikeldaten an das Serversystem. Das Feld clientOptionId dient als eindeutige ID des Artikels bzw. der Artikelvariante. Anhand dieser ID erfolgt eine Prüfung auf Vorhandensein dieser Artikeloption. Ist sie nicht vorhanden wird diese Artikeloption angelegt (mode = new), sonst werden seine Daten aktualisiert (mode = update). Das Feld clientArticleId dient der Zuordnung mehrerer Artikelvarianten zu einem Artikel. Nur wenn diese übermittelt wird ist das Serversystem in der Lage die Artikelvarianten einem Artikel zuzuordnen. Sonst wird mit jeder Artikeloption ein kompletter neuer Artikel erzeugt.
Name der Transaktion:
Request:
Response:
Fehlermeldungen:
„find more than one article“ wenn bei Verwendung der Feldes clientArticleId der Artikel mehrfach gefunden wurde.
„article option id is mandatory“ wenn das Pflichtfeld clientOptionId nicht korrekt gesetzt wurde
„database error“ wenn die Abfrage in der Datenbank fehlschlägt
ACHTUNG: Diese Transaktion steht erst ab myty4.1 Build:6832 (4. November 2009) zur Verfügung.
Diese Transaktion dient der Übergabe aller im Serversystem vorhandenen ArtikelIDs. Dabei können sowohl alle Artikel des Shops angefragt werden als auch nur die Artikel eines bestimmten Navigationspunktes. Dabei werden die IDs aller vorhandenen Artikel ausgeliefert unabhängig von deren Status oder Verfügbarkeit. Das Weg- bzw. Leerlassen der Daten des Navigationspunktes führt zur Auslieferung aller Artikel dieses Shops. Sind die Daten des Navigationspunktes ausgefüllt wird die id bevorzugt. Diese hat beispielhaft das Aussehen „tyNavigationTopicID_[ID]“. Sonst wird die URL verwendet. Nutzen sie dazu die im Frontend des myty-Shop verwendete URL ab dem Domainnamen (Beispiel: “/fashion/damen“). Falsch geschriebene ID bzw. URL führen zur Auslieferung eines leeren Arrays.
Name der Transaktion:
Request:
Response:
Fehlermeldungen:
Dieser Absatz umfasst den technischen Teil der API-Dokumentation. Es wird die eingesetzte Technologie erläutert und die Anforderungen an die Partnerseite definiert.
Die Allgemein zur Anwendung kommende Technologie ist ein Web-Service. Diese Technologie ist in der Lage Anwendungen plattform- und programmiersprachenunabhängig miteinander zu verbinden und deren Kommunikation auf XML-Basis über Internetprotokolle zu ermöglichen.
Konkret zum Einsatz kommt die Technologie SOAP, welche Objekte über diesen Webservice austauschen kann.
Die Firma tyclipso stellt einen SOAP-Server auf Basis der SOAP-Erweiterung von PHP5 zur Verfügung, welcher unter einer festgelegten URI auf SOAP-Anfragen „lauscht“ und die im fachlichen Teil dokumentierten Transaktionen als Methoden zur Verfügung stellt.
Die Partnerseite kann diesen SOAP-Server mit einem beliebigen SOAP-Client auf der festgelegten URI ansprechen und die definierten Methoden aufrufen.
Wichtiger Hinweis zur Implementation des SOAP-Clients:
Bei der Verarbeitung des SOAP-Request durch den Server können die im fachlichen Teil der Dokumentation definierten Fehler auftreten. Die Fehlermeldung erfolgt als SOAP-Exception an den Client. Der SOAP-Standard schreibt das Senden eines zur SOAP-Abarbeitung passenden HTTP-Headers vor (w3.org Definition des SOAP-Standards, Kapitel: 6.2 SOAP HTTP Response). Die SOAP-Erweiterung von PHP5 setzt darum korrekterweise im HTTP-Header des Response den HTTP-Fehlercode 500. Einige SOAP-Client interpretieren den HTTP-Fehlercode und verweigern eine Weiterverarbeitung. In diesem Fall muss jedoch der SOAP-Client den HTTP-Fehlercode ignorieren um an den SOAP-Response zu gelangen. Sollte dies Ihrem SOAP-Client nicht möglich sein, nehmen Sie bitte zeitnah mit der Firma Tyclipso Kontakt auf.
Eine kurze FAQ:
Es ist nicht möglich
XML-Dateien an den
SOAP-Server zu senden oder von diesem zu empfangen. Es muss mit einem
SOAP-Client ein Request entsprechend den dokumentierten Methoden erfolgen. Die oben angesprochene
XML-Technologie dient nur der Übertragung und ist für den Nutzer transparent, da er mit Objekten arbeitet.
Die Technologie des Clients ist unabhängig von der Servertechnologie. Wie dieses in der Technologie des Clients erfolgt ist Sache eben jener Technologie. Für die Serversprache
PHP erfolgt dies mittels eines Clients der
SOAP-Erweiterung. Der Einsatz eines nuSOAP-Clients ist nicht möglich, da nuSOAP trotz des Namens kein
SOAP-Client ist, da es keine Übertragung von Objekten beherrscht. Die Namensgleichheit ist irreführend - nuSOAP ist eher ein
XML-
RPC (
XML-Remote Procedure Call).
Der
SOAP-Server verarbeitet nur die Anfragen eines
SOAP-Clients und beantwortet diese. Es ist einem Server prinzipiell nicht möglich von sich aus Kontakt zu einem Client aufzunehmen.
Weitergehende Erläuterungen sind unter folgenden Links zu finden:
