Dokumentacja techniczna eksportu XML v1.01

Dokumentacja techniczna eksportu XML
v1.01
Spis treści
1.
Informacje podstawowe.......................................................................................................... 3
1.1.
Zasady ogólne ...................................................................................................................... 3
1.2.
Dane dostępowe serwera FTP ............................................................................................. 3
1.3.
Czas oczekiwania na przetworzenie .................................................................................... 3
2.
Eksport danych ........................................................................................................................ 4
2.1.
Paczka eksportowa .............................................................................................................. 4
2.2.
Rodzaje eksportów .............................................................................................................. 4
2.3.
Sposoby przesyłania zdjęć ................................................................................................... 4
2.4.
Usuwanie ofert .................................................................................................................... 5
2.5.
Numer oferty ....................................................................................................................... 5
3.
Plik XML ................................................................................................................................... 6
3.1.
Struktura .............................................................................................................................. 6
3.2.
Przykładowy plik XML .......................................................................................................... 7
© Trader.com (Polska)
2
1. Informacje podstawowe
1.1. Zasady ogólne
Plik XML dla zachowania polskich znaków diakrytycznych musi być zakodowany w standardzie UTF-8.
Schemat XSD pliku XML z danymi ogłoszeń, zawierający objaśnienia pól w języku polskim i angielskim
dostępny jest pod adresem:
http://www.autotrader.pl/Documents/Autotrader.xsd
Przed przetworzeniem paczki eksportowej sprawdzana jest poprawność składniowa oraz zgodność
pliku XML ze schematem XSD. W przypadku wykrycia niezgodności paczka jest pomijana.
Do sprawdzenia zgodności wygenerowanego pliku XML ze schematem XSD można posłużyć się
jednym z wielu darmowych narzędzi dostępnych online, np.
http://www.freeformatter.com/xml-validator-xsd.html
1.2. Dane dostępowe serwera FTP
Każdy użytkownik wykonuje eksporty na swoje indywidualne konto FTP. Na dane dostępowe składają
się unikalne
 Login
 Hasło
Dane dostępowe do konta FTP nadaje Biuro obsługi klientów, po otrzymaniu potwierdzenia o
gotowości wykonywania eksportów.
1.3. Czas oczekiwania na przetworzenie
Paczki eksportowe przetwarzane codziennie są w godzinach 00:00 – 22:00.
Czas oczekiwania na przetworzenie zależy od aktualnego obciążenia systemu i średnio wynosi od 5 do
10 minut, może się jednak wydłużyć w okresie dużego nasilenia eksportów od klientów.
© Trader.com (Polska)
3
2. Eksport danych
2.1. Paczka eksportowa
Paczka z danymi ofert musi mieć postać archiwum ZIP zawierającego


Plik XML z danymi ofert w formacie zgodnym ze schematem Autotrader.xsd
Pliki zdjęć w formacie JPG (jeżeli zdjęcia nie są podane jako adresy URL)
W danym momencie na koncie klienta może się znajdować kilka paczek oczekujących na
przetworzenie, dlatego pliki muszą posiadać unikalne nazwy zawierające datę i godzinę
wygenerowania, np.:
trader-20150618-092755-calosc.zip
Po poprawnym zakończeniu transferu na serwer FTP, należy zmienić nazwę pliku dodając na
początku ciąg znaków „ok-”:
ok-trader-20150618-092755-calosc.zip
Tylko pliki z nazwą zaczynającą się od „ok-” będą przetwarzane.
Przesyłanie pliku od razu z nazwą rozpoczynającą się od ciągu znaków „ok-” nie jest zalecane, gdyż w
przypadku nieoczekiwanego przerwania transferu, spowoduje to opóźnienie w przetwarzaniu
kolejnych paczek eksportowych.
2.2. Rodzaje eksportów
Dopuszczalne są 2 rodzaje eksportu


przyrostowy – zawierający informacje o ogłoszeniach dodanych i/lub zmienionych i/lub
usuniętych od momentu wykonania poprzedniego eksportu
całościowy – zawierający informacje o wszystkich ogłoszeniach jakie powinny znajdować się
na koncie klienta
Uwaga!
Aplikacja musi umożliwiać wykonanie eksportu całościowego.
2.3. Sposoby przesyłania zdjęć
Dopuszczalne są 2 sposoby przesyłania zdjęć


Jako pliki JPG – jeżeli ogłoszenie w pliku XML posiada zdefiniowane zdjęcia, muszą być one
przesłane w paczce eksportowej
Jako adresy URL do zasobów zewnętrznych
© Trader.com (Polska)
4
2.4. Usuwanie ofert
Informację o ofertach do usunięcia można przesłać na 3 sposoby



Wykonując eksport całościowy, wszystkie oferty na koncie klienta które nie zostały w nim
zawarte zostaną usunięte
Wykonując eksport przyrostowy zawierający listę numerów ofert do usunięcia
Wykonując eksport przyrostowy zawierający listę numerów ofert do pozostawiania,
wszystkie ofert na koncie klienta spoza tej listy zostaną usunięte
2.5. Numer oferty
Numer oferty musi być unikalny w ramach wszystkich ofert danego klienta. Na jego podstawie
wyszukiwane są oferty do zaktualizowania lub usunięcia.
© Trader.com (Polska)
5
3. Plik XML
3.1. Struktura
Podstawowa struktura pliku XML
<?xml version="1.0" encoding="utf-8"?>
<Autotrader xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ExportSettings>
(...)
Znaczniki z informacjami o eksporcie
(…)
</ExportSettings>
<Adverts>
<Advert>
(...)
Znaczniki z danymi ogłoszenia
(…)
<Pictures>
(...)
Znaczniki definiujące zdjęcia do ogłoszenia
(…)
</Pictures>
</Advert>
</Adverts>
<AdvertManagment>
(...)
Znaczniki z informacjami o ogłoszeniach do usunięcia
(…)
</AdvertManagment>
</Autotrader>
Pola zawierające wartości tekstowe, a w szczególności opis ogłoszenia musi być opatrzony
znacznikami <![CDATA[]]>.
Należy zwrócić uwagę na kolejność tagów XML.
Schemacie XSD definiuje pola wymagane.
Adresy z listami dostępnych wartości dla pół słownikowych podane są w schemacie XSD.
W ramach sekcji AdvertManagment niedopuszczalne jest podanie zarówno listy AdvertsToKeep
jak i AdvertsToDelete. Należy podać tylko jedną z tych list. W przypadku eksportu całościowego
informacje podane w tej sekcji są ignorowane.
© Trader.com (Polska)
6
3.2. Przykładowy plik XML
<?xml version="1.0" encoding="utf-8"?>
<Autotrader xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ExportSettings>
<ExportType>Incremental</ExportType>
<SchemaVersion>1.0.0</SchemaVersion>
<ClientId>111</ClientId>
</ExportSettings>
<Adverts>
<Advert>
<AdvertId>123</AdvertId>
<AdvertType>ForSale</AdvertType>
<Title>Fiat Palio 1.2 2001 r.</Title>
<Description><![CDATA[WITAM!Palio zadbany i bez uszkodzeń lakieru i
otarć nadwozia używany prywatnie przez 1-właściciela od nowości garażowany w domu
prywatnym.
Do samochodu dołączone są wszystkie dokumenty łącznia z książką
serwisową oraz fakturami z poszczególnych przeglądów w stacji serwisowej Fiata.
Dodatkowo posiada dzielone siedzenia tylne,regulacje pionową
kierownicy,welurowe tapicerki,komputer,atermiczne szyby,odcięcie zapłonu.
Istnieje możliwość zamiany i zakupu na raty.
SAMOCHOD OBJETY JEST KOMISOWA GWARANCJA NA PRZEBIEG,NA BEZWYPADKOWOSC
I NA LEGALNOSC POCHODZENIA.
Zapraszamy codziennie od 8.00-20.00]]></Description>
<Price>12500</Price>
<PriceCurrency>PLN</PriceCurrency>
<PriceIsNetto>0</PriceIsNetto>
<PriceIsNegotiable>0</PriceIsNegotiable>
<IsNew>0</IsNew>
<IsDamaged>0</IsDamaged>
<HasWarranty>0</HasWarranty>
<MainCategoryId>131</MainCategoryId>
<CategoryId>29454</CategoryId>
<Make>Fiat</Make>
<Model>Palio</Model>
<Version>Weekend</Version>
<ProductionYear>2001</ProductionYear>
<FirstRegistration>09-10-2001</FirstRegistration>
<City>Skawina</City>
<Voivodeship>Małopolskie</Voivodeship>
<Country>Polska</Country>
<OriginCountry>Polska</OriginCountry>
<History>
<HistoryElement>82</HistoryElement>
<HistoryElement>83</HistoryElement>
<HistoryElement>85</HistoryElement>
</History>
<Equipment>
<EquipmentElement>1060</EquipmentElement>
<EquipmentElement>73</EquipmentElement>
</Equipment>
<EnginePower>75</EnginePower>
<EngineCapacity>1200</EngineCapacity>
<Mileage>65000</Mileage>
<SeatCount>5</SeatCount>
<Vin>asdfg12a456ssiuyt</Vin>
<Color>Czerwony</Color>
© Trader.com (Polska)
7
<BodyTypeId>849</BodyTypeId>
<FuelTypeId>44</FuelTypeId>
<DriveId>200164</DriveId>
<TransmissionId>200011</TransmissionId>
<DoorCountId>200111</DoorCountId>
<PhoneNumber>+48 500 600 700</PhoneNumber>
<AdditionalContact>[email protected]</AdditionalContact>
<Pictures>
<SourceType>HttpUrl</SourceType>
<PicturePath>http://www.autotrader.pl/Images3/logo-autotraderpl.png</PicturePath>
</Pictures>
</Advert>
</Adverts>
<AdvertManagment>
<AdvertsToKeep>
<AdvertId>123</AdvertId>
<AdvertId>124</AdvertId>
</AdvertsToKeep>
</AdvertManagment>
</Autotrader>
© Trader.com (Polska)
8