Dokumentacja techniczna API Sprzedającego

Transkrypt

Dokumentacja techniczna
API Sprzedającego
DHL Parcel
All You Need
Stan z dnia: 08.12.2014; v 4.1
portal.ayn.pl
Spis treści
1
Wstęp ................................................................................................................................5
1.1
Informacje techniczne ................................................................................................6
1.2
Wymagany dostęp .....................................................................................................8
1.3
Informacja zwrotna i wsparcie....................................................................................9
1.4
Dokumenty i przykłady do pobrania...........................................................................9
2
Podstawy merytoryczne i przegląd Pasażu Handlowego ...............................................10
3
Nagłówki XML .................................................................................................................11
4
Wywołanie odpowiedzi....................................................................................................12
4.1
Opis merytoryczny ...................................................................................................12
4.2
Definiowanie ............................................................................................................12
5
Oferty produktów w Pasażu Handlowym ........................................................................13
5.1
5.2
Definiowanie ............................................................................................................13
6
Kategorie produktów sklepu Sprzedającego...................................................................17
6.1
6.2
Definiowanie ............................................................................................................17
7
Oferty produktów Sprzedającego....................................................................................18
7.1
7.2
Definiowanie ............................................................................................................18
8
Warianty produktu ...........................................................................................................22
8.1
Definiowanie grupy wariantów .................................................................................23
8.2
Definiowanie konfiguracji wariantów .......................................................................23
9
Przykłady konfiguracji wariantów różnych asortymentów ...............................................26
9.1
Market budowlany....................................................................................................26
9.2
Książki......................................................................................................................26
9.3
Sprzęt elektroniczny powszechnego użytku ............................................................27
9.4
Filmy ........................................................................................................................27
9.5
Gry ...........................................................................................................................28
9.6
Sprzęt AGD..............................................................................................................28
9.7
Artykuły spożywcze..................................................................................................29
9.8
Soczewki kontaktowe...............................................................................................29
10
Przegląd konfiguracji wariantów „internetowy Pasaż handlowy“ .................................31
10.1
Powszechnie stosowane konfiguracje wariantów ................................................31
10.2
Konfiguracje wariantów dla asortymentów Książka, Film i Gry ............................32
10.3
Konfiguracje wariantów soczewek kontaktowych.................................................32
portal.ayn.pl
10.4
11
Konfiguracje wariantów dla asortymentu Moda....................................................33
Kategorie do pobrania .................................................................................................34
11.1
Opis merytoryczny................................................................................................34
11.2
Definiowanie.........................................................................................................34
12
Oferty produktów do pobrania .....................................................................................36
12.1
12.2
Definiowanie.........................................................................................................36
13
Wywołanie wskaźników ...............................................................................................39
13.1
13.2
Definiowanie.........................................................................................................39
14
Usuwanie.....................................................................................................................40
14.1
14.2
Definiowanie.........................................................................................................40
15
Podstawy merytoryczne i przegląd interfejsów procesu zamówienia..........................42
16
Zamówienie .................................................................................................................44
16.1
16.2
Definiowanie.........................................................................................................45
17
Przesyłka towarów.......................................................................................................52
17.1
17.2
Definiowanie.........................................................................................................52
18
Śledzenie przesyłki......................................................................................................54
18.1
18.2
Definiowanie.........................................................................................................54
19
Anulowanie zamówienia ..............................................................................................55
19.1
19.2
Definiowanie.........................................................................................................55
20
Zwroty..........................................................................................................................57
20.1
20.2
Definiowanie.........................................................................................................58
21
Zapytanie o najniższą cenę .........................................................................................60
21.1
21.2
Definiowanie.........................................................................................................60
22
Wywoływanie danych produktu ...................................................................................62
22.1
22.2
Definiowanie.........................................................................................................62
23
Zapytanie o dane Sprzedającego................................................................................65
portal.ayn.pl
23.1
23.2
Definiowanie.........................................................................................................65
24
Kontakt ........................................................................................................................67
Załącznik A.............................................................................................................................68
Załącznik B.............................................................................................................................69
Załącznik C.............................................................................................................................70
Załącznik D.............................................................................................................................71
Załącznik E.............................................................................................................................72
portal.ayn.pl
1 Wstęp
Witamy w serwisie internetowym All You Need służącym do aktualizacji danych produktów i
realizacji zamówień na internetowym „Pasażu Handlowym“.
Niniejszy dokument ma być pomocą dla Sprzedających podczas oferowania produktów do
sprzedaży w Pasażu Handlowym lub przy projektowaniu własnego sklepu on-line oraz przy
realizacji zamówień. Zawiera merytoryczny i techniczny opis interfejsu i jest opracowany jako
dokument referencyjny dla programistów pracujących nad rozwojem oprogramowania. W
dokumencie wyjaśniono podstawy i powiązania, jak również opisano podłączenie techniczne.
Przez ten interfejs można oferować produkty w Pasażu Handlowym, jak również ustawiać je
we własnym sklepie internetowym, można je aktualizować lub wyłączać. Tym samym każdy
Sprzedający może rozszerzać swoją ofertę produktową i utrzymywać ją w aktualnym stanie,
jak również przeprowadzić kategoryzację produktów.
Rozdział 1 zawiera wprowadzenie do interfejsu. Rozdział 2 daje ogólny przegląd
techniczny Pasażu Handlowego. Rozdział 3 pokazuje budowę nagłówków XML. W
Rozdziale 4 opisano możliwość wywołania odpowiedzi za pomocą identyfikatora żądania
"RequestID". W Rozdziale 5 opisano jak produkty z katalogu DHL można oferować w
Pasażu Handlowym. Dla Sprzedających, którzy chcą oferować własne produkty w Pasażu
Handlowym i w swoim sklepie - przeznaczony jest Rozdział 6, który opisuje, jak tworzyć
niezbędne do tego celu kategorie produktów. Wyczerpująco - definicję produktu oraz
ustawianie produktów objaśniono w Rozdziale 7. Do tego celu są także niezbędne dane z
Rozdziału 4 i dodatkowo z Rozdział 8 opisującego, jak tworzyć warianty do tych produktów.
W Rozdziale 9 znajdziesz przykłady, jak można wykorzystywać konfiguracje wariantów.
Następnie w Rozdziale 10 wymienione są wszystkie konfiguracje. Rozdział 11 zawiera opis
„Pobierania“ kategorii produktów. W Rozdziale 12 opisano „Pobieranie“ ofert produktowych.
W Rozdziale 13 opisano, jak wysłane na serwer produkty i kategorie sklepów można
usunąć.
Przez ten interfejs można wywoływać zamówienia i realizować je. Należy przy tym zwrócić
uwagę na to, że zamówienia nie są od razu dostępne, chociaż zostały wysłane przez Klienta.
To może się zdarzyć, jeżeli Klienci płacą z góry lub zamówienie nie zostało jeszcze
przetworzone na „internetowy Pasaż handlowy“. Krótkie wprowadzenie do procesów
realizacji zamówienia otrzymasz w Rozdziale 14.
Rozdział 15 zawiera opis dotyczący żądania "Request", za pomocą którego można
wywoływać zamówienia i opisuje treści odpowiedzi "Response" z podstawowymi danymi do
zamówienia. W Rozdziale 16 opisano, jak zamówienia można oznaczać jako wysłane do
Klienta. Zależnie od tego, kiedy jest dostępny nr śledzenia przesyłki, może on być przesyłany
bezpośrednio ze zgłoszeniem przesyłki lub później. Rozdział 17 opisuje tę drugą możliwość,
późniejszego przekazania nr śledzenia przesyłki. Jeżeli jakiegoś produktu nie ma na stanie,
wtedy Sprzedający może anulować całe zamówienie lub jedną pozycję zamówienia, którą to
możliwość opisuje Rozdział 18. Jeżeli Klient odsyła towar z powrotem do Sprzedającego,
musi to zostać zgłoszone do „internetowy Pasaż Handlowy“, aby można było uruchomić
księgowanie powrotne. W Rozdziale 19 opisano budowę żądania dotyczącego zwrotu. W
Rozdziale 20 dowiesz się, jak można wysłać zapytanie o najlepszą cenę dla produktu, aby
portal.ayn.pl
polepszyć swoją sytuację w zakresie konkurencyjności. W Rozdziale 21 opisano, jak można
wywoływać podstawowe dane produktów. W Rozdziale 22 wyjaśnia się, jak możesz
wywołać dane Sprzedającego. W Rozdziale 23 zostaną wyjaśnione noty uznaniowe przez
interfejs.
1.1
Informacje techniczne
Serwis internetowy All You Need oferuje dwa tryby przetwarzania danych, które różnią się
odesłaniem odpowiedzi. W pierwszym trybie pracy żądanie jest przetwarzane natychmiast.
W tym czasie musi być utrzymane połączenie HTTP. Na końcu otrzymujesz wynik
przetworzenia danych w odpowiedzi. Ten tryb jest przede wszystkim przeznaczony do
realizacji zamówień.
portal.ayn.pl
W drugim trybie po przesłaniu żądania otrzymasz w odpowiedzi nr identyfikacyjny ID
żądania "RequestId". Twoje żądania zostanie następnie ustawione w kolejkę
oczekujących i potem zostanie przetworzone. W tym czasie nie jest konieczne
połączenie HTTP. Status realizacji i odpowiedź możesz wywołać przez podanie ID
żądania "RequestId". Ten tryb jest przeznaczony do przetwarzania dużych do bardzo
dużych zbiorów danych.
Poniższe tabele zawierają przegląd funkcji i możliwy trybu pracy.
uploadRequest
Funkcja
Tryb pracy
Deletions
usuwanie kategorii lub produktów
tryb asynchroniczny
Categories
tworzenie kategorii
tryb asynchroniczny
variantGroups
tworzenie grup wariantów
tryb asynchroniczny
Descriptions
tworzenie produktów
tryb asynchroniczny
Offers
tworzenie ofert
tryb asynchroniczny
InternationalPrices
tworzenie międzynarodowych ofert
tryb asynchroniczny
catalogstructure
pobranie struktury katalogu
tryb synchroniczny lub
asynchroniczny
getProductOffers
pobranie wszystkich ofert produktowych
tryb asynchroniczny
variantConfigurations
pobranie
wariantów
downloadRequest
wszystkich
konfiguracji tryb synchroniczny lub
asynchroniczny
queryRequest
orders
portal.ayn.pl
wywołanie zamówień
uploadRequest
Funkcja
Tryb pracy
asynchroniczny
creditMemos
wywołanie wydanych not uznaniowych
asynchroniczny
consignments
zgłaszanie przesyłek towarowych
asynchroniczny
trackingNumbers
przesyłanie nr śledzenia przesyłki
asynchroniczny
cancellations
zgłaszanie anulowania (zamówienia)
asynchroniczny
returns
zgłaszanie zwrotów
asynchroniczny
creditMemo
tworzenie noty uznaniowej
asynchroniczny
bestPriceRequest
wywołanie najlepszej ceny dla produktu
tryb asynchroniczny
productDataRequest
wywołanie danych produktu
tryb asynchroniczny
getMerchantData
wywołanie danych Sprzedającego
tryb asynchroniczny
getQuota
wywołanie dostępnych ilości
tryb synchroniczny
notificationRequest
dataRequest
1.2
Wymagany dostęp
Aby korzystać z interfejsu musisz potwierdzić swoją tożsamość wobec All You Need. Do
tego celu potrzebne są:


Username (Nazwa użytkownika)
Password (Hasło)
Te dane otrzymasz automatycznie pocztą elektroniczną natychmiast po odblokowaniu
Twojego konta Sprzedającego. Jeżeli jesteś już Sprzedającym na All You Need, można już
wykorzystać swoje dotychczasowe dane do logowania.
Żądanie HTTP
URL: https://www.ayn.pl/dealerapi/xmlAsync
(asynchroniczny
Rozdział 3)
URL: https://www.ayn.pl/dealerapi/xml Metoda: HTTP-POST
portal.ayn.pl
interfejs
-
patrz
1.3
Informacja zwrotna i wsparcie
Jeżeli potrzebujesz pomocy, chcesz przesłać informację zwrotną lub odpowiedz w
jakiejkolwiek innej sprawie możesz skontaktować się z nami w następujący sposób:
 Osoba kontaktowa z działu sprzedaży
 Osoba kontaktowa z działu wsparcia ([email protected])
1.4
Dokumenty i przykłady do pobrania
Do poszczególnych rozdziałów istnieją przykładowe pliki z możliwymi odpowiedziami.
Wszystkie przykładowe pliki znajdują się w naszej strefie do pobrania. W poszczególnych
plikach zawarte są dodatkowe komentarze, które ułatwią Ci pracę z naszym interfejsem.
W załączniku D znajdziesz przegląd przykładowych plików.
portal.ayn.pl
2 Podstawy merytoryczne i przegląd Pasażu Handlowego
All You Need jest podzielony na dwie płaszczyzny. Centralną z nich umożliwia zakupy online, zwany dalej Pasażem Handlowym. Druga z nich to część dla Sprzedających i ich
sklepy. Pasaż Handlowy zawiera obszerny katalog produktów, który udostępnia DHL. Dla
każdego produktu istnieje odpowiedni krótki i długi opis, jedno lub kilka zdjęć i atrybuty.
Pasaż Handlowy ma strukturę drzewa kategorii, które podzielone są na cztery główne
zakresy tematyczne. Każdy zarejestrowany Sprzedający może pobrać te kategorie. Produkt
będzie widoczny w danej kategorii jeżeli chociaż jeden Sprzedający oferuje go w swoim
sklepie.
Każdy Sprzedający może oferować w Pasażu Handlowym dowolnie liczbę produktów, do
tego celu potrzebuje jedynie zamieścić swoje specyficzne informacje o tych produktach.
Minimalne informacje to cena, dostępność (liczba sztuk) i specyficzny dla danego
Sprzedającego nr identyfikacyjny - IDproduktu - wszystkie pozostałe informacje są
opcjonalne. Można pobrać przegląd wszystkich produktów oferowanych przez
Sprzedającego. Wszystkie produkty, które oferuje Sprzedający, są także wyświetlane w jego
własnym sklepie. We własnym sklepie istnieje jeszcze dodatkowo możliwość zdefiniowania
własnej struktury katalogu i następnie odpowiedniego przyporządkowania produktów.
Ponadto Sprzedający może tworzyć produkty z własnymi opisami, zdjęciami i oferować je w
Pasażu Handlowym oraz w swoim własnym sklepie.
portal.ayn.pl
3 Nagłówki XML
Do każdego żądania są wymagane informacje nagłówka do identyfikacji Sprzedającego. Te pola są poniżej zdefiniowane i muszą być podane
w przypadku każdego żądania wysłania danych.
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
SprzedającyUżytkownik
login
string
100
tak
Hasło
password
string
100
tak
Hasło Sprzedającego-Użytkownika
Język
language
string
100
nie
Język, jeżeli nie wypełniono, wysyłany jest "pl"
nie
Pole to nie musi być wykorzystywane przez poszczególnych Sprzedających lub
może być ustawione jako „UNKNOWN“.
Jeżeli oferując system Multi-Shop opracowujesz podłączenie do Twojego
systemu, proszę zwrócić się do działu wsparcia (Support), aby otrzymać własny
nr identyfikacyjny - multiplierId.
Możliwe identyfikatory typu multiplierId znajdują się w załączniku C.
Multiplier
portal.ayn.pl
multiplierId
string
100
Sprzedający-Użytkownik (adres e-mail umieszczony na Twoim koncie)
4 Wywołanie odpowiedzi
4.1
Opis merytoryczny
Jeżeli żądanie zostało wysłane do asynchronicznego interfejsu, wtedy to żądanie otrzymuje
numer identyfikacyjny "ReqestId". Za pomocą tego nr identyfikacyjnego można wywołać stan
realizacji i wynik przetwarzania danych.
4.2
Definiowanie
Poniższe dane są niezbędne do pobrania odpowiedzi. Pola, które są bezwzględnie
wymagane, mają w kolumnie "Pole obowiązkowe" "tak". Pola, które nie są polami
obowiązkowymi i nie są wysyłane, nie są ustawiane. Tabela zawiera atrybuty, które
korespondują z opisem technicznym w data.xsd i każdorazowo krótki opis zawartości.
Nazwa
RequestId
Atrybut
requestId
Typ
string
Status lub
onlyStatus boolean
Odpowiedź
portal.ayn.pl
Długość
Pole
obowiązkowe
100
tak
Unikalny nr identyfikacyjny ID, który
identyfikuje żądanie
nie
Wybór elementów odpowiedzi:
true (prawda) – odsyłany jest z
powrotem tylko stan realizacji
żądania
false
(fałsz)–
odpowiedź
jest
odsyłana z powrotem, jeżeli już jest,
w przeciwnym przypadku - stan
Jeżeli nic nie jest przekazywane,
wtedy standardowo przekazywany
jest tylko stan.
Opis
5 Oferty produktów w Pasażu Handlowym
5.1
Opis merytoryczny
All You Need udostępnia obszerny katalog produktów. Produkty są identyfikowane za
pomocą EAN (European Article Number), ISBN13 (Międzynarodowy Standard Numerów
Księgowych) etc.. Każdy zarejestrowany Sprzedający jest automatycznie uczestnikiem
Pasażu Handlowego i może oferować dowolne produkty z tego katalogu. Do tego potrzeba
tylko kilku informacji, ponieważ dla wspomnianych produktów istnieją już dokładne opisy.
Sprzedający musi dla tych produktów jedynie podać EAN lub nr identyfikacyjny Pasaż
Handlowego jako nr referencyjny dla danego produktu, cenę i dostępną ilość sztuk, jak
również jednoznaczny wewnętrzny kod Sprzedającego (wewnętrzny numer produktu
Sprzedającego). Pozostałe informacje jak np. data początkowa są opcjonalne. Dzięki temu
każdy Sprzedający może tylko za pomocą tych minimalnych informacji oferować produkty z
szerokiej oferty Pasażu Handlowego.
Po bezbłędnym wysłaniu na serwer wymaganych danych przez Sprzedającego są one
dostępne w Pasażu Handlowym. Jeżeli rekordy danych poszczególnych produktów są
niepełne lub błędne, wtedy po ich wysłaniu zostanie przesłane zgłoszenie zwrotne o błędzie
w "uploadResponse". Sprzedający może skorygować błędne lub nie wysłane produkty i je
ponownie wysłać. Przy tym wystarczy ponownie zamieścić tylko te pierwotnie błędne dane,
nie jest zaś konieczne ponowne przesyłanie wszystkich rekordów danych.
Prawidłowo wysłane produkty pozostają aktywne do sprzedaży w Pasażu Handlowym do
momentu spełnienia się jednego z poniższych warunków:
5.2

podana liczba sztuk produktu została sprzedana lub jest zarezerwowana

dla danej oferty produktowej Sprzedający podał datę zakończenia i ten dzień właśnie
nadszedł

sklep Sprzedającego jest offline lub zablokowany

konto Sprzedającego nie jest już aktywne lub złożono wypowiedzenie

produkt został zablokowany
Definiowanie
Dla każdego pojedynczego produktu, który ma być oferowany, możliwe są poniższe dane.
Pola, które są bezwzględnie wymagane, mają w kolumnie "Pole obowiązkowe" "tak". Pola,
które nie są polami obowiązkowymi i nie są wysyłane, nie są ustawiane lub są wypełniane
wartością domyślną (patrz kolumna „Opis“). Tabela zawiera atrybuty, które korespondują z
opisem technicznym w common.xsd i product.xsd i każdorazowo krótki opis zawartości:
portal.ayn.pl
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
ID produktu
Sprzedającego
productId
string
100
tak
Wewnętrzny i unikalny numer artykułu Sprzedającego
string
100
nie
Unikalny numer artykułu „internetowy Pasaż handlowy“
string
13
nie
„European Article Number“, EAN produktu; w przypadku książek
ISBN-13
Pasaż handlowy ID
meinPaketId
produktu
European article
number
ean
Producent
manufacturerName string
100
nie
Nazwa producenta*
Numer artykułu
producenta
manufacturerPN
string
100
nie
Numer artykułu producenta
price
double
tak
Cena jednostkowa zawierająca ustawowy podatek VAT z maksymalnie
dwoma miejscami po przecinku i kropką jako separatorem dziesiętnych.
unitprice
double
nie
Cena na każdą jednostkę
nie
Jednostka ilości produktu:
Sztuka = „per_piece“
Kilogram = “per_1kg”
Litr =”per_1l”
Metr sześcienny =“per_1m3“
Metr =“per_1m“
Metr kwadratowy =”per_1m2”
Gram =”per_100g”
Mililitr =”per_100ml”
Cena sprzedaży
Cena jednostkowa
Jednostka
unit
string
100
availability
integer
tak
Dostępna liczba sztuk tego produktu. Liczba sztuk przy każdej
sprzedaży jest automatycznie obniżana. Jeżeli liczba sztuk wynosi 0
wtedy produkt jest wyświetlany jako wyprzedany.
startDate
dateTime
nie
Data, od kiedy produkt jest dostępny do zamawiania przez Klienta, tzn.
jest widoczny w Pasażu Handlowym u tego Sprzedającego. Data musi
być wysłana w następującym formacie: YYYY-MM-DDThh:mm:ss **
endDate
dateTime
nie
Data, od której produkt nie jest już dostępny, tzn. nie jest ani widoczny,
ani nie można go wybrać do zamówienia. Data musi być wysłana w
Dostępność
Data początkowa
Data zakończenia
portal.ayn.pl
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
następującym formacie: YYYY-MM-DDThh:mm:ss **
Termin dostawy
integer
nie
Czas dostawy produktu do klienta w dniach, od 1 do 29 dni. Jeżeli nie
jest podany termin dostawy, wtedy wstawia się domyślnie jeden dzień.
Kategoria w sklepie
shopCategory
Sprzedającego
categoryRef 100
nie
Kategoria produktu we własnym sklepie Sprzedającego***
Grupa wariantów
string
nie
Kod grupy wariantów
nie
Fixed-Product dla wyników wyszukiwania; Jeżeli wysyłany jest dla
więcej niż jednego produktu, to ostatni produkt jest „FixedProduct“;
standardem jest "false"
deliverytime
variantGroupCode
100
Fixed Product
useAsFixedProduct boolean
Kod atrybutu
code
string
100
tak
Unikalny ID atrybutu. Ten kod identyfikuje dla każdego Sprzedającego
każdy atrybut.
Nazwa atrybutu
name
string
100
nie
Nazwa cechy produktu jak wymiary, kolory etc.
Wartość atrybutu
value
string
100
nie
Wartość atrybutu
Jednostka atrybutu unit
string
100
nie
Jednostka wartości atrybutu
Koszty przesyłki
deliveryCost
double
nie
Informacja na temat specyficznych kosztów przesyłki tego produktu
Stałe koszty
przesyłki
fixedCost
boolean
nie
Informacja, czy koszty przesyłki tego produktu zawsze są doliczane w
całości, niezależnie od stopniowania etc.. Wymagane „dispatchType“
BULK_GOODS lub FORWARDING_AGENCY
nie
Rodzaj dostawy produktu. Możliwe są poniższe wartości:
BULK_GOODS – ładunek przestrzenny
FORWARDING_AGENCY – towar spedycyjny****
BOOK_RATE – Przesyłka książek
CONSIGNMENT_OF_GOODS – Przesyłka towarowa
Rodzaj dostawy
dispatchType
String
* Jeżeli chcesz podać numer artykułu producenta, wtedy wymagane jest także podanie nazwy producenta.
** Format dateTime ma następującą specyfikację "YYYY-MM-DDThh:mm:ss" przy czym:
- YYYY Rok
- MM Miesiąc
- DD Dzień
portal.ayn.pl
- Znak T, że od tego punktu zaczyna się format czasu
- hh Godziny
- mm Minuty
- ss Sekundy.
*** Kategorie sklepu muszą zostać utworzone przed rozpoczęciem użytkowania. (Patrz Rozdział 4)
**** w przypadku towaru spedycyjnego jest zapytanie o numer klienta i jest on Ci później pokazany, aby umożliwić zaplanowanie dostawy
portal.ayn.pl
6 Kategorie produktów sklepu Sprzedającego
6.1
Opis merytoryczny
Sprzedający na All You Need ma własny sklep Sprzedającego. W nim wyświetlane są
wszystkie produkty, które Sprzedający oferuje, zarówno produkty Pasażu Handlowego z
ofertami Sprzedającego, jak i jego własne produkty.
Każdy Sprzedający ma możliwość korzystania z własnych kategorii sklepu. W tym celu musi
on najpierw ustalić kategorie dla swoich produktów i te wysłać do sklepu. Następnie można
dodać produkty z własnymi opisami i zdjęciami (patrz Rozdział 7). Kategorie sklepu można
zbudować hierarchicznie. Kategorie w sklepie Sprzedającego można ponownie usunąć. Jest
to jednak możliwe tylko wtedy, gdy w danych kategoriach - ewentualnie podkategoriach - nie
znajdują żadne produkty. Jeżeli Sprzedający chce w swoim sklepie korzystać z własnych
kategorii, wówczas musi to oznaczyć na swoim sklepie. W tym celu konieczne jest zwrócenie
się do działu wsparcia o aktywację. W pozostałych wypadkach przyjmuje się jako podstawę
do oferowanych produktów strukturę kategorii Pasażu Handlowego i część tej struktury
odpowiednio wypełniona ofertami jest pokazywana w sklepie Sprzedającego. Kategorie
sklepu są opcjonalne, mimo to kategoria Pasażu Handlowego pozostaje daną obligatoryjną.
6.2
Definiowanie
Poniższe dane są wymagane do tworzenia kategorii. Opis lub model hierarchiczny jest do
tego tworzenia opcjonalny, nie konieczny. Tabela zawiera atrybuty, które korespondują z
opisem technicznym w common.xsd und product.xsd i każdorazowo krótki opis zawartości:
Tworzenie kategorii:
Nazwa
ID kategorii
Nazwa
kategorii
Atrybut
code
name
Opis kategorii shortDescription
Kategoria
nadrzędna
portal.ayn.pl
parent
Typ
string
Długość
100
Pole
obowiązkowe
Opis
tak
Unikalny ID kategorii sklepu:
Każda kategoria posiada
unikalny kod kategorii, który
jednak w sklepie nie jest
widoczny. Służy on do
identyfikacji kategorii.
string
100
tak
Nazwa kategorii produktu:
Ta nazwa jest wyświetlana w
sklepie. Każda kategoria
nadrzędna
i
wszystkie
podrzędne kategorie danej
nadrzędnej kategorii muszą
mieć jednoznaczną nazwę.
string
100
nie
Krótki opis kategorii
nie
Kategoria nadrzędna: Musi
ona
zostać
utworzona
odpowiednio wcześniej, co
jest możliwe w tym samym
"uploadRequest".
string
100
7 Oferty produktów Sprzedającego
7.1
Opis merytoryczny
Dodatkowo oprócz produktów Pasażu Handlowego każdy Sprzedający może ustawiać w
swoim sklepie i na All You Need swoje własne produkty, których nie zawiera katalog DHL.
Ewentualnie może on wysłać do swojego sklepu własny opis do istniejących produktów DHL.
Aby produkty stały się widoczne, oprócz ich opisów wymagane są oferty, jak opisano w
Rozdziale 4. W tym rozdziale nie powtarza się opisu oferty, lecz definiuje tylko dodatkowe
pola.
Produkty bezpośrednio po wysłaniu danych na serwer nie są dostępne do sprzedaży. Może
dojść do pewnego przesunięcia czasowego, ponieważ musi zostać przeprowadzona
indeksacja produktów za pomocą wewnętrznej wyszukiwarki. Także tu, analogicznie do
Pasażu Handlowego, pojawia się informacja zwrotna, czy produkty zostały wysłane
bezbłędnie.
Prawidłowo wysłane na serwer dane produktów pozostają aktywne do sprzedaży w sklepie
Sprzedającego do momentu spełnienia się jednego z poniższych warunków:

podana liczba sztuk produktu została sprzedana lub jest zarezerwowana

dla danej oferty produktowej Sprzedający podał datę zakończenia i ten dzień właśnie
nadszedł

sklep Sprzedającego jest off-line lub zablokowany

konto Sprzedającego nie jest już aktywne lub złożono wypowiedzenie

produkt został zablokowany
Do zmiany lub aktualizacji już wysłanych produktów wymagany jest zawsze pełny opis
produktu. Nie można aktualizować pojedynczych pól.
Produkty Sprzedającego, których dane zostały wysłane do Pasażu Handlowego, można
ponownie usunąć. Jednocześnie zostanie również usunięta oferta Sprzedającego na ten
produkt.
7.2
Definiowanie
Dla każdego pojedynczego produktu, który ma być oferowany, oprócz Informacji ofertowych
w Rozdziale 4 wymagane są poniższe dane. Tabela zawiera atrybuty, które korespondują z
opisem technicznym w następnym rozdziale i każdorazowo krótki opis zawartości.
portal.ayn.pl
Wysyłanie danych produktu
Nazwa
ID produktu
Sprzedającego
Atrybut
productId
Typ
Długość
Pole
obowiązkowe
Opis
string
100
tak
Pasaż handlowy ID
meinPaketId
produktu
string
100
nie
European article
number
ean
string
13
nie
„European Article Number“, EAN produktu; w przypadku książek ISBN-13
Producent
manufacturerName string
100
nie
Nazwa producenta*
Numer artykułu
producenta
manufacturerPN
string
100
nie
Nazwa produktu
name
string
100
tak
Nazwa produktu
Krótki opis
produktu
shortDescription
string
200
tak
Krótki opis produktu***
Długi opis produktu longDescription
string
4000
nie
Szczegółowy opis produktu***
Zdjęcie
image
image 512
nie
URL do zdjęcia produktu Sprzedającego. Maksymalna wielkość 2 MB
Kategoria w
Pasażu
Handlowym
marketplaceCateg
orie
string
100
tak
Kategoria produktu w Pasażu Handlowym
Kategoria w
sklepie
Sprzedającego
shopCategorie
string
100
nie
Kategoria produktu we własnym sklepie Sprzedającego**
Kod atrybutu
code
string
100
tak
Unikalny ID atrybutu. Ten kod identyfikuje dla każdego Sprzedającego
każdy atrybut.
Nazwa atrybutu
name
string
100
nie
Nazwa cechy produktu jak wymiary, kolory etc.
Wartość atrybutu
value
string
100
nie
Wartość atrybutu
string
100
nie
Jednostka atrybutu unit
portal.ayn.pl
** W przypadku nr referencyjnego do kategorii sklepu Sprzedającego należy zwrócić uwagę na to, że są one utworzone, patrz Rozdział 6.
*** dozwolone Tagi HTML patrz Załącznik B
portal.ayn.pl
Zasadniczo można usunąć wszystkie opisy produktu i oferty produktu. Jeżeli opisy
produktów i oferty produktów odnoszą się do jeszcze nie zakończonego zamówienia
(anulowanego lub nadanego jako przesyłka), wtedy nie mogą one zostać skasowane.
Dopiero po zakończeniu realizacji zamówienia możliwe jest skasowanie odnośnych opisów
produktów i ofert produktów.
Proszę zwrócić uwagę na to, że mogą istnieć zamówienia, nawet jeżeli nie pojawiają się one
na Twoim koncie. Chodzi tu o zamówienia jeszcze nie przetworzone przez „internetowy
Pasaż handlowy“ lub o zamówienia, za które ma być pobrana zapłata z góry.
portal.ayn.pl
8 Warianty produktu
Aby ustawić produkt w różnych wariantach na All You Need, należy przeprowadzić
następujące trzy etapy:
1. Identyfikacja konfiguracji wariantów
Konfiguracja wariantów określa cechy, którymi różnią się warianty produktu.
Pasaż Handlowy udostępnia dla różnych zakresów asortymentów wstępnie
zdefiniowane konfiguracje wariantów, aby ujednolicić tworzenie wariantów w Pasażu
Handlowym. Definiuje z reguły wartości domyślne atrybutów. Jednakże w
określonych przypadkach wartości wariantów nie są podane przez „internetowy
Pasaż handlowy“ jako obligatoryjne.
I tak, Sprzedający mogą przykładowo określić atrybut "Kolor" po prostu
wprowadzeniem opcji bez tekstu. Inne wartości są, zależnie od naszej definicji, albo
wartościami tekstowymi albo liczbowymi.
Teraz proszę określić, jakie konfiguracje wariantów pasują do Twojego produktu.
2. Definiowanie grupy wariantów
Grupa wariantów odzwierciedla wszystkie warianty produktu dostępne w Pasażu
Handlowym. Po określeniu w etapie 1, jakie konfiguracje wariantów pasują do
Twojego produktu, proszę teraz utworzyć grupę wariantów.
Przykład: Chcesz oferować produkt "Koszula Boss z nadrukiem XY" w różnych
rozmiarach. W etapie 1 określiłeś w tym celu konfigurację udostępnioną przez
„internetowy Pasaż handlowy“ (w przykładzie "Ubranie z USA"). Teraz proszę
utworzyć dla produktu odpowiednią grupę wariantów przydzielić jej unikalny kod do
własnego użytku (np. "Koszula Boss 001") i nazwę jako opis grupy produktów (np.
"Koszula Boss z nadrukiem XY"). Uwaga: Nazwa, którą nadajesz grupie produktów,
pojawia się na liście wyników wyszukiwania – jako przedstawiciel konkretnych
pojedynczych artykułów danej grupy produktów.
3. Wysyłanie wariantów
Teraz możesz ustawiać i oferować w Pasażu Handlowym warianty produktu tak jak
zwykłe produkty, przy czym tylko grupa wariantów utworzona przez Ciebie w etapie 2
musi mieć odniesienie i muszą zostać podane atrybuty wariantów.
Poniższy diagram obrazuje wysyłanie danych wariantów produktu na „internetowy
Pasaż handlowy“ jeszcze raz:
portal.ayn.pl
Konfiguracja
Grupa wariantów
Atrybut1: Rozmiar
"Koszula Boss z nadrukiem XY"
Atrybut2: Kolor
Warianty produktu
8.1
S
S
S
M
XL
XL
czarny
biały
niebieski
niebieski
zielony
czarny
Definiowanie grupy wariantów
Poniższe dane są niezbędne do tworzenia grup wariantów produktu. Tabela zawiera
atrybuty, które korespondują z opisem technicznym w następnym rozdziale i każdorazowo
krótki opis zawartości.
Grupa wariantów
Długość
Pole
obowiązkowe
string
100
tak
Unikalna identyfikacja grupy
wariantów, np. "Levis501"
Kod konfiguracji configuration
string
100
tak
Unikalny
nr
referencyjny
istniejącej konfiguracji
Tytuł grupy
string
4000
nie
Tytuł grupy, np. "Levis Jeans
501"
Nazwa
Grupa
wariantów
8.2
Atrybut
code
title
Typ
Opis
Definiowanie konfiguracji wariantów
Poniższe dane są niezbędne do opisu produktu z wariantami. Chodzi tu o opis (analogicznie
do Rozdziału 7.2) rozszerzony o grupę wariantów. Tabela zawiera wartości, które
korespondują z opisem technicznym w następnym rozdziale i każdorazowo krótki opis
zawartości.
portal.ayn.pl
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
ID produktu
Sprzedającego
productId
string
100
tak
Pasaż handlowy
ID produktu
meinPaketId
string
100
nie
European article
number
ean
string
13
nie
„European Article Number“, EAN produktu; w przypadku książek
ISBN-13
Producent
manufacturerName
string
100
nie
Nazwa producenta*
Numer artykułu
producenta
manufacturerPN
string
100
nie
Grupa
wariantów
variantGroupCode
string
100
nie
Grupa wariantów
Nazwa produktu
name
string
100
tak
Nazwa produktu
Krótki opis
produktu
shortDescription
string
200
tak
Krótki opis produktu
Długi opis
produktu
longDescription
string
4000
nie
Szczegółowy opis produktu
Zdjęcie
image
image 512
nie
URL do zdjęcia produktu Sprzedającego. Maksymalna wielkość 2
MB
Kategoria w
Pasażu
Handlowym
marketplaceCategorie
string
100
tak
Kategoria w
sklepie
Sprzedającego
shopCategorie
string
100
nie
Kategoria produktu we własnym sklepie Sprzedającego
Kod atrybutu
code
string
100
tak
Unikalny ID atrybutu. Ten
Sprzedającego każdy atrybut
**Nazwa
atrybutu
name
string
100
nie
Określone cechy produktu jak wymiary, kolory itp.
portal.ayn.pl
kod
identyfikuje
dla
każdego
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
**Wartość
atrybutu
value
string
100
nie
Wartość atrybutu
**Jednostka
atrybutu
unit
string
100
nie
**Mogą to być zarówno atrybuty wariantów jak i dodatkowe atrybuty produktu.
*** Jeżeli ten identyfikator jest wysyłany dla więcej niż jednego produktu danej grupy wariantów, wtedy jest on zawsze nadpisywany.
portal.ayn.pl
9 Przykłady konfiguracji wariantów różnych asortymentów
9.1
Market budowlany
Przykład: Sprzedajesz "gwoździe z łbem wpuszczanym” w trzech wymiarach:
3,8 x 100 mm, 4,2 x 120 mm i 4,6 x 130 mm
Postępujesz w następujący sposób:
Wybierasz z przeglądu udostępnionych przez nas konfiguracji wariantów konfigurację
"Wymiary". Tu możesz wpisać w polu tekstowym swoje wymiary, np. właśnie "3,8 x 100".
Nazwą Twojej grupy wariantów powinna być po prostu nazwa produktu: "Gwoździe z łbem
wpuszczanym", bez dopisków wymiarów poszczególnych artykułów.
Konfiguracja
wariantów
Atrybut
Wartość
atrybutu 1
Wartość
atrybutu 2
Wartość
atrybutu 3
Wymiar
3,8 x 100
4,2 x 120
4,6 x 130
Jedn.:
mm
mm
mm
Wymiar
9.2
Książki
Przykład: Prowadzisz księgarnię i sprzedajesz książkę Johna R. R. Tolkiena "Władca
Pierścieni" w różnych formatach: jako wydanie zszywane, jako wydanie kieszonkowe i jako
audiobook na CD.
"Format książki". "Format książki" podaje Ci wartości atrybutu, z których po prostu wybierasz
właściwą.
Nazwą Twojej grupy wariantów powinna być prosta nazwa produktu: "Władca Pierścieni",
bez dodatkowych danych poszczególnych wydań.
Konfiguracja
wariantów
Format książki
portal.ayn.pl
Atrybut
Format
Wartość
Wartość
Wartość
atrybutu 1
atrybutu 2
atrybutu 3
wydanie
wydanie
audiobook na
zszywane
kieszonkowe
CD
9.3
Sprzęt elektroniczny powszechnego użytku
Przykład: Prowadzisz sklep ze sprzętem elektronicznym i sprzedajesz "Apple iPod Nano" w
różnych kolorach i z pamięcią o różnej wielkości.
Wybierasz z przeglądu udostępnionych przez nas konfiguracji wariantów podwójną
konfigurację "Kolor-Wielkość". "Kolor" wpisujesz w wolnym polu tekstowym, np. "czarny".
"Wielkość" pamięci podajesz jako liczbę i możesz dodatkowo z podanych jednostek wybrać
"GB", co oznacza gigabajty. Z tego wynika dla parametru "Wielkość", np. dana: 16 GB
Nazwą Twojej grupy wariantów powinna być po prostu nazwa produktu: "Apple iPod Nano",
bez dopisków jak kolor lub pamięć poszczególnych artykułów.
Konfiguracja
wariantów
Atrybut
Wartość
atrybutu 1
Wartość
atrybutu 2
Wartość
atrybutu 3
Kolor
Kolor
czarny
niebieski
srebrny
Format
8
16
16
Jedn.
GB
GB
GB
Wielkość
9.4
Filmy
Przykład: Oferujesz film "Alicja w Krainie Czarów" w różnych formatach, jako "DVD", "Bluray" i "Blu-ray 3D".
"Format filmu". "Format filmu" podaje Ci wartości atrybutu, z których po prostu wybierasz
właściwą. Nazwą Twojej grupy wariantów powinna być prosta nazwa produktu: "Alicja w
Krainie Czarów”, bez dodatkowych danych poszczególnych wydań.
Konfiguracja
wariantów
Format filmu
portal.ayn.pl
Atrybut
Format
Wartość
Wartość
Wartość
atrybutu 1
atrybutu 2
atrybutu 3
DVD
Blu-ray
Blu-ray 3D
9.5
Gry
Przykład: Oferujesz grę "FIFA 12" w różnych formatach:
na PC, Playstation 3 i Wii.
"Platforma gry". "Platforma gry" podaje Ci wartości atrybutu, z których po prostu wybierasz
właściwą. Nazwą grupy wariantów powinna być prosta nazwa produktu: "FIFA12", bez
dodatkowych danych poszczególnych artykułów.
Konfiguracja
wariantów
Atrybut
Wartość
atrybutu 1
Wartość
atrybutu 2
Wartość
atrybutu 3
Platforma gier
Platforma
PC
Playstation 3
Wii
9.6
Sprzęt AGD
Przykład: Oferujesz "Kawiarkę Bodum Chambord" w dwóch kolorach "srebrnym" i "czarnym"
i w trzech wielkościach 0,35 l, 1 l i 1,5 l.
konfigurację "Kolor-Wielkość". "Kolor" wpisujesz w wolnym polu tekstowym, np. "czarny".
"Wielkość", w tym przypadku daną w litrach, podajesz jako liczbę i możesz dodatkowo
wybrać jednostkę np. "l" dla litra. Z tego wynika dla parametru "Wielkość", np. dana: "1,5 l".
Nazwą grupy wariantów powinna być prosta nazwa produktu, bez dopisków jak dane o
kolorze lub pojemności poszczególnych artykułów.
Konfiguracja
wariantów
Kolor
Wartość
Wartość
Wartość
atrybutu 1
atrybutu 2
atrybutu 3
Kolor
czarny
srebrny
srebrny
Format
0.35
1.0
1.5
Jedn.
l
l
l
Atrybut
Wielkość
portal.ayn.pl
9.7
Artykuły spożywcze
Przykład: Prowadzisz sklep z artykułami spożywczymi i oferujesz "Steki T-bone" w różnych
ilościach: 2, 3 lub 5 sztuk.
konfigurację "Wielkość".
"Wielkość" to w tym przypadku "ilość sztuk", podaj liczbę i wybierz jedną jednostkę
dowolnego wyboru, jak np. szt. Z tego wynika dla parametru "Wielkość", np. dana "5 szt.".
Nazwą Twojej grupy wariantów powinna być po prostu nazwa produktu: "Steki T-bone", bez
dopisków jak ilość, które charakteryzują poszczególne artykuły.
Konfiguracja
wariantów
Atrybut
Wartość
atrybutu 1
Wartość
atrybutu 2
Wartość
atrybutu 3
Wielkość
2
3
5
Jedn.
Szt.
Szt.
Szt.
Wielkość
9.8
Soczewki kontaktowe
Przykład: Oferujesz soczewki kontaktowe o promieniu krzywizny 8,6 mm, o mocy -6,50, 6,00 i -5,50 dioptrii i średnicy 14,2 mm.
Wybierasz z przeglądu udostępnionych przez nas konfiguracji wariantów "Soczewki
kontaktowe". Atrybuty "Promień krzywizny", "Moc" i "Średnica" można podać wraz z
pasującymi jednostkami: mm dla "Promienia krzywizny", dioptrie dla "Mocy" i mm dla
"Średnicy".
Nazwą Twojej grupy wariantów powinna być po prostu nazwa produktu: "soczewki
kontaktowe Richter 30 AS UV", bez dopisków, które charakteryzują poszczególne artykuły.
portal.ayn.pl
Konfiguracja
wariantów
Wartość
Wartość
Wartość
atrybutu 1
atrybutu 2
atrybutu 3
8.6
8.6
8.6
Jedn.
mm
mm
mm
Moc
-6.50
-6.00
-5.50
Jedn.
dpt
dpt
dpt
Średnica
14.2
14.2
14.2
Jedn.
mm
mm
mm
Atrybut
Promień
krzywizny
Soczewki
kontaktowe
portal.ayn.pl
10 Przegląd konfiguracji wariantów „internetowy Pasaż handlowy“
10.1 Powszechnie stosowane konfiguracje wariantów
Konfiguracja
Atrybut
Typ
Wstępnie
zdefiniowane
wartości
Jednostki opcjonalne
Kolor
Kolor
Tekst
-
ml, l, g, kg, mm, cm, m,
m2, m3, MB, GB,TB,
megapiksele, cale, szt.,
W
Wielkość
Wielkość
Liczba
-
Wymiar
Wymiar
Tekst
-
Kolor
Tekst
-
-
Kolor-Wielkość
Kolor-Wymiar
Styl
Wielkość
Liczba
-
m2, m3, MB, GB,TB,
W
Kolor
Tekst
-
-
Wymiar
Tekst
-
mm, cm, m
Styl
Tekst
-
-
Styl
Tekst
-
-
Wielkość
Liczba
-
ml, l, g, kg, szt., cl, dl
Materiał
Tekst
-
-
Materiał
Tekst
-
-
Wymiar
Tekst
-
Materiał
Tekst
-
-
Styl-Wielkość
Materiał
Materiał-Wymiar
Materiał-Wielkość
Model
portal.ayn.pl
mm, cm, m
mm, cm, m
Wielkość
Liczba
-
m2, m3, MB, GB,TB,
W
Model
Tekst
-
-
10.2 Konfiguracje wariantów dla asortymentów Książka, Film i Gry
Konfiguracja
Format książki
Format filmu
Platforma gier
Wstępnie
zdefiniowane
wartości
Atrybut
Typ
Format
wydanie zszywane
wydanie kieszonkowe,
Tekst broszura,
audiobook CD
kaseta audio
Format
DVD
Blu-ray,
Blu-ray 3D,
Tekst Blu-ray + DVD,
DVD + CD,
HD-DVD,
UMD wideo
Platforma
PC
Mac,
PlayStation,
PlayStation 2,
PlayStation 3,
PlayStation Portable,
Wii,
Xbox,
Xbox 360,
Tekst
Nintendo 3DS,
Nintendo DS,
Game Boy,
Game Boy Advance,
Game Cube,
Nintendo 64,
N-Gage,
Sega Dreamcast,
Sega Saturn
-
10.3 Konfiguracje wariantów soczewek kontaktowych
Konfiguracja
Soczewki
kontaktowe
portal.ayn.pl
Wstępnie
zdefiniowane
wartości
Atrybut
Typ
Promień
krzywizny
Liczba -
mm
Moc
Liczba -
dpt
Średnica
Liczba -
mm
10.4 Konfiguracje wariantów dla asortymentu Moda
Konfiguracja
Ubrania z UE
Atrybut
Typ
Kolor
Tekst -
-
Rozmiar
Liczb
a
-
Kolor
Tekst -
-
Rozmiar
XXS, XS, S, M, L, XL,
Tekst XXL, XXXL, 4XL, 5XL, 6XL, 7XL
Kolor
Tekst -
Ubrania z USA
Skarpety
Rozmiar
portal.ayn.pl
-
15-18, 19-22, 23-26,
19-22, 23-26, 27-30,
Tekst 31-34, 35-38, 39-42,
43-46, 47-48, 48-50
-
Kolor
Tekst -
Długość
Liczb 28, 30, 32, 34, 36, 38,
a
40, 42
Szerokość
24,
30,
36,
Liczb
42,
a
48,
54,
60
Kolor
Tekst -
Obwód
biustu
45, 50, 55, 60, 65, 70,
75, 80, 85, 90, 95,
Liczb
100, 105, 110, 115, a
120, 125, 130, 135,
140, 145, 150
Miseczka
Tekst
Jeans
Biustonosze
Wstępnie
zdefiniowane
wartości
-
25,
31,
37,
43,
49,
55,
26,
32,
38,
44,
50,
56,
27,
33,
39,
45,
51,
57,
28,
34,
40,
46,
52,
58,
29,
35,
41,
47, 53,
59,
-
AA, A, B, C, D, DD, E,
EE, F, FF, G, GG, H
11 Kategorie do pobrania
11.1 Opis merytoryczny
„internetowy Pasaż handlowy“ daje możliwość pobrania przeglądu kategorii do Pasażu
Handlowego oraz do własnego sklepu Sprzedającego. Pobieranie odbywa się poprzez
"downloadRequest", a przy tym konieczne jest jedynie rozróżnienie pomiędzy pasażem
handlowym i sklepem Sprzedającego.
Wynik zawiera dodatkowo, oprócz kategorii z możliwą hierarchią, także nazwy i opisy
wprowadzonych atrybutów, które stosuje się do wyszukania produktów lub do przeglądania
fasetowego.
11.2 Definiowanie
Poniższe dane są niezbędne do pobrania kategorii. Tabela zawiera atrybuty, które
zawartości.
portal.ayn.pl
Wywoływanie kategorii
Nazwa
Struktura
katalogu
Atrybut
catalogstructure
Typ
Długość
string
Pole
obowiązkowe
nie
Opis
Podaje strukturę katalogu: Z "marketplace" dla Pasażu Handlowego, z "shop"
dla sklepu Sprzedającego. Jeżeli nie zawiera żadnej wartości, to wysyłany jest
sklep Sprzedającego.
Informacja zwrotna opisu kategorii
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
string
100
tak
Unikalny ID kategorii sklepu. Każda kategoria posiada unikalny kod kategorii,
który jednak w sklepie nie jest widoczny. Służy on do identyfikacji kategorii.
Nazwa kategorii name
string
100
tak
Nazwa kategorii produktu. Ta nazwa jest wyświetlana w sklepie.
Opis kategorii
shortDescription
string
100
nie
Krótki opis kategorii
Kategoria
nadrzędna
parent
string
100
nie
ID nadrzędnej kategorii.
Kategoria
zablokowana
deprecated
boolean
nie
Jeżeli "prawda" wtedy nie można użyć tej kategorii do wysyłania produktów na
serwer. Dlatego przesyła się tylko kategorie z "fałsz".
ID kategorii
portal.ayn.pl
code
12 Oferty produktów do pobrania
Pasaż Handlowy daje Sprzedającemu możliwość pobrania przeglądu oferowanych przez
niego produktów. Pobieranie odbywa się poprzez "downloadRequest".
W wyniku wysyłany jest unikalny kod identyfikacyjny produktu, jak również specyficzna dla
danego Sprzedającego oferta. Dostarczane są z powrotem zawsze wszystkie oferty produktu
Sprzedającego.
12.2 Definiowanie
Do pobrania ofert produktów nie jest wymagane podanie żadnych specyficznych danych,
wystarcza wysłanie jedynie żądania.
Informacja zwrotna opisu kategorii
W informacji zwrotnej są wysyłane poniższe atrybuty. Tabela zawiera atrybuty, które
zawartości.
portal.ayn.pl
Nazwa
ID produktu
Sprzedającego
Atrybut
productId
Typ
Długość
Pole
obowiązkowe
Opis
string
100
tak
Pasaż handlowy
meinPaketId
ID produktu
string
100
nie
European article
Ean
number
string
13
nie
"European Article Number", EAN produktu.
Dla książek ISBN-13.
Producent
manufacturerName
string
100
nie
Nazwa producenta*
Numer artykułu
producenta
manufacturerPN
string
100
nie
Cena
jednostkowa
unitprice
doubl
e
nie
Cena na każdą jednostkę
nie
Jednostka ilości produktu:
Sztuka = „per_piece“
Kilogram = “per_1kg”
Litr =”per_1l”
Metr sześcienny =“per_1m3“
Metr =“per_1m“
Metr kwadratowy =”per_1m2”
Gram =”per_100g”
Mililitr =”per_100ml”
Jednostka miary Unit
string
Klasyfikacja
podatkowa
taxGroup
taxGr
oup
nie
Podatek VAT zawarty w cenie sprzedaży. "Standard" (aktualnie 19%),
"Reducted" (aktualnie 7%) i "Free" dla artykułów bez podatku VAT. Jeżeli to
pole nie jest wypełnione, wtedy jest ustawiany "Standard".
Dostępność
availability
intege
r
tak
Dostępna liczba sztuk tego produktu. Liczba sztuk przy każdej sprzedaży
jest automatycznie przeliczana w dół. Jeżeli liczba sztuk wynosi 0 wtedy
produkt jest wyświetlany jako wyprzedany.
Data
początkowa
startDate
dateTi
me
nie
Data, od kiedy produkt jest dostępny do zamówień Klienta, tzn. jest widoczny
w Pasażu Handlowym u tego Sprzedającego. Data musi być wysłana w
portal.ayn.pl
100
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
następującym formacie: YYYY-MM-DDThh:mm:ss **
Data
zakończenia
endDate
dateTi
me
nie
Data, od której produkt nie jest już dostępny, tzn. nie jest ani widoczny, ani
nie można go zamówić. Data musi być wysłana w następującym formacie:
YYYY-MM-DDThh:mm:ss **
Kategoria w
sklepie
Sprzedającego
shopCategory
categ
100
oryRef
nie
Kategoria produktu we własnym sklepie Sprzedającego***
- YYYY rok
- MM miesiąc
- DD dzień
- T oznaczenie, oznaczenie, że od tego miejsca zaczyna się format czasu
- hh godziny
- mm minuty
- ss sekundy
*** Wysyła się tylko wtedy, jeżeli Sprzedający zdefiniował własną strukturę kategorii.
portal.ayn.pl
13 Wywołanie wskaźników
Dla każdego Sprzedającego na All You Need w odniesieniu do różnych usług interfejsów jest
dostępny określony wskaźnik, tzn. jak często możesz korzystać z danej usługi. I na przykład,
odnośnie wysyłania danych produktu jest on zależny od tego, jak dużo masz produktów i
ofert.
Dzięki temu gwarantujemy, że dla każdego Sprzedającego jest dostępnych wystarczająco
dużo zasobów interfejsu. Ponadto zapewnia to czystą i wydajną pracę podłączenia do All
You Need .
Za pomocą zdefiniowanego tu żądania możesz wywołać Twój aktualny dostępny wskaźnik.
W sytuacji gdy miałby on nie być wystarczający (może to wystąpić głównie w przypadku
nowych Sprzedających bez produktów) proszę o kontakt z Działem Wparcia (patrz Rozdział
24 dane kontaktowe).
13.2 Definiowanie
Do pobrania ofert produktów nie jest potrzebne podanie żadnych specyficznych danych,
wystarcza wysłanie żądania.
Informacja zwrotna o wskaźniku
W informacji zwrotnej są wysyłane poniższe atrybuty. Tabela zawiera atrybuty i ich opis
zawartości.
Nazwa
Atrybut
Typ
Długoś Pole
Opis
ć
obowiązkowe
Nazwa usługi
name
string
100
Dostępne
żądania
availableSingle
Request
int
Dostępne
wywołania
availableCallCo
int
unt
Dostępne
żądania
availableConcur
int
rentRequest
tak
Nazwa
usługi,
która
ograniczona wskaźnikiem.
jest
nie
Podaje dostępną jeszcze liczbę
żądań danej usługi.
nie
Podaje dostępną jeszcze liczbę
wywołań danej usługi. Ten
parametr obecnie nie jest
jeszcze wykorzystywany.
nie
Podaje liczbę żądań, które
mogą jeszcze zostać ustawione
w
asynchronicznej
kolejce
oczekiwania.
Częstotliwość
wywoływania
availableFreque
int
ncy
nie
Podaje częstotliwość, z jaką
można ustawić nowe żądania
danej usługi. Ten parametr
obecnie
nie
jest
jeszcze
wykorzystywany.
Jednostka
częstotliwości
frequencyUnit
nie
Jednostka
częstotliwości.
Możliwe wartości: TYDZIEŃ,
DZIEŃ, GODZINA, MINUTA
portal.ayn.pl
int
14 Usuwanie
Na All You Need można usuwać opisy produktów, oferty produktów i kategorie sklepu. Jeżeli
są zamieszczone tylko oferty produktów, wtedy Sprzedający może usunąć tylko tę ofertę.
Jeżeli Sprzedający ma oferty produktów i opisy produktów, wtedy można usunąć je tylko
razem. Żądanie jest w obydwu wypadkach identyczne. Pasaż Handlowy uniemożliwia
usuwanie tak długo, dopóki są otwarte zamówienia określonego produktu. Tak samo nie
można usunąć kategorii, jeżeli zawierają one jeszcze jakieś produkty.
14.2 Definiowanie
Poniższe dane są niezbędne do pobrania kategorii. Tabela zawiera atrybuty i ich opis
zawartości.
portal.ayn.pl
Usuwanie kategorii
Nazwa
Struktura
katalogu
Atrybut
catalogstructure
Typ
Długość
string
Pole
obowiązkowe
nie
Opis
Dla Pasażu Handlowego należy tu wpisać "marketplace", dla własnego
sklepu można wpisać "shop", jeśli pole nie będzie zawierać żadnej wartości,
zostanie wysłany sklep Sprzedającego.
Usuwanie produktów
Nazwa
ID produktu
Sprzedającego
Atrybut
Długość
Pole
obowiązkowe
Opis
string
100
tak
Pasaż handlowy
meinPaketId
ID produktu
string
100
nie
Unikalny numer artykułu „Pasaż handlowy“
European article
ean
number
string
13
nie
„European Article Number“, EAN produktu. Dla książek ISBN-13
Producent
manufacturerName
string
100
nie
Nazwa producenta
Numer artykułu
producenta
manufacturerPN
string
100
nie
portal.ayn.pl
productId
Typ
15 Podstawy merytoryczne i przegląd interfejsów procesu
zamówienia
Między All You Need, Klientami, a Sprzedającymi mają miejsce różne etapy komunikacji.
Proces ten rozpoczyna się poprzez zamówienie Klienta, złożone w Pasażu Handlowym,
zakupów on-line. Klient może zamówić jeden lub kilka produktów, u jednego lub kilku
Sprzedających. Ma to miejsce wtedy, gdy Klient idzie ze swoim koszykiem "do kasy" i kończy
swoje zamówienie.
Pasaż Handlowy udostępnia dla każdego Sprzedającego złożone zamówienia jako
"Zamówienie" gotowe do wywołania. Sprzedający może sam wybrać czas, w którym on
wywołuje zamówienia, jak również częstotliwość wywołań. Zamówienie może być
wywoływane dowolnie często. Może to się odbywać poprzez podanie okresu i statusu lub
poszczególnych numerów zamówień.
Gdy tylko zamówiony towar zostanie wysłany w przesyłce przez Sprzedającego, przekazuje
on tę informację do Pasażu Handlowego. W ten sposób zostaje uruchomiony proces zapłaty,
który w tym dokumencie nie będzie szerzej omawiany. Sprzedający może z informacją o
przesyłce wysłać jednocześnie dane do śledzenia przesyłki, o ile są one już znane.
Informacje do śledzenia przesyłki mogą również zostać przekazane później. Po podaniu
informacji dotyczących przesyłki, dostawa i faktura muszą zostać wysłane do Klienta.
portal.ayn.pl
Klient może z różnych powodów odesłać z powrotem do Sprzedającego dostawę lub także w
przypadku kilku produktów tylko część z nich. Może to nastąpić z powiadomieniem lub bez.
Sprzedający ocenia te zwroty i przekazuje informację do All You Need. Tam rozpoczyna się
odpowiednia procedura cofnięcia zapłaty.
Sprzedający może anulować zamówienia produktów, które nie są już dostępne. Możliwe jest
anulowanie całego zamówienia lub także, w przypadku kilku produktów, również jedynie jego
części. Sprzedający przekazuje informację o anulowaniu zamówienia do All You Need, które
przekazuje informację do Klienta.
Dla Klienta nie przewidziano procesu anulowania zamówienia. Może on jedynie wysłać
zapytanie, czy można przeprowadzić anulowanie zamówienia. Sprzedający otrzymuje taką
informację pocztą elektroniczną i może, o ile jest to jeszcze możliwe w procesie wysyłki,
uruchomić procedurę anulowania zamówienia. Jeśli życzenie Klienta, aby anulować
zamówienie nie zostanie uwzględnione, Klient może skorzystać z możliwości zwrotu.
Przegląd całego procesu zamówienia, poszczególne etapy tego procesu, zostały zestawione
dla Sprzedającego w poniższej tabeli. Ze szczegółowym i technicznym opisem można się
zapoznać w rozdziałach od 16 do 20:
Etapy procesu
zamówienia
Opis
Wywołanie zamówień
Sprzedający musi w regularnych odstępach czasu (np. co 60
min) wywoływać nowe zamówienia. Jeżeli są zamówienia,
udostępnia się je Sprzedającemu w formie pliku XML.
Zgłoszenie przesyłki
Zamówiony towar wysyłany jest przez Sprzedającego do Klienta.
Musi to zostać zgłoszone do All You Need.
Anulowanie
Artykuły, które nie mogą zostać dostarczone, należy wysłać do
All You Need jako anulowanie zamówienia
Informacje
dotyczące Jeżeli informacji dotyczących śledzenia przesyłki nie ma w
śledzenia przesyłki
zgłoszeniu przesyłki, można je przekazać później.
Zwroty
Jeżeli Sprzedający otrzyma z powrotem towar od Klienta, należy
to zgłosić do All You Need. Po takim zgłoszeniu rozpoczyna się
procedura cofnięcia zapłaty.
Diagram przebiegu tego procesu patrz załącznik B.
Do technicznego opisu (interfejsu) API istnieją dwa pliki xsd, common.xsd i orders.xsd. Plik
common.xsd zawiera definicje ogólne, które używane są także w dalszych zakresach API
Sprzedającego. Plik orders.xsd zawiera opisane w poniższych rozdziałach żądania oraz
specyficzne definicje tego interfejsu.
portal.ayn.pl
16 Zamówienie
Zamówienie w tym rozdziale rozpatrywane jest jako zakup towarów na All You Need i w
poszczególnych sklepach Sprzedających.
Jeżeli Klient idzie z jednym lub kilkoma produktami w koszyku do kasy, rozpoczyna on tym
samym proces zamówienia. Jeżeli proces ten jest zakończony, wtedy Sprzedający może
wywołać kompletne informacje dotyczące zamówienia w formie pliku XML. Sprzedający
może wywołać wszystkie zamówienia lub tylko te otwarte w wybranym okresie.
Poszczególne zamówienia można wywołać na podstawie ID zamówienia "OrderId" lub
swojego wewnętrznego numeru zamówienia Sprzedającego.
Plik zawiera wszystkie wymagane informacje zamówienia, a Sprzedający ma teraz
obowiązek przygotować odpowiedni towar do wysyłki, wystawić Klientowi fakturę i na koniec
wysłać ten towar wraz z fakturą. Gdy tylko towar zostanie wysłany, należy przekazać tę
informację do All You Need aby mógł zostać uruchomiony proces zapłaty.
Jeżeli towar, wbrew ofercie w Pasażu Handlowym lub w sklepie Sprzedającego, nie może
zostać dostarczony, Sprzedający musi niezwłocznie anulować daną pozycję zamówienia lub
ewentualnie całe zamówienie (patrz rozdział 19)
Zamówienie podzielone jest na różne obszary, unikalna identyfikacja, pozycje zamówienia,
adres dostawy lub adres do faktury, dane kontaktowe i rodzaj przesyłki.
Ogólnym nr referencyjnym zamówienia jest unikalny numer zamówienia. Do każdego
numeru zamówienia należą jedna lub kilka pozycji zamówienia z odpowiednimi informacjami
szczegółowymi.
Do wysyłki wymagany jest adres dostawy. Dodatkowo istnieje taka możliwość, że adres
dostawy jest inny niż adres na fakturze. Ponadto Klient ma możliwość wybrania rodzaju
przesyłki.
Do celów ewentualnych zapytań Sprzedającego dostarczany jest dodatkowo informacyjnie
numer Klienta. Opcjonalnie Sprzedający ma możliwość wymagania wraz z wywołaniem
zamówienia również adresu poczty elektronicznej Klienta. W przypadku tego adresu poczty
elektronicznej chodzi o adres wirtualny, który jest przekazywany przez All You Need.
Możesz również, jeśli sprzedajesz towary spedycyjne, poprosić o podanie Ci numeru
telefonu Klienta, w celu omówienia dostawy.
Jeżeli część zamówienia została właśnie wysłana przez Sprzedającego do Klienta i zostało
to również zgłoszone do All You Need, to takie informacje będą również zawarte w danych.
portal.ayn.pl
16.2 Definiowanie
Proces zamówienia zawiera poniższe dane. Pola, które są bezwzględnie wymagane, mają w
kolumnie "Pole obowiązkowe" - "tak". Pola, które nie są polami obowiązkowymi i nie są
wysyłane, nie są ustawiane lub są wypełniane wartością domyślną (patrz kolumna „Opis“).
Tabela zawiera atrybuty, które korespondują z opisem technicznym common.xsd i orders.xsd
i każdorazowo krótki opis zawartości:
Wywołanie zamówień
Poniższe dane są wymaganymi lub możliwymi do wywołania informacjami danego
zamówienia. Można przy tym wybrać tylko jedną możliwość, albo numer dyspozycji lub
zamówienia, albo poprzez wybór okresu czasu i statusu.
portal.ayn.pl
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
Alias adres
mailowy Klienta
getEmail
boolean
nie
"true" wysyła Alias adres mailowy Klienta
Numer telefonu
additionalInfo
Boolean
nie
„true“ wysyła numer telefonu w przypadku towaru spedycyjnego
Numer
zamówienia
orderId
string
nie
Unikalny numer zamówienia Pasaży Handlowego
Data od
dateFrom
Date
Data do
dateTo
Date
Status
zamówienia
orderStatus
string
100
Data od kiedy** zamówienia mają być wywoływane,
tak (jeżeli wybór
Format:
przez okres)
YYYY-MM-DDThh:mm:ss *
100
nie
Data do kiedy** zamówienia mają być wywoływane,
Format:
YYYY-MM-DDThh:mm:ss *
Jeżeli data nie zostanie podana, wtedy interfejs zakłada datę aktualną.
nie
Status zamówień "Open" = zamówienia otwarte i nie załatwione do końca "All" =
wszystkie zamówienia. Jeśli to pole nie zostanie podane, wysyłane jest zawsze
"Open".
- YYYY rok
- MM miesiąc
- DD dzień
- hh godziny
- mm minuty
- ss sekundy
** dla ograniczenia okresu za pomocą daty, należy zwrócić uwagę na to, że niekoniecznie chodzi o datę zamówienia, ponieważ może dojść do opóźnienia z powodu testów
bezpieczeństwa.
portal.ayn.pl
Zamówienie
Wszystkie informacje danego zamówienia są całkowicie podporządkowane unikalnym informacjom zamówienia. Unikalnym kluczem jest numer
zamówienia Pasażu Handlowego.
Nazwa
Atrybut
Typ
Numer
zamówienia
orderId
string
Data zamówienia
orderDate*
Długość
100
Pole
obowiązkowe
Opis
tak
Unikalny numer zamówienia Pasażu Handlowego
Date
tak
Dzień, w którym złożono zamówienie
Data zmiany
lastModificationD
Date
ate*
tak
Dzień, w której została przeprowadzona ostatnia zmiana w procesie
zamówienia.
Wartość
zamówienia
totalPrice
double
tak
Całkowita wartość zamówienia wraz z podatkiem VAT
Koszty przesyłki
totalDeliveryCost
double
s
tak
Koszty przesyłki dla całego zamówienia
- YYYY rok
- MM miesiąc
- DD dzień
- hh godziny
- mm minuty
- ss sekundy
portal.ayn.pl
Pozycja zamówienia
Zamówienie może zawierać dowolną liczbę produktów. Każdy zamówiony produkt opisany jest osobną pozycją zamówienia.
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
ID produktu
Sprzedającego
productID
string
100
tak
Pasaż handlowy
ID
meinPaketId
string
100
nie
Unikalny numer artykułu
European article
number
ean
string
13
nie
Nazwa produktu
name
string
100
tak
Nazwa produktu
Ilość
quantity
Integer
tak
Zamówiona ilość produktu
Cena sprzedaży
basePrice
double
tak
Aktualna cena sprzedaży wraz z ustawowym podatkiem VAT
Wartość
zamówienia
totalPrice
double
tak
Całkowita wartość zamówienia wraz z podatkiem VAT
Adres dostawy
Adres dostawy może składać się z nr referencyjnego paczkomatu, adresu filii lub z adresu pocztowego.
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
Numer pocztowy customerId
Klienta
string
100
nie
Unikalny numer pocztowy Klienta dla DHL Services (paczkomat, dostawa
na życzenie…)
Tytułowanie
salutation
string
100
nie
Tytułowanie (Pan, Pani)
Tytuł
Title
string
100
nie
Tytuł Klienta (prof., dr itp.)
Firma
company
string
100
nie
Nazwa firmy do adresu dostawy
Imię
firstName
string
100
tak
Imię odbiorcy przesyłki
portal.ayn.pl
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
Nazwisko
lastName
string
100
tak
Nazwisko odbiorcy przesyłki
Ulica
Street
string
100
nie*
Ulica (w przypadku adresów filii w tym polu wskazówka „filia“)
Numer domu
houseNumber
string
100
nie*
Numer domu
Dodatek do
adresu:
addressAddition string
100
nie
Dodatkowe informacje do adresu, jak np. c/o
Kod pocztowy
zipCode
string
100
tak
Kod pocztowy
Miejscowość
City
string
100
tak
Miejscowość
Kraj
Country
country
2
tak
Kod krajów ISO
* adres dostawy składa się z adresu pocztowego lub paczkomatu lub adresu filii
Adres na fakturze
Niezależnie od adresu dostawy może zostać podany osobny adres na fakturze. Adres na fakturze jest opcjonalny.
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
Tytułowanie
salutation
string
100
nie
Forma zwracania się do Klienta (Pan, Pani)
Tytuł
Title
string
100
nie
Tytuł Klienta (prof., dr itp.)
Firma
company
string
100
nie
Nazwa firmy do adresu do faktury
Imię
firstName
string
100
tak
Imię odbiorcy faktury
Nazwisko
lastName
string
100
tak
Nazwisko odbiorcy faktury
Ulica
street
string
100
tak
Ulica
Numer domu
houseNumber
string
100
tak
Numer domu
Dodatek do
adresu:
addressAddition string
100
nie
Dodatkowe informacje do adresu, jak np. c/o
Kod pocztowy
zipCode
100
tak
Kod pocztowy
portal.ayn.pl
string
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
Miejscowość
city
string
100
tak
Miejscowość
Kraj
country
country 2
tak
Kod krajów ISO
Dane do kontaktu
Jako nr referencyjny Klienta do ewentualnych zapytań dostarczany jest również numer Klienta.
Typ
Długość
Pole
obowiązkowe
Opis
string
100
tak
Unikalny numer Klienta Pasażu Handlowego
Alias
adres email
mailowy Klienta
string
100
nie
Alias adres mailowy Klienta.
Numer telefonu
phoneNumber
Klienta
String
100
Nie
Numer telefonu Klienta w przypadku towaru spedycyjnego
Nazwa
Numer klienta
Atrybut
customerId
Dostawa
Te informacje odnośnie przetworzonych zamówień przekazywane są tylko dla procesów zakończonych częściowo (jeżeli są):
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
Numer dostawy
consignmentId
string
100
tak
Wewnętrzny i unikalny numer dostawy Sprzedającego
Status dostawy
consignmentSta
string
tus
100
tak
Możliwe wartości: ["SHIPPED", "CANCELED", "DONE"]
portal.ayn.pl
Pozycja dostawy
Pozycje, które są zawarte we właśnie załatwionej dostawie częściowej.
Typ
Długość
Pole
obowiązkowe
Opis
ID
produktu
productID
Sprzedającego
string
100
tak
Pasaż handlowy
meinPaketId
ID
string
100
nie
European article
ean
number
string
13
nie
Ilość
Integer
tak
Dostarczona ilość produktu
Nazwa
portal.ayn.pl
Atrybut
quantity
17 Przesyłka towarów
Sprzedający jest zobowiązany do przesłania zamówionych pozycji po wpłynięciu
zamówienia, w podanym przez siebie czasie dostawy. Jeżeli nie mógłby dostarczyć
żądanych artykułów lub ich części, wtedy musi je niezwłocznie anulować, patrz Rozdział 19.
Gdy tylko procedura wysłania przesyłki została uruchomiona przez Sprzedającego, musi on
to zgłosić do All You Need, ponieważ uruchamia to procedurę płatności Klienta i
wynagrodzenia dla Sprzedającego. Po zgłoszeniu przesyłki nie jest już możliwe anulowanie
zamówienia lub jego części.
Sprzedający może zgłosić jako wysłane zarówno kompletne zamówienie, jak również jego
poszczególne pozycje. Dla każdego zgłoszenia przesyłki istnieje możliwość przekazania do
All You Need informacji do śledzenia przesyłki. Po dokonanym wysłaniu przesyłki,
Sprzedający otrzymuje zapłatę przez All You Need. Pieniądze za zamówienie wypłacane są
siedem dni po zgłoszeniu przesyłki.
17.2 Definiowanie
Do informacji zwrotnej "notificationRequest" Sprzedającego do All You Need wymagane są
pewne dane odnośnie przesyłki towarów. Te bezwzględnie wymagane pola mają w kolumnie
"Pole obowiązkowe" "tak". Pola, które nie są polami obowiązkowymi i nie są wysyłane, nie są
ustawiane lub są wypełniane wartością domyślną (patrz kolumna „Opis“). Tabela zawiera
atrybuty, które korespondują z opisem technicznym common.xsd i orders.xsd i każdorazowo
krótki opis zawartości:
Dostawa
Cała dostawa może składać się z kilku artykułów, które mogą zostać wysłane w więcej niż
jednej przesyłce ew. także w różnych terminach. Pozycje zebrane w jednej przesyłce do
wysłania, otrzymują numer dostawy. Jednemu numerowi zamówienia może być więc
przyporządkowany więcej niż jeden numer dostawy
portal.ayn.pl
Dostawa
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
Numer
zamówienia
orderId
string
100
tak
Unikalny numer zamówienia „internetowy Pasaż handlowy“
Numer dostawy
consignmentId
string
100
tak
Wewnętrzny i unikalny numer dostawy Sprzedającego
Numer śledzenia
trackingId
przesyłki
string
100
nie
Numer śledzenia przesyłki/kod przesyłki (opcja), dostępny tylko przy
wysyłkach paczek
Data wysyłki
shippingDate
Date
nie
Data wysyłki przez Sprzedającego
Przewidywana
data dostawy
deliveryDate
Date
nie
Przewidywana data dostawy dla Klienta
Pozycja dostawy
Pozycje dostawy są zestawieniem wszystkich produktów, które zawiera dostawa.
Nazwa
ID produktu
Sprzedającego
Atrybut
Długość
Pole
obowiązkowe
Opis
string
100
tak
Pasaż handlowy
meinPaketId
ID
string
100
nie
European article
ean
number
string
13
nie
„European Article Number“, EAN produktu; w przypadku książek ISBN-13.
Ilość
long
tak
Dostarczona ilość artykułów
portal.ayn.pl
productID
Typ
quantity
18 Śledzenie przesyłki
Jeżeli w chwili zgłoszenia przesyłki nie są jeszcze znane dane do jej śledzenia, mogą one
zostać dostarczone później oddzielnie.
Dostarczenie danych do śledzenia przesyłki zasadniczo nie jest obowiązkowe, prowadzi
jednak do lepszej przejrzystości dla Klienta, a tym samym także do większego zadowolenia
Klienta. Sprzedający jest proszony do przekazania danych do śledzenia przesyłki (patrz
Rozdział 17) natychmiast lub po wysłaniu dostawy.
Jeżeli numer dostawy "consignmentId" nie jest unikalny, można dodatkowo podać numer
zamówienia "orderId".
Numer śledzenia przesyłki może zostać napisany lub skasowany. Do skasowania
przekazywana jest dostawa lub zamówienie puste, do zastąpienia przekazywana jest
dostawa lub zamówienie, z nowym numerem śledzenia przesyłki.
18.2 Definiowanie
Do zgłoszenia danych do śledzenia przesyłki przez Sprzedającego do All You Need
wymagane są poniższe dane. Obydwa pola są przy tym polami obowiązkowymi. Tabela
zawiera atrybuty, które korespondują z opisem technicznym common.xsd i orders.xsd i
każdorazowo krótki opis zawartości:
Śledzenie przesyłki
Dla informacji śledzenia przesyłki wymagany jest jedynie numer śledzenia przesyłki, który
jest przyporządkowany do danej dostawy.
Nazwa
Numer dostawy
Atrybut
Typ
consignmentId string
Długość
100
Pole
obowiązkowe
Opis
tak
Wewnętrzny i unikalny
numer dostawy
Sprzedającego
Numer śledzenia
trackingId
przesyłki
string
100
tak
Numer śledzenia
przesyłki/kod przesyłki
(opcja), dostępny tylko
przy wysyłkach paczek
Numer
zamówienia
string
100
nie
Unikalny numer
zamówienia Pasażu
Handlowego
portal.ayn.pl
orderId
19 Anulowanie zamówienia
Proces anulowania zamówienia wykorzystywany jest zarówno do anulowania zamówienia
Sprzedającego, kiedy towar nie może zostać dostarczony, jak i na prośbę Klienta o
anulowanie zamówienia.
Sprzedający, który nie może dostarczyć jednego lub więcej produktów lub całego
zamówienia, musi zgłosić te produkty jako anulowanie zamówienia. Dzięki temu Klient nie
jest obciążany, a zamówienie lub części zamówienia zostają unieważnione.
Klient ma możliwość, aby po aktywacji zamówienia wyrazić prośbę o anulowanie
zamówienia. Prośba ta jest przekazywana do Sprzedającego pocztą elektroniczną. Jeżeli
Sprzedający jest w stanie przeprowadzić to anulowanie zamówienia, to uruchamia on ten
proces. Jeżeli anulowanie zamówienia przez Sprzedającego nie jest już możliwe, ponieważ
np. proces przesyłki już się rozpoczął, wtedy prośba Klienta o anulowanie zamówienia nie
może być spełniona i Klient musi w tym wypadku skorzystać z możliwości zwrotu, patrz
Rozdział 20.
19.2 Definiowanie
W celu anulowania zamówienia muszą zostać przekazane do All You Need poniższe dane.
Pola, które są bezwzględnie wymagane, mają w kolumnie "Pole obowiązkowe" "tak". Pola,
które nie są polami obowiązkowymi i nie są wysyłane, nie są ustawiane lub są wypełniane
wartością domyślną (patrz kolumna „Opis“). Tabela zawiera atrybuty, które korespondują z
opisem technicznym common.xsd i orders.xsd i każdorazowo krótki opis zawartości:
portal.ayn.pl
Anulowanie zamówienia
Nazwa
Atrybut
Typ
Długość
Pole
Opis
obowiązkowe
Numer
zamówienia
orderId
string
100
tak
Unikalny numer zamówienia „internetowy Pasaż handlowy“
Numer
dostawy/numer
anulowania
consignmentId
string
100
tak
Wewnętrzny i unikalny numer anulowania Sprzedającego
Anulowanie pozycji zamówienia
Długość
Pole
obowiązkowe
string
100
tak
Pasaż handlowy
meinPaketId
ID
string
100
nie
European article
ean
number
string
13
nie
Ilość
quantity
Integer
tak
Anulowana liczba sztuk produktu
Powód
anulowania
zamówienia
reason
string
100
tak
Powód anulowania zamówienia [„CustomerRequest“ lub ”DealerRequest”]
Uwaga
comment
string
4000
nie
Inne uwagi Sprzedającego
Nazwa
ID produktu
Sprzedającego
portal.ayn.pl
Atrybut
productID
Typ
Opis
20 Zwroty
Klient ma możliwość odesłania w określonym terminie zamówienia do Sprzedającego. Może
to dotyczyć jednego lub kilku artykułów.
Najpóźniej wpłynięcie do Sprzedającego przesyłki zwrotnej uruchamia procedurę zwrotu.
Klient może również wcześniej skontaktować się z All You Need lub ze Sprzedającym, nie
jest to jednak bezwzględnie wymagane.
Zwrot może mieć różne powody lub może zostać wywołany różnymi akcjami Klienta:

Klient odsyła Sprzedającemu towar bez zawiadomienia na własny koszt.

Klient odsyła towar z formularzem dołączonym przez Sprzedającego.

Klient dzwoni do Sprzedającego, Sprzedający przekazuje Klientowi drogą pocztową
lub elektroniczną formularz zwrotu, Klient wysyła towar do Sprzedającego.

Klient dzwoni do Działu Obsługi Klienta w All You Need a tam jest odsyłany do
Sprzedającego.
Jeżeli Sprzedający otrzyma z powrotem przesyłkę, musi poinformować o tym All You Need i
podać przy tym odpowiedni numer zamówienia i numer artykułu.
Jeżeli odesłane artykuły są uszkodzone lub używane, istnieje możliwość obniżenia kwoty do
zwrotu. W takim wypadku musi zostać podane uzasadnienie tego faktu.
Poniżej zdefiniowano powody przesyłki zwrotnej:
Nazwa
Opis
DAMAGED
Towar uszkodzony
USED
Towar używany
LOOK_IN_COMMENT
Dokładny opis musi zostać udostępniony w polu "comment".
Dopuszczalne jest maksymalnie 4000 znaków. Ta uwaga jest w razie
potrzeby przekazywana do Klienta.
Następnie Sprzedający może podać kwotę zwrotu kosztów przesyłki.
portal.ayn.pl
20.2 Definiowanie
Poniższe dane są wymagane do zgłoszenia zwrotu. Pola, które są bezwzględnie wymagane,
mają w kolumnie "Pole obowiązkowe" "tak". Pola, które nie są polami obowiązkowymi i nie
są wysyłane, nie są ustawiane. Tabela zawiera atrybuty, które korespondują z opisem
technicznym common.xsd i orders.xsd oraz każdorazowo krótki opis zawartości:
portal.ayn.pl
Nazwa
Atrybut
Typ
Długość
Pole
Opis
obowiązkowe
Numer
zamówienia
orderId
string
100
tak
Unikalny numer zamówienia MeinPaket
Numer zwrotu
returnId
string
100
tak
Unikalny numer zwrotu Sprzedającego
Zmniejszenie
kwoty
Reduction
double
nie
Kwota o którą zmniejszono / potrącenie
Powód
zmniejszenia
reductionReason string
nie
Powód zmniejszenia: „DAMAGED“ jeżeli artykuł uszkodzony, „USED“ jeżeli
artykuł posiada ślady używania, „LOOK_IN_COMMENT“ w razie innych
powodów, wpisać komentarz w polu.
Zwrot kosztów
przesyłki
reimbursedDeliv
eryCosts
double
nie
Zwrócone koszty przesyłki
Uwaga
Comment
string
4000
nie
Inne uwagi Sprzedającego
ID produktu
Sprzedającego
productID
string
100
tak
Pasaż handlowy
ID
meinPaketId
string
100
nie
European article
number
Ean
string
13
nie
Ilość
Quantity
long
tak
Zamówiona ilość produktu
portal.ayn.pl
100
21 Zapytanie o najniższą cenę
Webservice getBestPrice umożliwia zapytanie o najlepszą cenę produktu na podstawie
Twojego ID produktu "productId". Ustalane są przy tym i porównywane ceny całkowite
wszystkich oferentów (wraz z kosztami przesyłki). Najbardziej korzystna cena przekazywana
jest w odpowiedzi. Odpowiada ona najlepszemu oferentowi w pasażu internetowym.
Serwis dzieli się na poziom podstawowy i poziom premium. Wszyscy Sprzedający od
momentu rejestracji otrzymują poziom podstawowy. Poziom premium przyznawany jest
Sprzedającym zgodnie z określonymi kryteriami.
21.2 Definiowanie
Poniższe dane są wymagane do pobrania odpowiedzi. Pola, które są bezwzględnie
korespondują z opisem technicznym common.xsd, product.xsd i data.xsd oraz każdorazowo
portal.ayn.pl
Nazwa
ID produktu
Sprzedającego
Atrybut
productId
Typ Długość
string
100
Pole
obowiązkowe
tak
Opis
Odpowiedź
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
100
tak
Wewnętrzny i unikalny numer artykułu Sprzedającego.
Opis
ID produktu
productId
Sprzedającego
string
Cena
sprzedaży
price
double
tak
Cena jednostkowa zawierająca ustawowy podatek VAT z maksymalnie dwoma
miejscami po przecinku i kropką jako separatorem dziesiętnych.
Koszty
przesyłki
deliveryCost
double
tak
Należne koszty przesyłki produktu.
Własność
ownership
string
tak
Odpowiada, czy wysyłający żądanie Sprzedający oferuje najlepszą cenę.
portal.ayn.pl
100
22 Wywoływanie danych produktu
Webservice getProductData umożliwia wywołanie danych produktu, abyś mógł podjąć
decyzję, który produkt chciałbyś porównać. Zasadniczo wysyłane są z powrotem tylko dane
produktu, które udostępniane są przez All You Need lub które są niezbędne do porównania.
Ilustracji i opisów produktów innych Sprzedających nie można wywołać.
Zapytanie odbywa się za pomocą parametrów
-
MeinPaketId (wyszukiwanie dokładne)
-
EAN (wyszukiwanie dokładne)
-
Nazwa producenta (zawiera szukane słowo, niezależnie od pisowni wielką/małą
literą)
-
Pn producenta (zawiera szukane słowo, niezależnie od pisowni wielką/małą literą)
-
Nazwę produktu (zawiera szukane słowo, niezależnie od pisowni wielką/małą literą)
Wyszukiwanie następuje na podstawie połączenia UND ze wszystkimi przekazanymi
wartościami.
22.2 Definiowanie
portal.ayn.pl
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
Numer zapytania
entryId
string
100
tak
Numer zapytania "entryId" jest przydzielany przez
Sprzedającego, za jego pomocą jest identyfikowane
jednoznacznie każde wyszukiwanie.
Pasaż handlowy“ ID
meinPaketId
string
100
nie*
Unikalny numer artykułu Pasażu Handlowego
European article
number
ean
string
13
nie*
Producent
manufacturerName
string
100
nie*
Nazwa producenta*
Numer artykułu
producenta
manufacturerPN
string
100
nie*
Nazwa produktu
name
string
100
nie*
Nazwa produktu
* Wszystkie dane są opcjonalne, ale należy przekazać przynajmniej jedną
Odpowiedź
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
Numer zapytania
entryId
string
100
tak
Numer zapytania "entryId" jest przydzielany przez
Sprzedającego, za jego pomocą jest identyfikowane
jednoznacznie każde wyszukiwanie.
Pasaż handlowy ID
produktu
meinPaketId
string
100
nie
Unikalny numer artykułu Pasażu Handlowego
European article
number
ean
string
13
nie
Producent
manufacturerName
string
100
nie
Nazwa producenta*
Numer artykułu
manufacturerPN
string
100
nie
portal.ayn.pl
Nazwa
Atrybut
Typ
Długość
Pole
obowiązkowe
Opis
producenta
Kategoria w Pasażu
Handlowym
marketplaceCategorie
string
100
tak
Nazwa produktu
name
string
100
tak
Nazwa produktu
Opis MeinPaket
hasDescription
string
100
tak
Informuje, czy istnieje opis
Zdjęcie
image
image
512
nie
URL do zdjęcia produktu Sprzedającego. Maksymalna
wielkość 2 MB
Kod atrybutu
code
string
100
nie
Unikalny ID atrybutu. Ten kod identyfikuje dla każdego
Sprzedającego każdy atrybut
Nazwa atrybutu
name
string
100
nie*
Określone cechy produktu jak wymiary, kolory itp.
Wartość atrybutu
value
string
100
nie*
Wartość atrybutu
Jednostka atrybutu
unit
string
100
nie*
Konfiguracja wariantów variantConfiguration
string
100
nie*
Kod konfiguracji wariantów
Klasyfikacja
string
100
nie
Klasa, do której został przyporządkowany produkt
classification
* Przekazywane są tylko atrybuty tworzące warianty.
portal.ayn.pl
23 Zapytanie o dane Sprzedającego
Webservice getMerchantData umożliwia wywołanie podstawowych danych Sprzedającego,
w celu uzyskania podstawowych informacji o konkurencji. Zasadniczo wysyłane są tylko
dane sklepu dostępne na jego stronie internetowej. Dane sklepów, niedostępnych online nie
są wysyłane.
Zapytanie następuje na podstawie kodu Sprzedającego, który można pobrać przez
getBestPrice.
23.2 Definiowanie
portal.ayn.pl
Nazwa
Id Sprzedającego
Atrybut
merchantId
Typ
string
Długość
Pole
obowiązkowe
100
tak
Długość
Pole
obowiązkowe
Opis
merchantId jednoznacznie identyfikuje Sprzedającego.
Odpowiedź
Nazwa
Atrybut
Typ
Opis
ID Sprzedającego
merchantId
string
100
tak
merchantId jednoznacznie identyfikuje Sprzedającego.
Nazwa sklepu
shopName
string
100
tak
Nazwa zidentyfikowanego sklepu
Kategorie sklepu
useShopCategories
boolean
tak
true – sklep używa własnych kategorii sklepu; false – sklep nie używa
własnych kategorii sklepu.
Status sklepu
shopStatus
string
tak
Informuje, czy sklep jest online.
Ilość opinii
numberOfMerchantRating int
tak
Podaje ilość opinii o Sprzedającym
Średnia ocena
averageMerchantRating
double
tak
Podaje średnią ocenę dla danego Sprzedającego.
Koszty przesyłki
shippingCosts
-
-
-
Przesyłki darmowe
Dostawa
freeShipping
boolean
nie
Podaje, czy Sprzedający oferuje dla wszystkich produktów darmowe
przesyłki.
Zróżnicowanie
kosztów przesyłek
shippingCost
-
-
-
Poziom zróżnicowanych kosztów przesyłek
Waluta
currency
String
100
tak
Waluta
Cena minimalna
from
double
tak
Cena minimalna, od której obowiązuje dany poziom
Cena maksymalna
to
double
nie
Cena maksymalna, od której obowiązuje dany poziom. Cena
maksymalna nie jest podawana, kiedy poziom nie ma górnej granicy.
Koszty przesyłki
cost
double
tak
Koszty przesyłki dla każdego poziomu.
portal.ayn.pl
100
-
24 Kontakt
Czy masz pytania, na które nie było odpowiedzi w tym dokumencie lub sugestie albo
wskazówki dla nas?
DHL Express (Poland) Sp. z o.o.,
ul. Osmańska 2,
02-823 Warszawa
E-mail:
Telefon:
Online:
portal.ayn.pl
[email protected]
+48 42 6 345 310 (Pn - Pt od 9 do 17:30)
http://portal.ayn.pl
Załącznik A
Kody błędów po wysłaniu danych
Lista kodów błędów:
Kod błędu
Opis
SERVER_ERROR
Wewnętrzny błąd serwera.
NOT_AUTHORIZED
Nie masz wymaganych uprawnień do wysłanego żądania.
INVALID_DATA
Przesłane dane nie są prawidłowe.
INVALID_MODIFICATION
Oczekiwana zmiana jest niedopuszczalna. W razie pytań proszę skontaktować się z
zespołem Działu Wsparcia
NO_CATEGORIZATION
Produkt nie może zostać wyświetlony, ponieważ nie można przyporządkować kategorii.
PRODUCT_NOT_FOUND
Nie można przyporządkować produktu.
AVAILABILITY_NEGATIVE
Dostępność nie może być mniejsza od zera.
PRODUCT_NOT_SELLABLE
Produktu nie można oferować, musi być udostępniony opis (patrz Rozdział 7).
MARKETPLACE_CATEGORY_NOT_FOUND
Podana kategoria Pasażu Handlowego jest nieważna.
SHOP_CATEGORY_NOT_FOUND
Podana kategoria jest nieważna.
VARIANT_CONFIGURATION_NOT_FOUND
Ta konfiguracja wariantów nie istnieje, proszę wykorzystać istniejącą konfigurację
VARIANT_GROUP_NOT_FOUND
Ta grupa wariantów nie istnieje. Proszę utworzyć odpowiednią grupę lub zastosować
istniejącą.
portal.ayn.pl
Załącznik B
Tagi HTML
Lista wszystkich tagów HTML, które są dopuszczalne w opisie produktów:
Tag HTML
Opis

Podświetlenie
 
Złamanie wiersza


Akapit tekstowy
<ul></ul>
Lista wyliczenia
<ol></ol>
Lista numerowana
<li></li>
Lista
<hr/>
Linia podziału
Proszę uważać na właściwe formatowanie tekstów i sprawdzać sposób prezentacji
na „Pasażu Handlowym“ zanim sklep zostanie ustawiony on-line!
Obszerna dokumentacja odnośnie HTML patrz www.selfhtml.org lub wykorzystanie CDATA
patrz www.w3schools.com/xml/xml_cdata.asp
portal.ayn.pl
Załącznik C
Jeżeli ma być zastosowana platforma multiplikacyjna, możliwe są następujące wartości
Usługodawca cCommerce /
multiplierId
System eCommerce
Magento
MAGENTO
Gambio
GAMBIO
XT_Commerce
XT_COMMERCE
OS Commerce
OS_COMMERCE
portal.ayn.pl
Załącznik D
Nazwa pliku
Opis
Rozdział
mp_example_20_01_download_categories
mp_example_20_02_upload_offer
mp_example_20_03_upload_complete_product
mp_example_20_04_upload_categories
mp_example_20_05_download_offers
mp_example_20_06_download_variantConfigurations
mp_example_20_07_upload_variantGroup
mp_example_20_08_upload_product_variant
mp_example_20_09_delete_shopcategory
mp_example_20_10_delete_product
mp_example_30_01_download_orders
mp_example_30_03_upload_consignment
mp_example_30_04_upload_trackingnr
mp_example_30_05_upload_cancellation
mp_example_30_06_upload_return
mp_example_30_07_upload_creditMemo
mp_example_30_08_creditMemoRequest
mp_example_60_01_asynchronousStatusRequest
mp_example_50_01_bestPriceRequest
mp_example_50_02_productDataRequest
mp_example_50_03_merchantDataRequest
mp_example_50_04_qoutaRequest
Do pobrania kategorie Pasażu Handlowego i sklepu
Wysyłanie oferty produktu
Wysyłanie produktu z opisem produktu i oferty produktu
Wysyłanie kategorii sklepu
Oferty produktów do pobrania
Dostępne konfiguracje wariantów do pobrania
Wysyłanie grupy wariantów
Wysyłanie wariantu produktu
Usuwanie kategorii sklepu
Usuwanie produktu
Istniejące zamówienia do pobrania
Wysyłanie zgłoszenia przesyłki
Wysyłanie numeru śledzenia przesyłki
Zgłoszenie anulowania do pobrania
Zwroty do pobrania
Tworzenie noty uznaniowej
Zapytanie o wydane noty uznaniowe
Zapytanie o status danego żądania
Uruchomienie zapytania o najlepszą cenę
Uruchomienie zapytania o dane produktu
Uruchomienie zapytania o dane Sprzedającego
Zapytanie o dostępne wskaźniki
Rozdział 10
Rozdział 4
Rozdział 6
Rozdział 5
Rozdział 11
Rozdział 7
Rozdział 7
Rozdział 7
Rozdział 12
Rozdział 12
Rozdział 14
Rozdział 15
Rozdział 16
Rozdział 17
Rozdział 18
Rozdział 24
Rozdział 24
Rozdział 3
Rozdział 19
Rozdział 20
Rozdział 21
Rozdział 13
Poniżej znajdziesz link do strefy do pobrania, gdzie możesz pobrać przykładowe pliki.
portal.ayn.pl
Załącznik E
Historia zmian
Wersja
v. 1.0
v. 2.0
v. 3.0
v. 4.0
v. 4.1
portal.ayn.pl
Zmiany
Opracowanie dla Polski
new Layout
Customizing
Change of the XML - Header
Small corrections during some wordings

Dokumentacja techniczna API Sprzedającego

Transkrypt

Podobne dokumenty

wzór umowy

umowa kupna – sprzedaży urządzenia / urządzeń medycznych

Zasady i warunki sprzedaży - PIT

ogłoszeniu.

Wzór umowy kupna sprzedaży

Warunki sprzedaży i dostawy

1.Usługodawcą w sklepie internetowym o adresie elektronicznym

umowa kupna - sprzedaży automatu do lodów basat ips