Allyouneed.com der Marktplatz der DHL mit mehr als 5 Millionen kaufenden Kunden und über 15 Millionen Angeboten

Technische Dokumentation Händler API

Stand: 07. Sep. 2017 Version 1.4

Inhaltsverzeichnis


1 Einführung

Willkommen beim DHL Webservice zur Produktpflege und Bestellabwicklung bei Allyouneed.com, dem Onlineshopping Marktplatz von DHL. Dieses Dokument soll Händler unterstützen Produkte auf dem Marktplatz zum Verkauf anzubieten bzw. den eigenen Händlershop zu gestalten und Bestellungen zu bearbeiten. Es enthält eine fachliche und technische Beschreibung der Schnittstelle und ist als Referenz-Dokumentation für Softwareentwickler konzipiert. In diesem Dokument werden Hintergründe und Zusammenhänge erläutert, sowie die Anbindung technisch beschrieben.


1.1 Technischer Überblick

Der Webservice von Allyouneed bietet zwei Verarbeitungsmodi, bei denen sich die Rückgabe der Response unterscheidet. Im ersten Modus wird der Request sofort verarbeitet. Während dieser Zeit muss die HTTP-Verbindung aufrecht erhalten werden. Am Ende erhalten Sie das Ergebnis der Verarbeitung in der Response. Dieser Modus ist vordergründig für die Bestellabwicklung gedacht. Im zweiten Modus erhalten Sie nach dem Hochladen des Requests eine RequestId in der Response. Ihr Request wird daraufhin in die Warteschlange eingereiht und danach verarbeitet. Während dieser Zeit ist keine HTTP-Verbindung notwendig. Den Status der Verarbeitung und die Response können Sie durch Angabe der RequestId abfragen. Dieser Modus ist für die Verarbeitung von großen bis sehr großen Datenmengen gedacht. Die folgende Tabellen enthält eine Übersicht der Funktionalitäten und der möglichen Verarbeitungsmodi.

uploadRequest

Funktionalität

Verarbeitungsmodus

Deletions

Löschung der Kategorien oder Produkte

Asynchrone Verarbeitung

Categories

Anlage der Kategorien

Asynchrone Verarbeitung

variantGroups

Anlage der Variantengruppen

Asynchrone Verarbeitung

Descriptions

Anlage der Produkte

Asynchrone Verarbeitung

Offers

Anlage der Angebote

Asynchrone Verarbeitung

InternationalPrices

Anlage internationale Angebote

Asynchrone Verarbeitung

downloadRequest

 

 

catalogstructure

Katalogstruktur herunterladen

Synchrone oder Asynchrone

Verarbeitung

getProductOffers

Alle Produktangebote herunterladen

Asynchrone Verarbeitung

variantConfigurations

Alle Variantenkonfiguration herunterladen

Synchrone oder Asynchrone

Verarbeitung

queryRequest

 

 

orders

Bestellungen abfragen

Synchrone oder Asynchrone

Verarbeitung

creditMemos

Getätigte Gutschriften abfragen

Synchrone oder Asynchrone

Verarbeitung

notificationRequest

 

 

consignments

Warensendungen melden

Synchrone oder Asynchrone

Verarbeitung

trackingNumbers

Trackingnummern übermitteln

Synchrone oder Asynchrone

Verarbeitung

cancellations

Stornierungen melden

Synchrone oder Asynchrone

Verarbeitung

returns

Retouren melden

Synchrone oder Asynchrone

Verarbeitung

creditMemo

Gutschrift anlegen

Synchrone oder Asynchrone

Verarbeitung

dataRequest

 

 

bestPriceRequest

Besten Preis für ein Produkt abfragen

Asynchrone Verarbeitung

productDataRequest

Produktdaten abfragen

Asynchrone Verarbeitung

getMerchantData

Ruft Händlerdaten ab

Asynchrone Verarbeitung

 


1.2 Benötigter Zugang

Für die Nutzung der Schnittstelle müssen Sie sich gegenüber Allyouneed authentifizieren. Dazu benötigen Sie • ‘Username’ • ‘Passwort’ Die Zugangsdaten legen Sie selber während der Registrierung fest. Sollten Sie bereits Händler bei Allyouneed sein, können Sie sofort Ihre bisherigen Logindaten nutzen.

HTTP Request

URL: www.allyouneed.com/dealerapi/xmlAsync

URL: www.allyouneed.com/dealerapi/xml Methode: HTTP-POST


1.3 Rückmeldung und Unterstützung

Falls Sie weitergehende Unterstützung benötigen oder Rückmeldung zum Web Service oder dem Dokument geben möchten, kontaktieren Sie bitte Ihren Vertriebs-Ansprechpartner oder den Allyouneed Händler-Service per Email unter: haendlerservice@allyouneed.com.


1.4 Dokumente und Beispiele herunterladen

Zu den einzelnen Kapiteln existieren Beispieldateien mit möglichen Responses. Alle Beispieldateien befinden sich in unserem Downloadbereich. In den einzelnen Dateien sind zusätzliche Kommentare, die Ihnen die Arbeit mit unserer Schnittstelle erleichtern.


1.5 REST-Client

Für das Debugging von XML-Requests empfiehlt es sich einen REST-Client zu nutzen. Dieser schickt die XML-Daten an die angegebene URL und zeigt die erhaltene Response. Dies kann in der Entwicklungsphase sehr hilfreich sein, um Fehler in der XML-Kommunikation aufzufinden.

REST-Client für Chrome

REST-Client für Firefox

REST-Client für den Desktop

Bei diesen Clients wird die fertig ausgefüllte XML als Request festgelegt und die Endpoint-URL der Produktiv- oder Sandboxumgebung angegeben. Nach dem Absenden werden dann die Daten der Response angezeigt.

nach oben


2 XML Header

Für jeden Request sind die Header-Informationen zur Händler-Identifizierung notwendig. Die Felder sind im Folgenden definiert und müssen für jeden uploadRequest angegeben werden.

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Händler-User

login

string

100

ja

Händler-User (Die in Ihrem Account hinterlegte E-Mail Adresse)

Passwort

password

string

100

ja

Passwort des Händler-Users

Sprache

language

string

100

nein

Sprache, wenn nicht belegt wird "de" geliefert

Multiplier

multiplierId

string

100

nein

Das Feld muss von einzelnen Händlern nicht verwendet werden oder es kann „UNKNOWN“ gesetzt werden.

Sollten Sie als Anbieter eines Multi-Shop-Systems eine Anbindung für Ihr System entwickeln, wenden Sie sich bitte an den Support, um eine eigene multiplierId zu erhalten.

Mögliche MultiplierIds befinden sich im Anhang C.

nach oben


 

3 Response abfragen

3.1 Fachliche Beschreibung

Wurde ein Request an die asynchrone Schnittste geschickt, so enthält die Response eine RequestId. Über diese Id kann der Verarbeitungsstand und das Ergebnis der Verarbeitung abgefragt werden.


3.2 Definitionen

Folgende Angaben sind für das Herunterladen der Response notwendig. Die Felder, die zwingend notwendig sind, haben in der Spalte "Pflichtfeld" ein "ja". Felder, die keine Pflichtfelder sind und nicht geliefert werden, werden nicht übermittelt. Die Tabelle enthält die Attribute, die mit der technischen Beschreibung in data.xsd korrespondieren und jeweils eine kurze Inhaltsbeschreibung.

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

RequestId

requestId

string

100

ja

Eindeutige Id, welche einen Request identifiziert

Status oder Response

onlyStatus

boolean

 

nein

Auswahl der Responseelemente:

true – es wird nur der Verarbeitungsstatus des Requests zurück gegeben

false – es wird die Response zurück gegeben, wenn diese bereits vorhanden ist ansosten der Status

Wenn nichts übergeben wird, dann wird standardmäßig nur der Status übergeben.

nach oben


 

4 Produkt-Kategorien Händler-Shop

4.1 Fachliche Beschreibung

Ein Händler des Allyouneed Onlineshopping-Marktplatzes hat automatisch einen eigenen Händler-Shop. Auf diesem werden alle Produkte gezeigt, die der Händler anbietet. Jeder Händler hat die Möglichkeit eigene Shopkategorien zu nutzen. Er muss hierfür zuerst Kategorien für seine Produkte festlegen und diese in den Shop laden. Anschließend können Produkte mit eigenen Beschreibungen und Bildern eingefügt werden. Die Shop-Kategorien können hierarchisch aufgebaut werden. Kategorien im Händler-Shop können wieder gelöscht werden. Dies ist aber nur möglich, wenn sich in den betroffenen Kategorien bzw. in Unterkategorien keine Produkte befinden. Möchte ein Händler eigene Kategorien in seinem Shop nutzen, so muss dies an seinem Shop gekennzeichnet werden. Dazu ist es notwendig, dies vom Allyouneed Händler-Service aktivieren zu lassen. Ansonsten wird für die angebotenen Produkte die Kategorien-Struktur vom Marktplatz zu Grunde gelegt und der entsprechend mit Angeboten gefüllte Teil dieser Struktur im Händlershop angezeigt. Shopkategorien sind optional, trotzdem bleibt die Marktplatzkategorie eine Pflichtangabe.


4.2 Definitionen

Folgende Angaben werden für die Anlage von Kategorien benötigt. Die Beschreibung bzw. ein hierarchisches Modell ist für die Anlage optional nicht notwendig. Die Tabelle enthält die Attribute, die mit der technischen Beschreibung in common.xsd und product.xsd korrespondieren und jeweils eine kurze Inhaltsbeschreibung:

 

Kategorien anlegen:

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Kategorie ID

code

string

100

ja

Eindeutige ID der Shop-Kategorie: Jede Kategorie besitzt eine eindeutige KategorieID, die aber im Shop nicht sichtbar ist. Sie dient dazu die Kategorie zu identifizieren.

Kategorie Name

name

string

100

ja

Name der Produktkategorie: Dieser Name wird im Shop angezeigt. Jede Oberkategorie und alle Unterkategorien einer Oberkategorie müssen einen eindeutigen Namen haben.

Kategorie Beschreibung

shortDescription

string

100

nein

Kurze Kategoriebeschreibung

Übergeordnete Kategorie

parent

string

100

nein

Id der übergeordneten Kategorie: Diese Kategorie muss entsprechend vorher angelegt werden, was im gleichen "uploadRequest" möglich ist.

nach oben


 

5 Download der Kategorien

5.1 Fachliche Beschreibung

Für den Marktplatz und für den eigenen Händlershop bietet Allyouneed die Möglichkeit, eine Übersicht der Kategorien herunterzuladen. Dieser Download erfolgt über den "downloadRequest", dabei ist es lediglich notwendig zwischen Marktplatz und Händlershop zu unterscheiden. Das Ergebnis enthält zusätzlich zu den Kategorien mit möglicher Hierarchie auch die Namen und Beschreibungen hinterlegter Attribute, die für die Suche von Produkten bzw. für die Facettierung verwendet werden.


5.2 Definitionen

Folgende Angaben sind für den Download von Kategorien notwendig. Die Tabelle enthält die Attribute, die mit der technischen Beschreibung im folgenden Kapitel korrespondieren und jeweils eine kurze Inhaltsbeschreibung

Kategorien abfragen

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Katalogstruktur

catalogstructure

string

 

nein

Gibt die Katalogstruktur aus: Mit "marketplace" für den Marktplatz, mit "shop" für den Händlershop. Sollte kein Wert enthalten sein, so wird der Händlershop geliefert.

Provision

rate

boolean

 

nein

Mit diesem Attribut wird festgelegt, ob die Provisionen mitgeliefert werden sollen. Bei Nichtangabe werden keine Provisionen übergeben.

 

Rückmeldung Kategorie-Beschreibung

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Kategorie ID

code

string

100

ja

Eindeutige ID der Shop-Kategorie. Jede Kategorie besitzt eine eindeutige Kategorie, die aber im Shop nicht sichtbar ist. Sie dient dazu die Kategorie zu identifizieren.

Kategorie Name

name

string

100

ja

Name der Produktkategorie. Dieser Name wird im Shop angezeigt.

Kategorie Beschreibung

shortDescription

string

100

nein

Kurze Kategoriebeschreibung

Übergeordnete Kategorie

parent

string

100

nein

Kategorie ID der Übergeordneten Kategorie.

Gesperrte Kategorie

deprecated

boolean

 

nein

Wenn "true" dann darf diese Kategorie nicht für den Produk-Upload verwendet werden. Daher werden nur Kategorien mit "false" übertragen.

Provision

commissionRate

String

100

 

Beinhaltet die Veraufsprovision für die Kategorie. Das Element wird nur mitgeliefert, wenn im Requtest rate = true angegeben wurde. Je nach vereinbartem Tarif kann es hier zu Abweichungen kommen. Bitte klären Sie mit dem Händlerservice ab, welcher Tarif bei Ihnen eingestellt ist und ob es bei einzelnen Kategorien Abweichungen gibt.

 

 

nach oben

6 Produktbeschreibung

6.1 Fachliche Beschreibung

Um Produkte zu listen müssen productDescriptions mit den wichtigsten Informationen hochgeladen werden. Dabei werden Daten wie Name, Beschreibung, Bilder usw. übergegeben. Für die Änderung oder Aktualisierung bereits geladener Produkte ist immer eine vollständige Produktbeschreibung notwendig. Einzelne Felder können nicht aktualisiert werden. Produkte, die auf den Marktplatz geladen wurden, können auch wieder gelöscht werden. Dabei wird das Angebot zu diesem Produkt vom System ebenfalls gelöscht.


6.2 Definitionen

Folgende Angaben für jedes einzelne Produkt, das angeboten werden soll, notwendig. Die Tabelle enthält die Attribute, die mit der technischen Beschreibung im folgenden Kapitel korrespondieren und jeweils eine kurze Inhaltsbeschreibung:

Produkt hochladen

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Händler Produkt ID

productId

string

100

ja

Interne und eindeutige Artikelnummer des Händlers

Allyouneed Produkt ID

meinPaketId

string

100

nein

Eindeutige Allyouneed Artikelnummer

European article number

ean

string

13

nein

Die „European Article Number“,  EAN des Produktes; Bei Büchern ISBN-13.

Hersteller

manufacturerName

string

100

nein

Name des Herstellers*

Hersteller Artikelnummer

manufacturerPN

string

100

nein

Artikelnummer des Herstellers

Produkt Name

name

string

100

ja

Name des Produktes

Produktbeschreibung kurz

shortDescription

string

200

ja

Kurze Produktbeschreibung. Der Inhalte sollte stets im CDATA-Tag übergeben werden.**

Produktbeschreibung lang

longDescription

string

4000

nein

Ausführliche Beschreibung des Produktes. Der Inhalte sollte stets im CDATA-Tag übergeben werden.**

Bild

image

image

512

nein

URL zu einem Produktbild des Händlers. Maximale Größe 2 MB. Die URL muss mit http:// oder https:// beginnen.

Marktplatz Kategorie

marketplaceCategorie

string

100

ja

Produktkategorie auf dem Marktplatz

Händler-Shop Kategorie

shopCategorie

string

100

nein

Produktkategorie im eigenen Händler-Shop*

Attribut Code

code

string

100

ja

Eindeutige ID des Attributes. Dieser Code identifiziert für jeden Händler jedes Attribut eindeutig.

Attribute Name

name

string

100

nein

Name des Merkmals des Produktes wie Abmessungen, Farbe etc.

Attribut Wert

value

string

100

nein

Wert des Attributes

Attribut Einheit

unit

string

100

nein

Einheit des Attributwerts

Produktdatenblatt

productDataSheetUrl

 string

100

nein

URL für die Übergabe des Produktdatenblattes. Es werden nur PDFs mit der max. Größe von 2,5 MB akzeptiert. Die URL muss https beginnen. Weiterleitungen sind nicht erlaubt.

Energielabel

energyClassLabelUrl

String

100

nein

URL für die Übergabe des Labels. Es werden folgende Dateitypen akzeptiert: png, gif und jpeg. Die URL muss mit http/https beginnen. Weiterleitungen sind nicht erlaubt.

* Bei der Referenz zu den Händler-Shop Kategorien ist zu beachten, dass diese angelegt sind.
** die zugelassenen HTML-Tags siehe Anhang B

nach oben


 

6.3 Beispiel Produktbeschreibung und Angebot

 

 

6.4 Energieverbrauchskennzeichnung

Sie können die Energieeffizienzklassen-Information mit Hilfe von Attributen übermitteln. Erforderlich hierfür ist die Übergabe folgender Attribute:

  • Energieklasse über den Attribut-Typ strict_Energieklasse
  • Produktgruppe über den Attribut-Typ strict_Produktgruppe

Darüber hinaus können Sie zusätzlich optional übergeben:

  • EU-Energielabel den Attribut-Typ energyClassLabelUrl
  • Produktdatenblatt den Attribut-Typ productDataSheetUrl

Bei Leuchten, die mit einem oder mehreren Leuchtmitteln geliefert werden, können Sie auch einen Klassenbereich angeben, z.B. Klassen A++ bis D. Dies erfolgt über die Attribute strict_Energieklasse_von und strict_Energieklasse_bis.

 

Werte für das Attribut strict_Energieklasse (von/bis)

A+++

A++

A+

A

B

C

D

E

F

G

 

Werte für das Attribut strict_Produktgruppe

Beschreibung

Wert

Haushaltsgeschirrspülmodelle

1

Haushaltskühlgerätemodelle

2

Haushaltswaschmaschinenmodelle

3

Fernsehgeräte

4

Haushaltswäschetrocknermodelle

5

Lampen und Leuchten

6

Luftkonditioniermodelle

7

Staubsauger

8

Backöfen

9

Dunstabzugshauben

10

Warmwasserbereiter

11

Warmwasserspeicher

12

Raumheizgeräte

13

Kombiheizgeräte

14

Verbundanlagen aus Warmwasserbereitern und Solareinrichtungen

15

Verbundanlagen aus Warmwasserspeicher und Solareinrichtungen

16

Verbundanlagen aus Raumheizgeräten, Temperaturreglern und Solareinrichtungen

17

Verbundanlagen aus Kombiheizgeräten, Temperaturreglern und Solareinrichtungen

18

 


 

6.5 Weitere strikte Attribute

Strikte Attribute dienen der genauen Identifikation von Produkteigenschaften, damit lassen sich diese deutlich einfach weiter erkennen und weiter verarbeiten. Dabei ist der Attributcode als auch die möglichen Werte fest vorgegeben. Die Attribute sind sehr wichtig für den Export zu Produktsuchmaschinen und Preisvergleichsportalen. Das Attribut zur Kennzeichnung von „B-Ware“ dient der Beschreibung des Zustandes von Produkten. Diese Kennzeichnung ist Voraussetzung für die Aufnahme Ihrer Produkte in den B-Ware Channel, unseren Vermarktungskanal für entsprechende Produkte.

Element

Wert

Code

strict_B-Ware

Name

Zustand

Value

[ B-Ware, Refurbished, Verpackungsschäden, Demoware ]

 

Beispiel XML

<attribute code=“strict_B-Ware“>
<name>Zustand</name>
<value>B-Ware</value>
</attribute>

Das Attribut strict_Altersklasse wird genutzt um die Zielgruppe dem Alter nach zu definieren.

Element

Wert

Code

strict_Altersklasse

Name

Altersklasse

Value

[ Neugeborene, Säuglinge, Kleinkinder, Kinder, Erwachsene ]

 

Das Attribut strict_Geschlect wird genutzt um die Zielgruppe dem Geschlecht nach zu definieren.

Element

Wert

Code

strict_Geschlecht

Name

Geschlecht

Value

[ Herren, Damen, Unisex ]

 


 

6.6 Empfohlene Attribute für die Kategorien „Wohnen“

Nachfolgend finden Sie die empfohlenen Attribute für die Kategorien Wohnen. Diese ermöglichen es die jeweiligen Produkte korrekt zu beschreiben und Allyouneed.com kann die Produkte an Produktsuchmaschinen und Preisvergleichsportale übergeben.


 

7 Produkt-Varianten

Um ein Produkt in verschiedenen Varianten auf Allyouneed verknüpft einzustellen, müssen Sie folgende zwei Schritte durchführen:

Schritt 1: Definition der Varianten-Gruppe

Die Varianten-Gruppe repräsentiert alle verfügbaren Varianten eines Produktes auf dem Marktplatz. Sie geben in den Produkten, welche als Variante gruppiert werden sollen, eine entsprechende Variantengruppe mit eindeutigem Code mit. Die Variantengruppe kann sowohl explizit mit einem Request angelegt werden, als auch implizit. Dabei wird die Variantengruppe vor der ersten productDescription angelegt.

Schritt 2: Angabe der Variantenattribute

Definieren Sie die Attribute, aus denen die Variante bestehen soll. Dafür machen Sie aus dem vorhandenen, normalen „Attribute“ jeweils ein „VariantAttribute“. Für alle Produkte einer Variantengruppe müssen natürlich die selben Variantenattribute angegeben werden.


 

7.1 Explizite Definition einer Varianten-Gruppe

Folgende Angaben sind für die Anlage von Varianten-Gruppen für ein Produkt notwendig. Die Tabelle enthält die Attribute, die mit der technischen Beschreibung in dem folgenden Kapitel korrespondieren und jeweils eine kurze Inhaltsbeschreibung:

 

Varianten-Gruppe

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Varianten Gruppe

code

string

100

ja

Eindeutige Identifikation der Varianten-Gruppe, z.B. "Levis501"

Konfiguration-Code

configuration

string

100

ja

Eindeutige Referenz auf eine bestehende Allyouneed -Konfiguration.

Titel der Gruppe

title

string

4000

nein

Titel der Gruppe, z.B. "Levis Jeans 501"

 


 

7.2 Pflichtangaben Produktbeschreibung mit Variante

Folgende Angaben sind für eine Produktbeschreibung mit Varianten notwendig. Es handelt sich um die Beschreibung (analog zu Kapitel 6.2) erweitert um die Varianten-Gruppe.Die relevanten XML-Element sind hervorgehoben. Die Tabelle enthält die Werte, die mit der technischen Beschreibung in dem folgenden Kapitel korrespondieren und jeweils eine kurze Inhaltsbeschreibung:

 

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Händler Produkt ID

productId

string

100

ja

Interne und eindeutige Artikelnummer des Händlers.

Allyouneed Produkt ID

meinPaketId

string

100

nein

Eindeutige Allyouneed Artikelnummer

European article number

ean

string

13

nein

Die „European Article Number“,  EAN des Produktes; Bei Büchern ISBN-13

Hersteller

manufacturerName

string

100

nein

Name des Herstellers*

Hersteller Artikelnummer

manufacturerPN

string

100

nein

Artikelnummer des Herstellers

Varianten Gruppe

variantGroupCode

string

100

nein

Varianten Gruppe – Wenn die Variantengruppe implizit erstellt werdn soll, dann muss variant = true angegeben werden. Ansonsten muss die Variantengruppe explizit angelegt werden.

Produkt Name

name

string

100

ja

Name des Produktes

Produktbeschrei-bung kurz

shortDescription

string

200

ja

Kurze Produktbeschreibung

Produktbeschrei-bung lang

longDescription

string

4000

nein

Ausführliche Beschreibung des Produktes

Bild

image

image

512

nein

URL zu einem Produktbild des Händlers. Maximale Größe 2 MB

Marktplatz Kategorie

marketplaceCategorie

string

100

ja

Produktkategorie auf dem Marktplatz

Händler-Shop Kategorie

shopCategorie

string

100

nein

Produktkategorie im eigenen Händler-Shop**

Attribut Code

code

string

100

ja

Eindeutige ID des Attributes. Dieser Code identifiziert für jeden Händler jedes Attribut.

Attribut Variant

variant

boolean

-

Nein

Muss auf „true“ gesetzt werden, wenn es ein Variantenattribut sein soll und die Variantengruppe implizit angelegt werden soll.

*Attribut Name

name

string

100

nein

Bestimmte Merkmale des Produktes wie Abmessungen, Farben etc.

*Attribut Wert

value

string

100

nein

Wert des Attributes

*Attribut Einheit

unit

string

100

nein

Einheit des Attributwerts

* Hierbei kann es sich sowohl um Varianten-Attribute als auch um weitere Produkt-Attribute handeln. ** Wird dieses Kennzeichen für mehr als ein Produkt einer Varianten-Gruppe geliefert so wird es immer überschrieben.


 

7.3 Liste der Verfügbaren Variantenattribute

Hier finden Sie die Liste der verfügbaren Variantenattribute Bitte achten Sie auf Groß- und Kleinschreibung und die exakte Schreibweise, damit auch die Farcetten etc. auf dem Marktplatz funktionieren und Ihre Produkte gut gefunden werden können.

 

Attributname ( I )

Attributname ( II )

Farbe

Abteilung

Größe

Ärmellänge

Abmessung

Fassung

Anzahl

Hauptmaterial

Breite

Herstellungsland

Format

Geschwindigkeitsindex 

Material

Höhe

Länge

Jahr

Geschmacksrichtung 

Kollektion

Beschriftung

Kragenform

Modell

Marke

Plattform

Motiv

Radius

Optik

Stärke

Sets

Durchmesser

Sprache

Zylinder

Stil

Achse

Typ

Brustumfang

Mahlgrad

Cup

Gewicht

nach oben


8 Produktangebote

8.1 Fachliche Beschreibung

Nachdem Daten wie Name, Attribute, Bilder usw. übergeben wurden, ist es notwendig Daten zu Preisen und der Verfügbarkeit zu übertragen. Diese Daten werden mit den Produktangeboten übergeben. 8.2 Definitionen Folgende Angaben sind für jedes einzelne Produkt, das angeboten werden soll, möglich. Die Felder, die zwingend notwendig sind, haben in der Spalte „Pflichtfeld“ ein „ja“. Felder, die keine Pflichtfelder sind und nicht geliefert werden, werden nicht gesetzt oder werden mit einem Vorgabewert befüllt (siehe Spalte „Beschreibung“). Die Tabelle enthält die Attribute, die mit der technischen Beschreibung in common.xsd und product.xsd korrespondieren, und jeweils eine kurze Inhaltsbeschreibung:

 

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Händler Produkt ID

productId

string

100

ja

Interne und eindeutige Artikelnummer des Händlers.

Allyouneed Produkt ID

meinPaketId

string

100

nein

Eindeutige Allyouneed Artikelnummer. Diesen Wert nicht übertragen.

European article number

ean

string

13

nein

Die „European Article Number“,  EAN des Produktes; Bei Büchern ISBN-13.

 

Hersteller

manufacturerName

string

100

nein

Name des Herstellers

Hersteller Artikelnummer

manufacturerPN

string

100

nein

Artikelnummer des Herstellers

Verkaufspreis

price

double

 

ja

Einzelpreis incl. Der gesetzlichen MwSt. mit maximal zwei Nachkommastellen und einem Punkt als Dezimaltrennzeichen.

Einheitspreis

unitprice

double

 

nein

Preis pro Einheit

Einheit

unit

string

100

nein

Einheit der Produktmenge:
Stück = „per_piece“

Kilo = “per_1kg

Liter =”per_1l”

Kubikmeter =“per_1m3“

Meter =“per_1m“

Quadratmeter =”per_1m2”

Gramm =”per_100g”

Milliliter =”per_100ml

Steuer Klassifikation

taxGroup

taxGroup

 

nein

Die im Verkaufspreis enthaltene Mehrwertsteuer. „Standard“ (aktuell 19%), „Reduced“ (aktuell 7%) und „Free“ für Artikel ohne Mehrwertsteuer. Wird dieses Feld nicht gefüllt so wird „Standard“ gesetzt.

Verfügbarkeit

availability

integer

 

ja

Verfügbare Stückzahl für dieses Produkt. Die Stückzahl wird bei jedem Verkauf automatisch nach unten gezählt. Ist die Stückzahl 0 so wird das Produkt als ausverkauft angezeigt. Wenn ein negativer Wert im Request übergeben wird, dann wird im System 0 als neue Verfügbarkeit gesetzt.

Start Datum

startDate

dateTime

 

nein

Datum, ab dem das Produkt für eine Kundenbestellung zur Verfügung steht, d.h. auf dem Marktplatz zu diesem Händler sichtbar wird. Das Datum muss in folgendem Format geliefert werden: YYYY-MM-DDThh:mm:ss *

Ende Datum

endDate

dateTime

 

nein

Datum, ab dem das Produkt nicht mehr zur Verfügung steht, d.h. es ist weder sichtbar noch kann es für eine Bestellung ausgewählt werden. Das Datum muss in folgendem Format geliefert werden: YYYY-MM-DDThh:mm:ss *

Lieferzeit

deliverytime

integer

 

nein

Die Lieferzeit bezieht sich auf den Zeitraum, den Sie brauchen um die Ware zu verschicken. Sollten Sie keine Lieferzeit mitschicken, dann wird automatisch der Wert 3 gesetzt. In diesem Fall senden Sie das Element deliveryTime nicht mit. Die max. Lieferzeit beträgt 29 Tage, außer für Speditionsware, hier ist die Lieferzeit 62 Tage.

Händler-Shop Kategorie

shopCategory

categoryRef

100

nein

Produktkategorie im eigenen Händler-Shop**

Varianten Gruppe

variantGroupCode

string

100

nein

Code der Variantengruppe

Fixed Product

useAsFixedProduct

boolean

 

nein

Fixed-Product für Suchergebnis; Wird es für mehr als ein Produkt geliefert, ist das letzte Produkt das „FixedProduct“; Standard ist „false“

Attribut Code

code

string

100

ja

Eindeutige ID des Attributes. Dieser Code identifiziert für jeden Händler jedes Attribut.

Attribute Name

name

string

100

nein

Name des Merkmals des Produktes wie Abmessungen, Farben etc.

Attribut Wert

value

string

100

nein

Wert des Attributes

Attribut Einheit

unit

string

100

nein

Einheit des Attributwerts

Versandkosten

deliveryCost

double

 

nein

Angabe für spezifische Versandkosten für dieses Produkt

Fixe Versandkosten

fixedCost

boolean

 

nein

Angabe, ob die Versandkosten für dieses Produkt immer voll berechnet werden sollen, unabhängig von Staffeln etc.. Benötigt „dispatchType“ BULK_GOODS oder FORWARDING_AGENCY

Lieferart

dispatchType

String

 

nein

Lieferart des Produktes. Folgende Werte sind möglich:

BULK_GOODS – Sperrgut

FORWARDING_AGENCY – Speditionsware***

BOOK_RATE – Büchersendung

CONSIGNMENT_OF_GOODS – Warensendung

DOWNLOAD – Produkt wird als Download zur Verfügung gestellt

EMAIL – Produkt wird per E-Mail zugestellt

LETTER – Produkt wird als Standardbrief zugestellt

* Das Format dateTime ist wie folgt spezifiziert "YYYY-MM-DDThh:mm:ss" wobei: - YYYY Jahr - MM Monat - DD Tag - T Kennzeichnung, dass ab hier das Zeitformat beginnt - hh Stunden - mm Minuten - ss Sekunden bedeutet. ** Shopkategorien müssen vor der Nutzung angelegt sein. *** Bei Speditionsware wird die Telefonnummer des Kunden abgefragt und Ihnen später angezeigt um die Lieferung planen zu können.

nach oben


9 Einstellen von internationalen Preisen

9.1 Fachliche Beschreibung

Analog zum Upload von normalen Angeboten auf Allyouneed können Sie nun internationale Preise hochladen. Neben den gewohnten Angaben wie ProduktId und Preis müssen Sie lediglich noch eine Versandzone oder ein Zielland angeben. Versandzonen (also das Zusammenfassen von mehreren Ländern zu einer Gruppe) können über den Händleraccount gepflegt werden. Selbstverständlich sind die Funktionen „Preis pro Einheit“, „Versandkosten pro Produkt“ und „Versandart“ ebenfalls verfügbar. Laden Sie internationale Angebote hoch, so bekommt ein Kunde mit dem entsprechenden Zielland genau die zutreffenden mit exakt diesen Preisen und Versandkosten etc. angezeigt. Lediglich die Verfügbarkeit muss nicht mitgegeben werden. Die Verfügbarkeit richtet sich immer nach dem Standard-Angebot für Deutschland. Daher muss auch immer zu jedem Produkt ein Standard-Angebot vorhanden sein.


9.2 Definition Internationale Preise

Folgende Werte können mitgegeben werden:

 

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Internationales Angebot Container

internationalPrices

container

-

ja

Container für ein internationales Angebot

Händler Produkt ID

productId

string

100

ja

Interne und eindeutige Artikelnummer des Händlers.

Angebotszone

deliveryZone

string

100

ja*

Lieferzone des Angebotes

Angebotsland

Country

string

2

ja*

Liederland des Angebotes (Nach ISO 3166-1)

Internationaler Preis

price

double

 

Ja

Einzelpreis (international) incl. Der gesetzlichen MwSt. mit maximal zwei Nachkommastellen und einem Punkt als Dezimaltrennzeichen.

Einheitspreis

unitprice

double

 

nein

Preis pro Einheit (international)

Einheit

unit

string

100

nein

Einheit der Produktmenge:
Stück = „per_piece“

Kilo = “per_1kg

Liter =”per_1l”

Kubikmeter =“per_1m3“

Meter =“per_1m“

Quadratmeter =”per_1m2”

Gramm =”per_100g”

Milliliter =”per_100ml

Versandkosten

deliveryCost

double

 

nein

Angabe für spezifische Versandkosten für dieses Produkt für den internationalen Versand

Fixe Versandkosten

fixedCost

boolean

 

nein

Angabe, ob die Versandkosten für dieses Produkt immer voll berechnet werden sollen, unabhängig von Staffeln etc.. Benötigt „dispatchType“ BULK_GOODS oder FORWARDING_AGENCY

Lieferart

dispatchType

String

 

nein

Lieferart des Produktes. Folgende Werte sind möglich:

BULK_GOODS – Sperrgut

FORWARDING_AGENCY – Speditionsware

BOOK_RATE – Büchersendung

CONSIGNMENT_OF_GOODS – Warensendung

DOWNLOAD – Produkt wird als Download zur Verfügung gestellt

EMAIL – Produkt wird per E-Mail zugestellt

LETTER – Produkt wird als Standardbrief zugestellt

*Es muss entweder eine Angebotszone oder ein Angebotsland mitgegeben werden


 

9.3 Definition Internationale Angebote löschen - internationalPriceDeletion

Selbstverständlich können Sie auch internationale Angebote löschen, sollten Sie ein Produkt nicht mehr ins Ausland verschicken wollen.

Folgende Werte können mitgegeben werden:

 

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Internationales Angebot löschen

internationalPriceDeletion

container

-

ja

Container für das Löschen internationaler Preise

Händler Produkt ID

productId

string

100

ja

Interne und eindeutige Artikelnummer des Händlers.

Angebotszone

deliveryZone

string

100

ja*

Lieferzone des Angebotes

Angebotsland

Country

string

2

ja*

Liederland des Angebotes (Nach ISO 3166-1)

*Es muss entweder eine Angebotszone oder ein Angebotsland mitgegeben werden

nach oben


10 Download der Produktangebote

10.1 Fachliche Beschreibung

Für den Händler bietet Allyouneed die Möglichkeit eine Übersicht der von ihm angebotenen Produkte herunterzuladen. Dieser Download erfolgt über den "downloadRequest". Es können sowohl alle Angebote (keine Angabe von productIds) abgefragt werden, als auch eine Auswahl an Angeboten.


10.2 Definitionen

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Produktnummer

productId

string

100

nein

Identifiziert eine productOffer, die heruntergeladen werden soll.

 

Rückmeldung der Produktangebote Bei der Rückmeldung werden folgende Attribute geliefert. Die Tabelle enthält die Attribute, die mit der technischen Beschreibung in dem folgenden Kapitel korrespondieren und jeweils eine kurze Inhaltsbeschreibung:

 

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Händler Produkt ID

productId

string

100

ja

Interne und eindeutige Artikelnummer des Händlers

Allyouneed Produkt ID

meinPaketId

string

100

nein

Eindeutige Allyouneed Artikelnummer

European article number

Ean

string

13

nein

Die "European Article Number", EAN des Produktes.

Für Bücher ISBN-13.

Hersteller

manufacturerName

string

100

nein

Name des Herstellers*

Hersteller Artikelnummer

manufacturerPN

string

100

nein

Artikelnummer des Herstellers

Einheitspreis

unitprice

double

 

nein

Preis pro Einheit

Einheit

Unit

string

100

nein

Einheit der Produktmenge:
Stück = "per_piece"

Kilo = "per_1kg"

Liter ="per_1l"

Kubikmeter ="per_1m3"

Meter ="per_1m"

Quadratmeter ="per_1m2"

Gramm ="per_100g"

Milliliter ="per_100ml"

Steuer Klassifikation

taxGroup

taxGroup

 

nein

Die im Verkaufspreis enthaltene Mehrwertsteuer. "Standard" (aktuell 19%), "Reduced" (aktuell 7%) und "Free" für Artikel ohne Mehrwertsteuer. Wird dieses Feld nicht gefüllt so wird "Standard" gesetzt.

Verfügbarkeit

availability

integer

 

ja

Verfügbare Stückzahl für dieses Produkt. Die Stückzahl wird bei jedem Verkauf automatisch nach unten gezählt. Ist die Stückzahl 0 so wird das Produkt als ausverkauft angezeigt.

Start Datum

startDate

dateTime

 

nein

Datum, ab dem das Produkt für eine Kundenbestellung zur Verfügung steht, d.h. auf dem Marktplatz zu diesem Händler sichtbar wird. Das Datum muss in folgendem Format geliefert werden: YYYY-MM-DDThh:mm:ss **

Ende Datum

endDate

dateTime

 

nein

Datum, ab dem das Produkt nicht mehr zur Verfügung steht, d.h. es ist weder sichtbar noch kann es bestellt werden. Das Datum muss in folgendem Format geliefert werden: YYYY-MM-DDThh:mm:ss **

Händler-Shop Kategorie

shopCategory

categoryRef

100

nein

Produktkategorie im eigenen Händler-Shop***

* Wenn Sie eine Herstellerartikelnummer angeben möchten, so ist auch die Angabe des Herstellernamens notwendig. ** Das Format dateTime ist wie folgt spezifiziert "YYYY-MM-DDThh:mm:ss" wobei: - YYYY Jahr - MM Monat - DD Tag - T Kennzeichnung, dass ab hier das Zeitformat beginnt - hh Stunden - mm Minuten - ss Sekunden *** Wird nur geliefert wenn der Händler eine eigene Kategorien-Struktur in seinem Shop definiert hat.

nach oben


11 Löschen

11.1 Fachliche Beschreibung

Bei Allyouneed können Produktbeschreibungen, Produktangebote und Shopkategorien gelöscht werden. Das Löschen wird von Allyouneed verhindert solange Bestellungen zu einem bestimmten Produkt offen sind. Ebenso können keine Kategorien gelöscht werden, wenn in diesen bzw. den Unterkategorien noch Produkte enthalten sind.


11.2 Definitionen

Folgende Angaben sind für den Download von Kategorien notwendig. Die Tabelle enthält die Attribute, die mit der technischen Beschreibung in dem folgenden Kapitel korrespondieren und jeweils eine kurze Inhaltsbeschreibung:

 

Kategorien löschen

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Katalogstruktur

catalogstructure

string

 

nein

Für den Marktplatz muss hier der "marketplace" angegeben werden, für den eigenen Shop kann "shop" angegeben werden, sollte kein Wert enthalten sein, so wird der Händlershop geliefert.

 

Produkte löschen

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Händler Produkt ID

productId

string

100

ja

Interne und eindeutige Artikelnummer des Händlers.

Allyouneed Produkt ID

meinPaketId

string

100

nein

Eindeutige Allyouneed Artikelnummer

European article number

ean

string

13

nein

Die „European Article Number“, EAN des Produktes. Für Bücher ISBN-13

Hersteller

manufacturerName

string

100

nein

Name des Herstellers

Hersteller Artikelnummer

manufacturerPN

string

100

nein

Artikelnummer des Herstellers

nach oben


12 Fachlicher Hintergrund und Übersicht über die Schnittstellen des Bestellvorgangs

Zwischen Allyouneed, Kunden und Händlern finden unterschiedliche Kommunikations-Schritte statt. Dieser Prozess wird durch eine Kundenbestellung auf dem Marktplatz ausgelöst. Ein Kunde kann ein oder mehrere Produkte bei einem oder mehreren Händlern bestellen. Dieses erfolgt, wenn der Kunde mit seinem Warenkorb "zur Kasse" geht und seine Bestellung abschließt.

Allyouneed stellt für jeden Händler die eingegangenen Bestellungen als "Order" zum Abruf bereit. Ein Händler kann den Zeitraum über den er die Order abruft selbst wählen, ebenso die Abruf-Frequenz. Eine Order kann beliebig oft abgerufen werden. Dies kann über den Zeitraum erfolgen. In Ausnahmefällen kann es vorkommen, dass eine Bestellung bis zu 24 Stunden in der Betrugsprüfung verbleibt und erst dann freigegeben wird. Bestellungen, die per Vorkasse bezahlt wurden, sind für den Händler erst ab dem Zahlungseingang abrufbar. Sobald die bestellte Ware vom Händler versandt wurde, übermittelt er diese Information an Allyouneed. Ein Händler kann mit der Versandinformation gleichzeitig die Tracking-Daten der Lieferung schicken, sofern diese bereits bekannt sind.

Die Tracking-Informationen können auch nachträglich übermittelt werden. Nach Bekanntgabe der Versandinformation müssen Lieferung und Rechnung an den Kunden geschickt werden. Eine explizite Versandmitteilung durch den Händler ist nicht notwendig, sie erfolgt automatisch durch Allyouneed.com Ein Kunde kann aus unterschiedlichen Gründen die Lieferung oder bei mehreren Produkten auch nur einen Teil davon an den Händler zurück schicken. Dies kann mit oder ohne Ankündigung passieren. Der Händler bewertet die Retoure und gibt diese Information an Allyouneed weiter.

Von dort wird die entsprechende Rückabwicklung ausgelöst. Ein Händler kann Produkte, die nicht mehr lieferbar sind, stornieren. Es ist möglich die komplette Bestellung oder bei mehreren Produkten in einem Bestellvorgang auch nur einen Teil davon zu stornieren. Der Händler übermittelt die Storno-Information an Allyouneed und Allyouneed informiert den Kunden. Für den Kunden ist kein eigener Stornoprozess vorgesehen. Er kann lediglich anfragen, ob eine Stornierung durchgeführt werden kann.

Der Händler erhält diese Information per Email und kann, falls es im Versandablauf noch möglich ist, den Stornoprozess starten. Sollte der Stornowunsch des Kunden nicht berücksichtigt werden, so kann der Kunde die Möglichkeit der Retoure nutzen. Es ist möglich dem Kunden einen bestimmten Betrag gut zu schreiben, damit können z. B. Verpackungsschäden oder Verspätungen reguliert werden. Zur Übersicht des gesamten Bestellvorgangs sind die einzelnen Prozess-Schritte für den Händler in folgender Tabelle zusammengefasst. Die detaillierte und technische Beschreibung ist den Kapiteln 16 bis 20 zu entnehmen:

 

Prozess-Schritte

Beschreibung

Abruf der Bestellungen

Der Händler muss in regelmäßigen Abständen (z.B. alle 60 min) neue Bestellungen abfragen. Liegen Bestellungen vor werden diese dem Händler in einer XML-Datei bereit gestellt.

Versandmeldung

Die bestellte Ware wird vom Händler an den Kunden verschickt. Dies muss an Allyouneed gemeldet werden.

Storno

Artikel die nicht geliefert werden können müssen als Storno an Allyouneed geliefert werden

Tracking-Informationen

Sind die Tracking-Informationen nicht in der Versandmeldung enthalten, so können diese nachträglich übermittelt werden

Retoure

Erhält ein Händler vom Kunden die Ware zurück, so muss dies an Allyouneed gemeldet werden. Nach dieser Meldung beginnt die Rückabwicklung der Bezahlung.

Gutschrift

Es ist möglich dem Kunden gewisse Beträge gutzuschreiben, um z. B. Reklamationen zu regulieren.

Für die technische Beschreibung der API gibt es zwei xsd-Dateien, common.xsd und orders.xsd. Die common.xsd enthält globale Definitionen, die auch in weiteren Bereichen der Händler-API verwendet werden. Die orders.xsd enthält die in den folgenden Kapiteln beschriebenen Requests sowie spezifische Definitionen dieser Schnittstelle.

nach oben


13 Bestellung

13.1 Fachliche Beschreibung

Die Bestellung in diesem Kapitel betrachtet den Einkauf von Waren auf dem Marktplatz und den einzelnen Händler-Shops auf Allyouneed. Geht ein Kunde mit einem oder mehreren Produkten im Warenkorb zur Kasse, so löst er damit den Bestellvorgang aus. Ist dieser Vorgang abgeschlossen, dann kann der Händler die vollständigen Bestellinformationen in Form einer XML-Datei abrufen. Der Händler kann entweder alle oder nur die offenen Bestellungen über einen zu wählenden Zeitraum abrufen bzw. sind einzelne Bestellungen anhand der OrderId oder seiner internen Händler-Bestellnummer abrufbar.

Die Datei enthält alle notwendigen Informationen zur Bestellung und der Händler ist nun in der Pflicht die entsprechende Ware versandfertig zu machen, eine Rechnung an den Kunden zu erstellen und schließlich die Ware mit der Rechnung zu verschicken. Sobald die Ware versandt wurde muss diese Informationen an Allyouneed übermittelt werden, damit der Bezahlprozess von Allyouneed gestartet werden kann. Sollte die Ware entgegen des Angebotes auf dem Marktplatz bzw. im Händler-Shop nicht lieferbar sein, so muss der Händler die betroffenen Bestellpositionen oder gegebenenfalls die gesamte Bestellung umgehend stornieren (siehe Kapitel 19)

Die Bestellung ist in unterschiedliche Bereiche aufgeteilt, eindeutige Identifizierung, Bestellpositionen, Liefer- bzw. Rechnungsadresse, Kontaktdaten und die Versandart. Globale Referenz einer Bestellung ist die eindeutige Bestellnummer. Zu jeder Bestellnummer gehören eine oder mehrere Bestellpositionen mit den entsprechenden Detailinformationen. Für die Auslieferung ist eine Lieferadresse notwendig. Zusätzlich gibt es die Möglichkeit, dass die Lieferadresse von der Rechnungsadresse abweicht.

Für mögliche Rückfragen des Händlers wird zusätzlich zur Information die Kundennummer mitgeliefert. Optional kann der Händler mit dem Abruf der Bestellung auch die E-mail-Adresse des Kunden anfordern. Bei dieser Email-Adresse handelt es sich um eine virtuelle Adresse, die über Allyouneed geleitet wird. Auch können Sie, wenn Sie Speditionsware verkaufen, sich die Telefonnummer des Kunden zurück geben lassen, um die Lieferung abzusprechen.


13.2 Definitionen

Folgende Angaben sind im Bestellvorgang enthalten. Die Felder die zwingend notwendig sind haben in der Spalte "Pflichtfeld" ein "ja". Felder die keine Pflichtfelder sind und nicht geliefert werden, werden nicht gesetzt oder werden mit einem Vorgabewert befüllt (siehe Spalte "Beschreibung"). Die Tabelle enthält die Attribute, die mit der technischen Beschreibung in common.xsd und orders.xsd korrespondieren und jeweils eine kurze Inhaltsbeschreibung: Abruf Bestellungen Folgende Angaben sind für den Abruf der Bestellinformationen notwendig bzw. möglich. Es kann hierbei nur eine Möglichkeit gewählt werden, entweder eine Order- oder Bestell-Nummer, oder die Auswahl über Zeitraum und Status.

 

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Alias Email Kunde

getEmail

boolean

 

nein

"true" liefert eine Alias-Email-Adresse des Kunden

Telefonnummer

additionalInfos

Boolean

 

nein

„true“ liefert die Telefonnummer bei Speditionsware zurück

Bestellnummer

orderId

string

100

nein

Eindeutige Allyouneed Bestellnummer.

Datum von

dateFrom

Date

 

ja (wenn Auswahl über Zeitraum)

Datum ab wann** die Bestellungen abgerufen werden sollen,

Format:

YYYY-MM-DDThh:mm:ss *

Datum bis

dateTo

Date

 

nein

Datum bis wann** die Bestellungen abgerufen werden sollen,

Format:

YYYY-MM-DDThh:mm:ss *

Wird das Datum nicht angegeben dann setzt die Schnittstelle das aktuelle Tagesdatum voraus.

Status Bestellung

orderStatus

string

100

nein

Status der Bestellungen "Open" = offene und noch nicht vollständig bearbeitete Bestellungen "All" = alle Bestellungen. Wird das Feld nicht angegeben, so wird immer "Open" geliefert.

* Das Format dateTime ist wie folgt spezifiziert "YYYY-MM-DDThh:mm:ss" wobei: - YYYY Jahr - MM Monat - DD Tag - T Kennzeichnung, dass ab hier das Zeitformat beginnt - hh Stunden - mm Minuten - ss Sekunden ** Für die zeitliche Einschränkung über das Datum muss beachtet werden, dass es sich nicht zwingend um das Bestelldatum handelt, da es Aufgrund von Sicherheitsprüfungen zu Verzögerungen kommen kann.

 

Bestellung

Alle Informationen einer Bestellung sind global eindeutigen Bestellinformationen untergeordnet. Eindeutiger Schlüssel ist die Allyouneed -Bestellnummer.

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Bestellnummer

orderId

string

100

ja

Eindeutige Allyouneed Bestellnummer

Bestell-Datum

orderDate*

Date

 

ja

Datum an dem die Bestellung getätigt wurde

Änderungsdatum

lastModificationDate*

Date

 

ja

Datum an dem die letzte Änderung am Bestellvorgang durchgeführt wurde.

Bestell-Wert

totalPrice

double

 

ja

Gesamtbestellwert incl. MwSt.

Versandkosten

totalDeliveryCosts

double

 

ja

Versandkosten für die gesamte Bestellung

Das Format dateTime ist wie folgt spezifiziert "YYYY-MM-DDThh:mm:ss wobei: - YYYY Jahr - MM Monat - DD Tag - T Kennzeichnung, dass ab hier das Zeitformat beginnt - hh Stunden - mm Minuten - ss Sekunden bedeuten.

 

Bestellposition

Die Bestellung kann eine beliebige Anzahl von Produkten enthalten. Jedes bestellte Produkt wird durch eine einzelne Bestellposition beschrieben.

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Haendler Produkt ID

productID

string

100

ja

Interne und eindeutige Artikelnummer des Händlers

Allyouneed Produkt ID

meinPaketId

string

100

nein

Eindeutige Allyouneed Artikelnummer

European article number

ean

string

13

nein

Die „European Article Number“,  EAN des Produktes; Bei Büchern ISBN-13

Produkt Name

name

string

100

ja

Name des Produktes

Menge

quantity

Integer

 

ja

Bestellte Anzahl des Produktes

Verkaufspreis

basePrice

double

 

ja

Aktueller Verkaufspreis inkl. der gesetzlichen MwSt.

Bestellwert

totalPrice

double

 

ja

Gesamtbestellwert incl. MwSt.

 

Lieferadresse / Packstation / Filiale

Die Lieferadresse kann aus einer Packstations-Referenz, einer Filialadresse oder aus einer Postanschrift-Adresse bestehen.

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

PostKundennummer

customerId

string

100

nein

Eindeutige Post-Kundennummer für die DHL Services (Packstation, Wunschzustellung…)

Packstations / Filialennummer

packstationId

string

100

nein*

Die Packstations/Filial-Nummer ist in Kombination mit der Postleitzahl eindeutig

Anrede

salutation

string

100

nein

Kunden Anrede (Herrn, Frau)

Titel

Title

string

100

nein

Kunden Titel (Prof., Dr. etc.)

Firma

company

string

100

nein

Firmenname für Lieferadresse

Vorname

firstName

string

100

ja

Vorname des Lieferungs-Empfängers

Nachname

lastName

string

100

ja

Nachname des Lieferungs-Empfängers

Strasse

Street

string

100

nein*

Straße (Bei Filialadressen in diesem Feld der Hinweis „Filiale“)

Hausnummer

houseNumber

string

100

nein*

Hausnummer

Adresszusatz

addressAddition

string

100

nein

Zusätzliche Adressinformationen wie z.B. c/o

PLZ

zipCode

string

100

ja

Postleitzahl

Ort

City

string

100

ja

Ort

Land

Country

country

2

ja

ISO Ländercode

* die Lieferadresse besteht aus Postanschrift oder Packstation oder Filialadresse

 

Rechnungsadresse

Unabhängig von der Lieferadresse kann eine gesonderte Rechnungsadresse angegeben werden. Die Rechnungsadresse ist optional.

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Anrede

salutation

string

100

nein

Kunden Anrede (Herr, Frau)

Titel

Title

string

100

nein

Kunden Titel (Prof., Dr. etc.)

Firma

company

string

100

nein

Firmenname für Rechnungsadresse

Vorname

firstName

string

100

ja

Vorname des Rechnungs-Empfängers

Nachname

lastName

string

100

ja

Nachname des Rechnungs-Empfängers

Strasse

street

string

100

ja

Straße

Hausnummer

houseNumber

string

100

ja

Hausnummer

Adresszusatz

addressAddition

string

100

nein

Zusätzliche Adressinformationen wie z.B. c/o

PLZ

zipCode

string

100

ja

Postleitzahl

Ort

city

string

100

ja

Ort

Land

country

country

2

ja

ISO Ländercode

 

Kontaktdaten

Als Kundenreferenz für mögliche Rückfragen wird die Kundennummer mitgeliefert.

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Kundennummer

customerId

 

string

100

ja

Eindeutige Allyouneed Kundennummer

Alias Email Kunde

email

 

string

100

nein

Alias-Email-Adresse des Kunden.

Telefonnummer Kunde

phoneNumber

String

100

Nein

Telefonnummer des Kunden bei Speditionsware

Lieferung

Diese Informationen über abgearbeitete Bestellungen werden nur für teilweise erledigte Vorgänge (wenn vorhanden) übermittelt:

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Liefernummer

consignmentId

string

100

ja

Interne und eindeutige Liefernummer des Händlers

Liefer-Status

consignmentStatus

string

100

ja

Mögliche Werte: ["SHIPPED", "CANCELED", "DONE"]

 

Lieferposition

Die Positionen die in der bereits erledigten Teillieferung enthalten sind.

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Händler Produkt ID

productID

string

100

ja

Interne und eindeutige Artikelnummer des Händlers

Allyouneed Produkt ID

meinPaketId

string

100

nein

Eindeutige Allyouneed Artikelnummer

European article number

ean

string

13

nein

Die „European Article Number“,  EAN des Produktes; Bei Büchern ISBN-13

Menge

quantity

Integer

 

ja

Gelieferte Anzahl des Produktes

nach oben


14 Warenversand

14.1 Fachliche Beschreibung

Ein Händler ist verpflichtet, in der von ihm angegebenen Lieferzeit, die bestellten Positionen nach Eingang der Bestellung zu versenden. Sollte er die geforderten Artikel oder Teile davon nicht liefern können, so muss er diese umgehend stornieren. Sobald der Versandvorgang vom Händler gestartet wurde, muss er dies an Allyouneed melden, denn das löst den Bezahlvorgang des Kunden und die Vergütung an den Händler aus. Nach erfolgter Versandmeldung ist keine Stornierung der Bestellung oder von Teilen davon mehr möglich. Der Händler kann sowohl die komplette Bestellung als auch einzelne Positionen (oder Teile davon) als versendet melden. Für jede Versandmeldung gibt es die Möglichkeit, die Tracking-Informationen der Lieferung an Allyouneed zu übermitteln. Nach erfolgter Auslieferung erhält der Händler die Bezahlung über Allyouneed. Das Geld für die Bestellung wird sieben Tage nach der Versandmeldung ausbezahlt.


14.2 Definitionen

Für die Rückmeldung (notificationRequest) des Händlers an Allyouneed sind einige Angaben über den Versand der Ware notwendig. Diese zwingend notwendigen Felder haben in der Spalte "Pflichtfeld" ein "ja". Felder, die keine Pflichtfelder sind und nicht geliefert werden, werden nicht gesetzt oder werden mit einem Vorgabewert befüllt (siehe Spalte "Beschreibung"). Die Tabelle enthält die Attribute, die mit der technischen Beschreibung in common.xsd und orders.xsd korrespondieren und jeweils eine kurze Inhaltsbeschreibung:

 

Lieferung

Die gesamte Lieferung kann aus mehreren Artikeln bestehen, die in mehr als einem Paket bzw. auch zu unterschiedlichen Zeitpunkten verschickt werden können. Die Positionen, die in einem Versand-Paket zusammengefasst sind, erhalten eine Liefernummer. Einer Bestellnummer kann somit mehr als eine Liefernummer zugeordnet sein. Lieferung.

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Bestellnummer

orderId

string

100

ja

Eindeutige Allyouneed Bestellnummer

Liefernummer

consignmentId

string

100

ja

Interne und eindeutige Liefernummer des Händlers

Trackingnummer

trackingId

string

100

nein

Trackingnummer/Sendungscode der Lieferung (opt.), nur bei Paketlieferung verfügbar

Versanddatum

shippingDate

Date

 

nein

Datum des Versandes durch den Händler

Voraussichtliches Lieferdatum

deliveryDate

Date

 

nein

Voraussichtliches Lieferdatum für den Kunden

 

Lieferposition

Die Lieferpositionen sind eine Auflistung aller Produkte, die in der Lieferung enthalten sind.

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Haendler Produkt ID

productID

string

100

ja

Interne und eindeutige Artikelnummer des Händlers

Allyouneed Produkt ID

meinPaketId

string

100

nein

Eindeutige Allyouneed Artikelnummer

European article number

ean

string

13

nein

Die „European Article Number“,  EAN des Produktes; Bei Büchern ISBN-13.

Menge

quantity

long

 

ja

Gelieferte Menge des Artikels

 

nach oben


15 Tracking

15.1 Fachliche Beschreibung

Die Lieferung der Tracking-Daten ist generell nicht zwingend, führt aber zu mehr Transparenz für den Kunden und damit auch zu einer höheren Kundenzufriedenheit. Der Händler ist angehalten die Tracking-Daten sofort (siehe Kapitel 17) oder nach dem Versand der Lieferung zu übermitteln.

Falls die Liefernummer (consignmentId) nicht eindeutig ist kann zusätzlich die Bestellnummer (orderId) mit angegeben werden.

Die Trackingnummer kann überschrieben oder gelöscht werden. Zum Löschen wird die Lieferung bzw. Order leer übermittelt, zum Überschreiben wird die Lieferung bzw. Order mit der neuen Trackingnummer übermittelt.

Falls zum Zeitpunkt der Versandmeldung noch keine Tracking-Daten der Lieferung bekannt sind, können diese separat nachgeliefert werden.


15.2 Definitionen

Für die Tracking-Meldung des Händlers an Allyouneed sind die folgenden Angaben notwendig. Beide Felder sind dabei Pflichtfelder. Die Tabelle enthält die Attribute, die mit der technischen Beschreibung in common.xsd und orders.xsd korrespondieren und jeweils eine kurze Inhaltsbeschreibung:


Tracking

Für die Tracking-Information ist lediglich die Tracking-Nummer notwendig, die der Lieferung zugeordnet wird.

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Liefernummer

consignmentId

string

100

ja

Interne und eindeutige Liefernummer des Händlers

Trackingnummer

trackingId

string

100

ja

Trackingnummer/Sendungscode der Lieferung (opt.), nur bei Paketlieferung verfügbar

Bestellnummer

orderId

string

100

nein

Eindeutige Allyouneed Bestellnummer

nach oben


16 Stornierung

16.1 Fachliche Beschreibung

Der Stornierungsprozess wird sowohl für die Stornierung des Händlers, wenn ein Produkt nicht lieferbar ist, als auch für den Stornierungswunsch des Kunden genutzt.

Ein Händler, der ein oder mehrere Produkte bzw. die komplette Bestellung nicht liefern kann, muss die entsprechenden Produkte als Stornierung melden. Dadurch wird der Kunde nicht belastet und die Bestellung bzw. Teile der Bestellung werden hinfällig.
Ein Kunde hat die Möglichkeit, nach einer getätigten Bestellung einen Stornierungswunsch zu äußern. Dieser Wunsch wird per Mail dem Händler mitgeteilt. Sofern der Händler in der Lage ist die Stornierung durchzuführen, stößt er diesen Prozess an. Falls eine Stornierung durch den Händler nicht mehr möglich ist, da z.B. der Versandprozess schon begonnen hat, so kann der Stornierungswunsch des Kunden nicht erfüllt werden und der Kunde muss in diesem Fall die Möglichkeit der Retoure, nutzen.


16.2 Definitionen

Folgende Angaben müssen für die Stornierung an Allyouneed übermittelt werden. Die Felder, die zwingend notwendig sind, haben in der Spalte "Pflichtfeld" ein "ja". Felder, die keine Pflichtfelder sind und nicht geliefert werden, werden nicht gesetzt oder werden mit einem Vorgabewert befüllt (siehe Spalte "Beschreibung"). Die Tabelle enthält die Attribute, die mit der technischen Beschreibung in common.xsd und orders.xsd korrespondieren und jeweils eine kurze Inhaltsbeschreibung:

 

Stornierung der Bestellung

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Bestellnummer

orderId

string

100

ja

Eindeutige Allyouneed Bestellnummer

Liefernummer/Stornonummer

consignmentId

string

100

ja

Interne und eindeutige Storno-Nummer des Händlers

 

Stornierung Bestellposition

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Haendler Produkt ID

productID

string

100

ja

Interne und eindeutige Artikelnummer des Händlers

Allyouneed Produkt ID

meinPaketId

string

100

nein

Eindeutige Allyouneed Artikelnummer

European article number

ean

string

13

nein

Die „European Article Number“,  EAN des Produktes; Bei Büchern ISBN-13

Menge

quantity

Integer

 

ja

Stornierte Stückzahl des Produkts

Stornierungsgrund

reason

string

100

ja

Grund der Stornierung [„CustomerRequest“ oder ”DealerRequest”]

Bemerkung

comment

string

4000

nein

Weitere Anmerkung des Händlers

nach oben


17 Retoure

17.1 Fachliche Beschreibung

Der Kunde hat die Möglichkeit, innerhalb einer vorgegebenen Frist, eine Bestellung an den Händler zurück zu schicken. Dabei können ein oder mehrere Artikel betroffen sein.

Spätestens der Eingang der Retourensendung beim Händler löst den Retouren-Prozess aus.
Der Kunde kann auch vorher Allyouneed oder den Händler kontaktieren, dies ist aber nicht zwingend notwendig.

Eine Retoure kann unterschiedlichste Gründe haben bzw. durch verschiedene Aktionen des Kunden ausgelöst werden:

  • Der Kunde schickt die Ware ohne Ankündigung und auf eigene Kosten an den Händler zurück.
  • Der Kunde schickt die Ware mit dem vom Händler beigelegtem Retourenschein zurück.
  • Der Kunde ruft beim Händler an, der Händler lässt dem Kunden per Post oder elektronisch einen Retourenschein zukommen, der Kunde schickt die Ware an den Händler.
  • Der Kunde ruft bei der Allyouneed -Hotline an und wird dort an den Händler verwiesen.

Erhält der Händler eine Sendung zurück so muss er Allyouneed informieren und dabei die entsprechende Bestellnummer und Artikelnummern mitteilen.

Falls die zurück gesendeten Artikel beschädigt oder gebraucht sind, gibt es die Möglichkeit den zu erstattenden Betrag zu reduzieren. Hierbei müssen die Gründe dafür angegeben werden.

 

Folgende Rücksendungs-Gründe sind definiert:

Name

Beschreibung

DAMAGED

Ware beschädigt

USED

Ware gebraucht

LOOK_IN_COMMENT

Genaue Beschreibung muss dafür in dem Feld "comment" bereit gestellt werden. Es sind maximal 4000 Zeichen zugelassen. Diese Anmerkung wird bei Bedarf an den Kunden weiter geleitet.

 

Weiter kann ein Händler den Betrag über die Rückerstattung der Versandkosten angeben.


17.2 Definition

Folgende Angaben sind für die Meldung der Retoure notwendig. Die Felder, die zwingend notwendig sind, haben in der Spalte "Pflichtfeld" ein "ja". Felder, die keine Pflichtfelder sind und nicht geliefert werden, werden nicht gesetzt. Die Tabelle enthält die Attribute, die mit der technischen Beschreibung in common.xsd und orders.xsd korrespondieren und jeweils eine kurze Inhaltsbeschreibung:

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Bestellnummer

orderId

string

100

ja

Eindeutige Allyouneed Bestellnummer

Retourennummer

returnId

string

100

ja

Eindeutige Händler Retourennummer

Reduzierung

Reduction

double

 

nein

Betrag um den reduziert wird / Abschlag

Reduzierungs Grund

reductionReason

string

100

nein

Reduzierungs Grund: „DAMAGED“ wenn Artikel beschädigt, „USED“ wenn Artikel Gebrauchsspuren aufweist, „LOOK_IN_COMMENT“ bei weiteren Gründen, dann im Feld Comment anzugeben.

Versandkosten Erstattung

reimbursedDeliveryCosts

double

 

nein

Erstattete Versandkosten

Bemerkung

Comment

string

4000

nein

Weitere Anmerkungen des Händlers

Haendler Produkt ID

productID

string

100

ja

Interne und eindeutige Artikelnummer des Händlers

Allyouneed Produkt ID

meinPaketId

string

100

nein

Eindeutige Allyouneed Artikelnummer

European article number

Ean

string

13

nein

Die „European Article Number“,  EAN des Produktes; Bei Büchern ISBN-13

Menge

Quantity

long

 

ja

Bestellte Anzahl des Produktes

nach oben


18 Gutschriften einstellen und abfragen

18.1 Fachliche Beschreibung

Mit dem NotificationRequest „creditMemo“ können Sie Gutschriften über die Schnittstelle anlegen. Dies kann auf Basis eines Consignments (Also Lieferung oder Stornierung) oder einer Retoure geschehen.  Neben der Angabe der Höhe des Gutschriftenbetrags muss auch ein Grund für die Gutschrift übergeben werden. Eine Liste der Gründe finden Sie weiter unten.

Eine Gutschrift kann nicht negativ sein und nicht größer als der bezahlte Betrag der Bestellung.

Mit dem QueryRequest „creditMemoQuery“ haben Sie die Möglichkeit, die erstellten Gutschriften über die API abzurufen. Dies kann auf Basis von Consignments bzw. Retouren, der ID der Gutschrift, der OderID und einem eingegrenzten Zeitraum geschehen.


18.2 Definitionen

Folgende Angaben sind für das Herunterladen der Response notwendig. Die Felder, die zwingend notwendig sind, haben in der Spalte "Pflichtfeld" ein "ja". Felder, die keine Pflichtfelder sind und nicht geliefert werde, werden nicht gesetzt. Die Tabelle enthält die Attribute, die mit der technischen Beschreibung in common.xsd, product.xsd und data.xsd korrespondieren und jeweils eine kurze Inhaltsbeschreibung.

 

Request „creditMemo“

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Liefernummer/Stornonummer

consignmentId

string

100

ja

Interne und eindeutige Storno-Nummer des Händlers*

Retourennummer

returnId

string

100

ja

Eindeutige Händler Retourennummer*

Bestellnummer

orderId

string

100

ja

Eindeutige Allyouneed Bestellnummer

Gutschriftennummer

creditId

string

100

ja

Eindeutiger Gutschriftenbezeichner. Wird in der Antwort auf den NotificationRequest zurückgegeben.

Betrag der Gutschrift

creditAmount

string

100

ja

Der Betrag der gutgeschrieben werden soll.

Grund der Gutschrift

creditMemoReason

string

100

ja

Der Grund für die Gutschrift.

* Entweder Angabe der consignmentId oder einer returnId

 

Response

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Gutschriftennummer

creditId

string

100

ja

Eindeutiger Gutschriftenbezeichner. Wird in der Antwort auf den NotificationRequest zurückgegeben.

 

Request „creditMemoQuery“

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Liefernummer/Stornonummer

consignmentId

string

100

ja

Interne und eindeutige Storno-Nummer des Händlers

Retourennummer

returnId

string

100

ja

Eindeutige Händler Retourennummer

Bestellnummer

orderId

string

100

ja

Eindeutige Allyouneed Bestellnummer

Gutschriftennummer

creditId

string

100

ja

Eindeutiger Gutschriftenbezeichner. Wird in der Antwort auf den NotificationRequest zurückgegeben.

Datum von

dateFrom

Date

 

ja (wenn Auswahl über Zeitraum)

Datum ab wann** die Bestellungen abgerufen werden sollen,

Format:

YYYY-MM-DDThh:mm:ss *

Datum bis

dateTo

Date

 

nein

Datum bis wann** die Bestellungen abgerufen werden sollen,

Format:

YYYY-MM-DDThh:mm:ss *

Wird das Datum nicht angegeben dann setzt die Schnittstelle das aktuelle Tagesdatum voraus.

* Das Format dateTime ist wie folgt spezifiziert "YYYY-MM-DDThh:mm:ss" wobei:
- YYYY Jahr
- MM Monat
- DD Tag
- T Kennzeichnung, dass ab hier das Zeitformat beginnt
- hh Stunden
- mm Minuten
- ss Sekunden

 

Response

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Anlegedatum

creationDate

Date

-

ja

Datum und Uhrzeit, an dem die Gutschrift angelegt wurde

Liefernummer/Stornonummer

consignmentId

string

100

ja

Interne und eindeutige Storno-Nummer des Händlers

Gutschriftennummer

creditId

string

100

ja

Eindeutiger Gutschriftenbezeichner. Wird in der Antwort auf den NotificationRequest zurückgegeben.

Bestellnummer

orderId

string

100

ja

Eindeutige Allyouneed Bestellnummer

Betrag der Gutschrift

creditAmount

string

100

ja

Der Betrag der gutgeschrieben werden soll.

Grund der Gutschrift

creditMemoReason

string

100

ja

Der Grund für die Gutschrift.

PostKundennummer

customerId

string

100

ja

Eindeutige Kundennummer des Kunden

Kunden Alias E-Mail

Email

String

100

ja

Alias E-Mail Adresse des Kunden

 

Folgende Gutschriftengründe sind definiert:

Name

Beschreibung

DEALER_GOODWILL

Gutschrift aus Kulanz des Händlers

DEALER_STORNO_COMPENSATION

Gutschrift wegen Stornierung durch Händler

DEALER_ADVANCE_PAYMENT_COMPENSATION

Gutschrift wegen zu hohem Rechnugsbetrag

DEALER_DELIVERY_DIFFICULTIES

Gutschrift wegen Lieferschwierigkeiten des Händlers

DEALER_DELIVERY_DEFICIT

Gutschrift wegen Mängeln an der Lieferung

DEALER_DELIVERY_DELAYED

Gutschrift wegen Lieferverzug

DEALER_DELIVERY_WRONG

Gutschrift wegen Falschlieferung

DEALER_DELIVERY_FAILED

Gutschrift wegen nicht durchgeführter Lieferung

nach oben


19 Günstigsten Preis abfragen

19.1 Fachliche Beschreibung

Der Webservice getBestPrice erlaubt Ihnen den besten Preis für ein Produkt anhand Ihrer productId abzufragen. Dabei werden die Gesamtpreise aller Anbieter (inklusive der Versandkosten) ermittelt und verglichen. Der günstigste Preis wird dann in der Response übergeben. Dieser entspricht dann dem Topanbieter auf dem Marktplatz.


19.2 Definitionen

Folgende Angaben sind für das Herunterladen der Response notwendig. Die Felder, die zwingend notwendig sind, haben in der Spalte "Pflichtfeld" ein "ja". Felder, die keine Pflichtfelder sind und nicht geliefert werde, werden nicht gesetzt. Die Tabelle enthält die Attribute, die mit der technischen Beschreibung in common.xsd, product.xsd und data.xsd korrespondieren und jeweils eine kurze Inhaltsbeschreibung.

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Händler Produkt ID

productId

string

100

ja

Interne und eindeutige Artikelnummer des Händlers.

 

Response

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Händler Produkt ID

productId

string

100

ja

Interne und eindeutige Artikelnummer des Händlers.

Verkaufspreis

price

double

 

ja

Einzelpreis incl. der gesetzlichen MwSt. mit maximal zwei Nachkommastellen und einem Punkt als Dezimaltrennzeichen.

Versandkosten

deliveryCost

double

 

ja

Anfallende Versandkosten für das Produkt.

Eigentümerschaft

ownership

string

100

ja

Sagt aus, ob der anfragende Händler den besten Preis bietet.

nach oben


20 Produktdaten abfragen

20.1 Fachliche Beschreibung

Der Webservice getProductData erlaubt Produktdaten abzurufen, um entscheiden zu können auf welches Produkt Sie matchen möchten. Grundsätzlich werden nur Produktdaten zurück geliefert, die von Allyouneed zur Verfügung gestellt werden bzw. für das Matchen unbedingt notwendig sind. Die Bilder und Produktbeschreibungen von anderen Händlern sind nicht abrufbar.

Die Suchabfrage erfolgt über die Parameter

  • MeinPaketId (Exakte Suche)
  • EAN (Exakte Suche)
  • Herstellername (Enthällt den Suchbegriff, unabhängig von der Groß-/Kleinschreibung)
  • HerstellerPn (Enthällt den Suchbegriff, unabhängig von der Groß-/Kleinschreibung)
  • Produktname (Enthällt den Suchbegriff, unabhängig von der Groß-/Kleinschreibung)

Die Suche erfolgt anhand einer UND-Verknüpfung mit allen übergebenen Werten.


20.2 Definitionen

Folgende Angaben sind für das Herunterladen der Response notwendig. Die Felder, die zwingend notwendig sind, haben in der Spalte "Pflichtfeld" ein "ja". Felder, die keine Pflichtfelder sind und nicht geliefert werde, werden nicht gesetzt. Die Tabelle enthält die Attribute, die mit der technischen Beschreibung in common.xsd, product.xsd und data.xsd korrespondieren und jeweils eine kurze Inhaltsbeschreibung.

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Nummer der Abfrage

entryId

string

100

ja

Die entryId wird vom Händler vergeben, durch sie wird jede Suchanfrage eindeutig identifiziert.

Allyouneed Produkt ID

meinPaketId

string

100

nein*

Eindeutige Allyouneed Artikelnummer

European article number

ean

string

13

nein*

Die "European Article Number", EAN des Produktes.

Für Bücher ISBN-13.

Hersteller

manufacturerName

string

100

nein*

Name des Herstellers*

Hersteller Artikelnummer

manufacturerPN

string

100

nein*

Artikelnummer des Herstellers

Produkt Name

name

string

100

nein*

Name des Produktes

* Alle Angagen sind optional aber mindestens eine muss übergeben werden

 

Response

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

Nummer der Abfrage

entryId

string

100

ja

Die entryId wird vom Händler vergeben, durch sie wird jede Suchanfrage eindeutig identifiziert.

Allyouneed Produkt ID

meinPaketId

string

100

nein

Eindeutige Allyouneed Artikelnummer

European article number

ean

string

13

nein

Die "European Article Number", EAN des Produktes.

Für Bücher ISBN-13.

Hersteller

manufacturerName

string

100

nein

Name des Herstellers*

Hersteller Artikelnummer

manufacturerPN

string

100

nein

Artikelnummer des Herstellers

Marktplatz Kategorie

marketplaceCategorie

string

100

ja

Produktkategorie auf dem Marktplatz

Produkt Name

name

string

100

ja

Name des Produktes

Beschreibung von Allyouneed

hasDescription

string

100

ja

Gibt an ob eine Description vorhanden ist.

Bild

image

image

512

nein

URL zu einem Produktbild des Händlers. Maximale Größe 2 MB

Attribut Code

code

string

100

nein

Eindeutige ID des Attributes. Dieser Code identifiziert für jeden Händler jedes Attribut.

Attribut Name

name

string

100

nein*

Bestimmte Merkmale des Produktes wie Abmessungen, Farben etc.

Attribut Wert

value

string

100

nein*

Wert des Attributes

Attribut Einheit

unit

string

100

nein*

Einheit des Attributwerts

Variantenkonfiuration

variantConfiguration

string

100

nein*

Code der Variantenkonfiguration

Klassifikation

classification

string

100

nein

Die Klasse, der das Produkt zugeordnet wurde

* Es werden nur variantenbildende Attribute übergeben.

nach oben


21 Händlerdaten abfragen

21.1 Fachliche Beschreibung

Der Webservice getMerchantData erlaubt Basisdaten eines Händlers abzurufen, um grundlegende Wettbewerbsinformationen zu erlagen. Grundsätzlich werden nur Daten von Shops zurück geliefert, die auf der jeweiligen Shopseite verfügbar sind. Daten von Shops, die nicht online sind werden nicht zurück geliefert.

Die Suchabfrage erfolgt über den Parameter Händlercode, welcher über getBestPrice bezogen werden kann.


21.2 Definitionen

Folgende Angaben sind für das Herunterladen der Response notwendig. Die Felder, die zwingend notwendig sind, haben in der Spalte "Pflichtfeld" ein "ja". Felder, die keine Pflichtfelder sind und nicht geliefert werde, werden nicht gesetzt. Die Tabelle enthält die Attribute, die mit der technischen Beschreibung in common.xsd, product.xsd und data.xsd korrespondieren und jeweils eine kurze Inhaltsbeschreibung.

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

HändlerId

merchantId

string

100

ja

Die merchantId identifiziert einen Händler eindeutig.

 

Response

Name

Attribut

Typ

Länge

Pflichtfeld

Beschreibung

HändlerId

merchantId

string

100

ja

Die merchantId identifiziert einen Händler eindeutig.

Name des Shops

shopName

string

100

ja

Der Name des identifizierten Shops.

Shopkategorien

useShopCategories

boolean

 

ja

true – der Shop nutz eigene Shopkategorien; false – der Shop nutzt keine eigenen Shopkategorien.

Status des Shops

shopStatus

string

100

ja

Gibt an ob der Shop online ist.

Anzahl der Bewertungen

numberOfMerchantRating

int

 

ja

Gibt die Anzahl der Händlerbewertungen wieder.

Durchschnitts-ewertung

averageMerchantRating

double

 

ja

Gibt die Durchschnittsbewertung für diesen Händler wieder.

Versandkosten

shippingCosts

-

-

-

-

Versandkostenfreie

Lieferung

freeShipping

boolean

 

nein

Gibt an, ob der Händler für alle Produkte eine versandkostenfreie Lieferung anbietet.

Versandkostenstaffel

shippingCost

-

-

-

Stufe einer Versandkostenstaffel

Währung

currency

String

100

ja

Währung

Mindestpreis

from

double

 

ja

Mindestpreis ab dem die Stufe greift

Höchstpreis

to

double

 

nein

Höchstpreis ab dem die Stufe greift. Der Höchstpreis wird nicht zurück gegeben, wenn die Stufe nach oben hin nicht begrenzt ist.

Versandkosten

cost

double

 

ja

Versandkosten für die jeweilige Stufe

nach oben


22 Die wichtigsten Fehlermeldungen der XML-Schnittstelle

22.1 Fehlermeldungen nach Art des Requests

In diesem Dokument finden Sie die Liste aller möglichen Fehlermeldungen, die sowohl die XML Schnittstelle von Allyouneed als auch die CSV Schnittstelle ausgeben kann. Diese sind innerhalb dieses Dokumentes und auch generell an Hand der Error-IDs in verschiedene Themengebiete aufgegliedert und immer eindeutig zu identifizieren.

Sowohl für das eigene Bearbeiten von möglicherweise auftretenden Fehlern als auch für den Kontakt mit dem Allyouneed Support ist es sinnvoll,  die Fehler korrekt zu identifizieren.

 

Generelle Fehlermeldungen

Error ID

ErrorCode

Fehlermeldung [de]

Fehlermeldung [en]

0001

 

Ein interner Fehler ist aufgetreten. (Code: 0001)

Internal error. // "ModelSavingException.getMessage()"

0002

 

Es ist ein unbekannter Fehler aufgetreten. (Code: 0002)

An unknown error occured, please contact meinpaket support, with this xmlfile

0003

 

Beim Verarbeiten der CSV-Datei ist ein unbekannter Fehler ist aufgetreten. (Code:0003)

An unknown Error occured

0004

 

Die Zugangsdaten sind nicht korrekt. (Code: 0004)

Failed to authenticate.

 

Produkte und Shopkategorie Fehlermeldungen

Error ID

ErrorCode

Fehlermeldung [de]

Fehlermeldung [en]

1001

SHOP_CATEGORY_NOT_FOUND

Die Oberkategorie “CategoryID" wurde nicht gefunden (Code:1001)

Parent category “CategoryID" not found.

1002

SHOP_CATEGORY_NOT_FOUND

Die Kategorie “CategoryID" wurde nicht gefunden (Code:1002)

Category “CategoryID" not found.

1003

MARKETPLACE_CATEGORY_NOT_FOUND

Die Marktplatz-Kategorie “MarketplaceCategory" wurde nicht gefunden. (Code:1003)

Market place category “MarketplaceCategory"not found.

1004

SHOP_CATEGORY_NOT_FOUND

Die Shop-Kategorie "ShopCategory" wurde nicht gefunden (Code: 1004)

Shop category "ShopCategory" not found.

1005

PRODUCT_NOT_FOUND

Das Produkt wurde nicht gefunden. (Code: 1005)

No product matched for given criteria.

1006

 

Das Pflichtfeld ""productID"" wurde nicht gefunden. (Code: 1006)

 

1007

INVALID_MODIFICATION

Das Pflichtfeld ""name"" wurde nicht gefunden (Code: 1007)

Name is missing

1008

INVALID_MODIFICATION

Das Pflichtfeld "shortDescription" wurde nicht gefunden (Code: 1008)

Shortdescription is missing

1009

NO_CATEGORIZATION

Das Pflichtfeld "marketplaceCategory" wurde nicht gefunden (Code: 1009)"

The specified product is not categorized nor clasfficied. Please provide a marketplace category or classification class.

1010

INVALID_DATA

Ungültiger Preis “{Wert}“. Der Preis muss eine positive Dezimalzahl sein. (Code: 1010)

Invalid price “{Wert}“, price must be a positive decimal number.

1011

INVALID_DATA

Ungültige Verfügbarkeit “{Wert}“. Die Verfügbarkeit eine muss positive Dezimalzahl sein. (Code: 1011)

Invalid availablity “{Wert}“, availability must be a positive integer.

1012

INVALID_DATA

Ungültige Steuerklasse “{Wert}“. Gültige Steuerklassen sind ""Reduced"", ""Standard"" und ""Free"". (Code: 1012)

Invalid taxgroup “{Wert}“, valid taxgroups are Reduced, Standard, Free

1013

INVALID_DATA

Ungültige Lieferzeit “{Wert}“. Die Lieferzeit muss eine positive ganze Zahl unter 30 sein. (Code: 1013)

Invalid delivery time “{Wert}“, delivery time must be a positive integer below 30.

1014

INVALID_DATA

Ungültige Einheit “{Wert}“. Die Einheit muss sein: pro_Stück, pro_1kg, pro_1l, pro_1m3, pro_1m, pro_1m2, pro_100g, pro_100ml. (Code: 1014)

Invalid unit “{Wert}“, unit must be one of: per_piece, per_1kg, per_1l, per_1m3, per_1m, per_1m2, per_100g, per_100ml

1015

INVALID_DATA

Ungültiger Preis “{Wert}“. Der Preis muss eine positive Dezimalzahl sein. (Code: 1015)

Invalid price “{Wert}“, price must be a positive decimal number.

1016

AVAILABILITY_NEGATIVE

Ungültige Verfügbarkeit “{Wert}“ Die Verfügbarkeit muss eine positive ganze Zahl sein. (Code: 1016)

Invalid availablity “{Wert}“, availability must be a positive integer.

1017

INVALID_DATA

Ungültige Lieferzeit “{Wert}“. Die Lieferzeit muss eine positive ganze Zahl unter 30 sein. (Code: 1017)

Invalid delivery time “{Wert}“, delivery time must be a positive integer below 30.

1018

INVALID_DATA

Ungültiger Grunpreis “{Wert}“. Der Grunpreis muss positive Dezimalzahl sein. (Code: 1018)

Invalid unit price “{Wert}“. unit price must be a positive decimal number.

1024

INVALID_DATA

Ungültiges Startdatum “{Wert}“. Das Datumsformat muss sein: YYYY-MM-DDTHH:MM:SS. (Code: 1024)

Invalid start date “{Wert}“, date format must be YYYY-MM-DDTHH:MM:SS

1025

INVALID_DATA

Ungültiges Enddatum “{Wert}“. Das Datumsformat muss sein: YYYY-MM-DDTHH:MM:SS. (Code: 1025)

Invalid end date “{Wert}“, date format must be YYYY-MM-DDTHH:MM:SS

1029

INVALID_DATA

Ungültige EAN “{Wert}“. Die EAN muss eine 13-stellige Zahl sein. (Code: 1029)

Invalid EAN “{Wert}“, EAN must be a 13 digit number.

1032

PRODUCT_NOT_FOUND

Das Produkt zum Löschen wurde nicht gefunden. (Code: 1032)

Product to delete not found

1033

INVALID_MODIFICATION

Es ist nicht möglich das Produkt zu löschen, da es unverarbeitete Bestellungen hat. (Code: 1033)

Product can not be deleted, because it has open orders

1035

 

Es wurde keine Marktplatz-Kategorie angegeben (Code: 1035)

No category code specified.

1036

 

Die Kategorie “{Wert}“ konnte auf Grund eines internen Fehlers nicht gelöscht werden. (Code: 1036)

Failed to remove category “{Wert}“ due to an internal error.

1037

 

Es exisitiert bereits eine Kategorie mit diesem Namen unter der gleichen Ursprungs- oder Oberkategorie. (Code: 1037)

Category with the same name already exists under the same root or supercategory.

1038

 

Es exisitert bereits eine Kategorie mit diesem Code “{Wert}“. (Code: 1038)

Category with code “{Wert}“ already exists.

1039

 

Beim Löschen des Produktes ist ein Fehler aufgetreten. (Code: 1039)

Error while deleting a product occured.

1040

 

Das Produkt konnte nicht angelegt werden. Es exisitert keine Beschreibung für dieses Produkt. (Code: 1040)

There is no existing Description for this product.

1041

 

Es exisitert bereits ein Produkt mit der Artikelnummer: "{ID}“ (Code: 1041)

There already is a product identified by the external id '{ID}' in the system for this dealer.

1042

 

Es exisitert bereits ein Produkt mit dieser ID. (Code: 1042)

There is already an offer with this ID (transaction failed).

1043

 

Es exisitert bereits ein Produkt mit dieser ID. (Code: 1043)

There is already an offer or product with this ID (constraint violation).

1044

 

Es wurde ein Fehler in den vorhandene Produktdaten gefunden. (Code: 1044)

"there is an undefined Error in the provided Productdata "

1045

 

Ihre Requestquote ist überschritten. (Code: 1045)

Quota Exceeded

1046

 

Der Name des Produktes konnte nicht geändert werden, da es noch Angebote enthält. (Code: 1046)

Rename on ", productApiData.getProductId(), " unsuccesfull, because Product still has open offers

1047

 

Der Name des Produktes konnte nicht geändert werden. (Code: 1047)

StringUtil.concatX("Rename on ", productApiData.getProductId(), " unsuccesfull ")

1048

 

Während des Speichervorgangs ist ein Fehler aufgetreten. (Code: 1048)

An Error during Saving occured