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>a@b.pl</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