Jak na import aukcí přes Aukro WebAPI? (díl 2.)
V minulém díle jsem se snažil poskytnout základní informace o tom, jak postupovat, když chci umožnit svým webovým stránkám komunikaci s aukčním systémem Aukro.cz. Vše bylo vysvětleno na příkladech v programovacím jazyce PHP. V tomto pokračování Vám předvedu, jak naimportovat konkrétní aukce pomocí rozhraní Aukro WebAPI.
Jak vytvořit svůj testovací účet?
Pokud plánujeme importovat nové aukce na portál Aukro.cz, je nutné počítat s tím, že za každý úspěšný import zaplatí vlastník účtu drobný poplatek. Výše poplatku závisí na kategorii produktu, který hodláme nabízet. Sazebník poplatků a provizí nalezneme zde.
Pro potřeby vývoje je vždy vhodné mít zřízený svůj testovací účet. Můžeme tak hodit za hlavu starosti s placením poplatků a mazáním testovacích aukcí, které vzniknou během dokončování prací. Aukro nám to umožňuje zřízením nového účtu na webu http://www.testwebapi.pl/. Jak už bylo zmíněno v předchozím díle, potřebujeme pro přihlášení ke službě Aukro WebAPI následující údaje:
$params = array("user-login" => 'login_k_testovacimu_uctu_aukra',
"user-password" => 'heslo_k_testovacimu_uctu_aukra',
"country-code" => 228,
"webapi-key" => '123456789', // klíč k WebAPI
"local-version" => (int) $ver_key); // získaný klíč z doQuerySysStatus
$session = $soap->__soapCall('doLogin', $params);
V případě testovacího účtu získáme potřebné údaje takto:
- login_k_testovacimu_uctu_aukra - přihlašovací jméno získané registrací na testwebapi.pl
- heslo_k_testovacimu_uctu_aukra - heslo získané registrací na testwebapi.pl
- country_code - u testovacího účtu je pouze jeden stát s ID 228 (Neverland)
- webapi-key - klíč pro testovací přístup ke službě Aukro WebAPI (Zde jsem bohužel nezjistil, podle čeho získám svůj klíč pro testovací účet. Použil jsem stejný klíč, jako u ostrého účtu a vše fungovalo.)
Adresu pro přístup ke službám testovacího účtu jsem použil http://webapi.allegro.pl/uploader.php?wsdl.
Získání seznamu uložených aukcí
Pokud se rozhodneme získat seznam aukcí, které máme naimportovány pod svým účtem na portále Aukro.cz, je nutné použít metodu doMyAccount2. Vše znázorňuje následující ukázka:
$type = 'watch_cl';
$params = array('session-handle' => $session,
'account-type' => $type,
'offset' => 0,
'items-array' => '');
$output = $this->soap->__soapCall('doMyAccount2', $params);
Proměnná $session nese hodnotu, kterou získáme po použití metody doLogin nebo doLoginEnc - popis použití byl zmíněn v předchozím díle. Pak už zbývá jen určit, jaký typ seznamu chceme získat (proměnná $type). Možné typy jsou:
- bid - pro výpis nabízených položek
- sell - pro výpis prodávaných položek
- won - pro výpis vyhraných aukcí
- not_won - pro výpis prohraných aukcí
- sold - pro výpis prodaných položek
- not_sold - pro výpis neprodaných položek
- watch - pro získání seznamu sledovaných aukcí
- watch_cl - pro získání seznamu sledovaných aukcí, které jsou dokončeny
- future - pro výpis budoucích aukcí
Založení nové aukce
Důvod, proč jsem se rozhodl napsat tento článek na blog, byl právě import aukcí na portál Aukro.cz. Před rozhraní WebAPI to lze udělat pomocí metody doNewAuctionExt.
# inicializace proměnných
$empty = new stdClass();
$empty->{'fvalue-string'} = '';
$empty->{'fvalue-int'} = 0;
$empty->{'fvalue-float'} = 0;
$empty->{'fvalue-image'} = ' ';
$empty->{'fvalue-datetime'} = 0;
$empty->{'fvalue-boolean'} = false;
$form = array();
# název importovaného produktu
$field = clone $empty;
$field->{'fid'} = 1;
$field->{'fvalue-string'} = 'Snowboardové prkno';
$form[] = $field;
# kategorie, do které chceme vložit náš produkt
$field = clone $empty;
$field->{'fid'} = 2;
$field->{'fvalue-int'} = 63350; # ID 63350 je pro kategorii Snowboardy
$form[] = $field;
# datum, kdy se má zveřejnit naše aukce
$field = clone $empty;
$field->{'fid'} = 3;
$field->{'fvalue-datetime'} = time(); # zveřejníme rovnou
$form[] = $field;
# délka trvání aukce - 2 pro 7dní, 3 pro 10dní, 4 pro 14dní, 5 pro 30dní
$field = clone $empty;
$field->{'fid'} = 4;
$field->{'fvalue-int'} = 3; # 10 dní
$form[] = $field;
# počet položek daného produktu v nové aukci
$field = clone $empty;
$field->{'fid'} = 5;
$field->{'fvalue-int'} = 1;
$form[] = $field;
# cena zboží, když bude aukce typu Kup teď!
$field = clone $empty;
$field->{'fid'} = 8;
$field->{'fvalue-float'} = 109.60;
$form[] = $field;
# ID země pro novou aukci
$field = clone $empty;
$field->{'fid'} = 9;
$field->{'fvalue-int'} = 56; # ID 56 pro Českou republiku
$form[] = $field;
# ID kraje pro novou aukci
$field = clone $empty;
$field->{'fid'} = 10;
$field->{'fvalue-int'} = 30; # ID 32 pro Vysočinu, ID 30 pro jihomoravský kraj
$form[] = $field;
# město
$field = clone $empty;
$field->{'fid'} = 11;
$field->{'fvalue-string'} = 'Brno';
$form[] = $field;
# Kdo hradí náklady na dopravu
$field = clone $empty;
$field->{'fid'} = 12;
$field->{'fvalue-int'} = 1; # ID 1 = kupující
$form[] = $field;
# Forma platby
$field = clone $empty;
$field->{'fid'} = 14;
$field->{'fvalue-int'} = 1; # ID 1 = Zaplaťte předem (banka)
$form[] = $field;
# Obrázek produktu
if (!empty($input_file)) {
$field = clone $empty;
$field->{'fid'} = 16;
# otevřeme soubor obrázku
$ifp = fopen( $input_file, "rb" );
$image_data = fread( $ifp, filesize( $input_file ) );
fclose( $ifp );
$field->{'fvalue-image'} = $image_data;
$form[] = $field;
}
# popis produktu
$field = clone $empty;
$field->{'fid'} = 24;
$field->{'fvalue-string'} = $description;
$form[] = $field;
# aukce bez přihazováni - pouze Kup teď!
# 0 => aukce (s PayPal nebo Kup Teď! s omezeným počtem dnů)
# 1 => aukce Kup Teď! s aktivnim Aukro Shopem
$field = clone $empty;
$field->{'fid'} = 29;
$field->{'fvalue-int'} = 0;
$form[] = $field;
# PSČ místa, ve kterém prodáváme zboží
$field = clone $empty;
$field->{'fid'} = 32;
$field->{'fvalue-string'} = '621 00' # musi obsahovat mezeru
$form[] = $field;
# přidání bezplatné přepravy - osobní převzetí
$field = clone $empty;
$field->{'fid'} = 35;
$field->{'fvalue-int'} = 1;
$form[] = $field;
# cena za poštovné - dobírka
$field = clone $empty;
$field->{'fid'} = 43;
$field->{'fvalue-float'} = 80.0
$form[] = $field;
# cena za poštovné - kurýrní služba, dobírka
$field = clone $empty;
$field->{'fid'} = 45;
$field->{'fvalue-float'} = 160.0;
$form[] = $field;
# další dodatečné atributy, které se odvíjejí od zvolené kategorie
$field = clone $empty;
$field->{'fid'} = 2027; # dodatečný atribut Stav zboží, který je nutný pro kategorii Snowboardy
$field->{'fvalue-'.$type} = 1; # ID 1 pro nové zboží
$form[] = $field;
$local = uniqid();
$params = array('session-handle' => $session, 'fields' => $form, 'private' => 0, 'local-id' => $local);
$output = $this->soap->__soapCall('doNewAuctionExt', $params);
Uvedená ukázka znázorňuje postup, jak importovat novou aukci typu Kup teď!. Vkládání běžné aukce se tento článek nezabývá, ale implementace bude hodně podobná - bude se lišit jen množství potřebných údajů. Základní atributy jsou u každého importu stejné (název, popis, kategorie, město, země, ...). Dodatečné atributy se pak odvíjejí od zvolené kategorie (v našem příkladu byla zvolená kategorie Snowboardy a jako dodatečný atribut nutný pro úspěšné dokončení importu byl Stav zboží). V závěru článku si pak ukážeme, jak zjistíme dodatečné atributy, pokud známe ID kategorie.
Když jsem se začal před měsícem trápit s implementací, tak mě zarazilo, že nikde v dokumentaci WebAPI není dostupný seznam možných atributů, které lze použít při importu aukce. Jediný zdroj, ze kterého bylo možné čerpat, byl jakýsi polský internetový blog. Abych Vám podobné hledání usnadnil, rozhodl jsem se vytvořit následující seznam:
| Fid | Field name |
|---|---|
| 1 | Název produktu |
| 2 | ID kategorie (int) |
| 3 | Datum zahájení aukce |
| 4 | Čas aukce (0 | 1 | 2 | 3 | 4 | 5 => 3 | 5 | 7 | 10 | 14 | 30 dnů) |
| 5 | Počet položek daného produktu (int) |
| 6 | Vyvolávací cena (float) |
| 7 | Minimální cena (float) |
| 8 | Cena "Kup teď" (float) |
| 9 | ID země (int) |
| 10 | ID státu (int) |
| 11 | Město (String) |
| 12 | Forma dopravy (0 | 1 => Prodávající je povinen nést náklady na dopravu | Kupující hradí náklady na dopravu) |
| 13 | Způsob dopravy (1 2 => Souhlasím se zasílání zboží i do zahraničí | Podrobnosti v popisu) (možnost sčítání volby) |
| 14 | Forma platby (1 | 2 | 4 | 8 => Zaplaťte předem (banka) | - | Podrobnosti v popisu | faktura s DPH) (možnost sčítání volby) |
| 15 | Další možnosti (1 | 2 | 4 | 8 | 16 | 32 => tučný titulek | zvýraznění | přednostní výpis | strana kategorie | hlavní strana | vodoznak) (možnost sčítání volby) |
| 16 | Foto 1 |
| 17 | Foto 2 |
| 18 | Foto 3 |
| 19 | Foto 4 |
| 20 | Foto 5 |
| 21 | Foto 6 |
| 22 | Foto 7 |
| 23 | Foto 8 |
| 24 | Popis produktu |
| 27 | Další informace o zásilce a platbě (max. 500 znaků) |
| 28 | Specifikace množství položek (0 | 1 | 2 => Kusy | Sady | Páry) |
| 29 | Formát prodeje na Aukru (0 | 1 => Aukce (s PayPal nebo Kup teď!) | Běžná aukce) (výchozí 0) |
| 30 | Automatická obnova aukce (0 | 1 | 2 => Bez pokračování | Pokračovat s pevným seznamem produktů | Pokračovat pouze s neprodanými produkty) |
| 31 | Kategorie v obchodě |
| 32 | PSČ |
| 33 | První bankovní účet |
| 34 | Druhý bankovní účet |
| 35 | Volba bezplatné přepravy (1 | 2 => Osobní vyzvednutí | Elektronickou poštou (e-mail)) (možnost sčítání volby) |
| 36 | Možnosti přepravy: Obyčejný balík (cena při prvním nákupu) (float) |
| 37 | Možnosti přepravy: Obchodní balík (cena při prvním nákupu) (float) |
| 38 | Možnosti přepravy: cenný balík (cena při prvním nákupu) (float) |
| 39 | Možnosti přepravy: EMS (cena při prvním nákupu) (float) |
| 40 | Možnosti přepravy: Obyčejné psaní (cena při prvním nákupu) (float) |
| 41 | Možnosti přepravy: Cenné psaní (cena při prvním nákupu) (float) |
| 42 | Možnosti přepravy: Doporučená zásilka (cena při prvním nákupu) (float) |
| 43 | Možnosti přepravy: dobírka (cena při prvním nákupu) (float) |
| 44 | Možnosti přepravy: Kurýrní služba (cena při prvním nákupu) (float) |
| 45 | Možnosti přepravy: Kurýrní služba - dobírka (cena při prvním nákupu) (float) |
| 46 | Možnosti přepravy: Zásilka do zahraničí (cena při prvním nákupu) (float) |
| 136 | Možnosti přepravy: Obyčejný balík (cena při dalším nákupu) (float) |
| 137 | Možnosti přepravy: Obchodní balík (cena při dalším nákupu) (float) |
| 138 | Možnosti přepravy: cenný balík (cena při dalším nákupu) (float) |
| 139 | Možnosti přepravy: EMS (cena při dalším nákupu) (float) |
| 140 | Možnosti přepravy: Obyčejné psaní (cena při dalším nákupu) (float) |
| 141 | Možnosti přepravy: Cenné psaní (cena při dalším nákupu) (float) |
| 142 | Možnosti přepravy: Doporučená zásilka (cena při dalším nákupu) (float) |
| 143 | Možnosti přepravy: dobírka (cena při dalším nákupu) (float) |
| 144 | Možnosti přepravy: Kurýrní služba (cena při dalším nákupu) (float) |
| 145 | Možnosti přepravy: Kurýrní služba - dobírka (cena při dalším nákupu) (float) |
| 146 | Možnosti přepravy: Zásilka do zahraničí (cena při dalším nákupu) (float) |
| 236 | Možnosti přepravy: Obyčejný balík (množství v balení) (int) |
| 237 | Možnosti přepravy: Obchodní balík (množství v balení) (int) |
| 238 | Možnosti přepravy: cenný balík (množství v balení) (int) |
| 239 | Možnosti přepravy: EMS (množství v balení) (int) |
| 240 | Možnosti přepravy: Obyčejné psaní (množství v balení) (int) |
| 241 | Možnosti přepravy: Cenné psaní (množství v balení) (int) |
| 242 | Možnosti přepravy: Doporučená zásilka (množství v balení) (int) |
| 243 | Možnosti přepravy: dobírka (množství v balení) (int) |
| 244 | Možnosti přepravy: Kurýrní služba (množství v balení) (int) |
| 245 | Možnosti přepravy: Kurýrní služba - dobírka (množství v balení) (int) |
| 246 | Možnosti přepravy: Zásilka do zahraničí (množství v balení) (int) |
Seznam obsahuje jen základní atributy. Doplňující atributy lze zjistit pomocí speciálních metod, které popíšu dále v textu.
Pokud se podaří aukci úspěšně naimportovat, dostaneme jako výsledek provedené operace unikátní číslo v rámci portálu Aukro.cz. Toto číslo poslouží jako identifikátor uložené aukce. Bližší info nalezeme v dokumentaci.
Využití Aukro Shopu
Při dokončování prací jsem se ještě setkal s jednou komplikací. Chtěl jsem vystavit předmět s cenou Kup teď! na dobu dlouhou 30 dní a nedařilo se mně import aukce dokončit. Po komunikaci s technickou podporou Aukro.cz jsem zjistil, že to lze udělat pouze se založeným Aukro Shopem. Díky němu je možné vystavit předměty s cenou Kup teď! na dobu 30 dní za nižší poplatky, než nabízí klasické aukce. Bez jeho aktivace lze předměty vystavovat na dobu dlouhou maximálně 10 dnů.
A co to vlastně Aukro Shop je? Jedná se o zpoplatněnou službu, která je určena pro prodejce, kteří chtějí mít vlastní webové stránky s vlastním obsahem prodávaného zboží.
Svůj Aukro Shop si můžete založit, pokud už jste prodejcem na Aukru a máte hodnocení minimálně 10 bodů v systému komentářů.
Registraci Aukro Shopu provedete po přihlášení na svůj účet v Moje Aukro > Můj prodej > Aukro Shopy. Postup při vkládání údajů je následující:
- Vložte název Shopu a jeho popis.
- Nahrajte grafické logo svého Shopu.
- Zvolte barvy a způsob, jakým se budou předměty zobrazovat.
- Vytvořte záhlaví a zvolte způsob vyhledávání.
Při vytváření jména je nutné myslet na ochranné známky jiných společností nebo třetích stran tak, aby nebyly porušeny žádné právní předpisy. Pro více informací navštivte stránku Aukro Shopy z Hlavní strany administrace svého účtu nebo přejděte na tento odkaz http://shopy.aukro.cz/.
Další užitečné metody
Účelem tohoto článku není popsání všech metod, které nabízí Aukro WebAPI. Nicméně bych rád zmínil ještě některé metody, které jsem využil při svých pracích na importu.
Detail konkrétní aukce
Detail konkrétní aukce zjistíme pomocí metody doShowItemInfoExt. Jediné co potřebujeme je číslo - identifikátor aukce, který získáme jako návratovou hodnotu při importování.
$params = array('session-handle' => $session, 'item-id' => $auction_id);
$output = $this->soap->__soapCall('doShowItemInfoExt', $params);
Aktuální stav účtu
Aktuální stav Vašeho Aukro účtu lze získat snadno pomocí metody doMyBilling. Jako odpověď dostaneme informaci množství peněz.
$params = array('session-handle' => $session);
$output = $this->soap->__soapCall('doMyBilling', $params);
Dostupné kategorie pro nabízené zboží
Při vkládání nové aukce je nutné zadat i kategorii, do které patří vybrané zboží. Seznam dostupných kategorií závisí na zvolené zemi. Informace získáme pomocí metody doGetCatsData.
$params = array("country-id" => 56, // id země (56 pro ČR)
"local-version" => 0,
"webapi-key" => '123456789'); // tvůj WebAPI klíč
$output = $this->soap->__soapCall('doGetCatsData', $params);
Informace o dodatečných atributech pro novou aukci
Jak jsem již zmínil v předchozím textu, mají některé aukce řadu dodatečných atributů. Seznam dodatečných atributů pro nové zboží závisí především na zvolené kategorii, do které vkládáme produkt.
$params = array('country-id' => 56, // id země (56 pro ČR)
'webapi-key' => '123456789', // tvůj WebAPI klíč
'local-version' => 0,
'cat-id' => $cat_id // ID kategorie, do které vkládáme nový produkt
);
$output = $this->soap->__soapCall('doGetSellFormAttribs', $params);
