Jak na import aukcí přes Aukro WebAPI? (díl 1.)

Martin Pešout   11. 12. 2010


Pokud spravujete větší eshop, čas od času se jejich majitel rozhodne o provázání s aukčním systémem Aukro.cz. I když existuje bohaté fórum, kde se dají problémy s implementací diskutovat, nikde jsem nenalezl ucelený návod. Rozhodl jsem se proto, že se podělím o zkušenosti s komunikací prostřednictvím Aukro WebAPI a programováním vhodného nástroje. Veškeré moje příklady jsou psány v programovacím jazyce PHP. Nicméně jsou natolik jednoduché, že snadno lze okoukat jejich implementace do jiných jazyků.

Co je nutné zjistit na začátku vývoje?

Než bude zahájeno samotné programování, je nutné zajistit následující:

  1. Zaregistrovat se na webu aukro.cz
  2. Získat klíč pro přístup ke službě Aukro WebAPI

Co je Aukro WebAPI?

Rozhraní WebAPI je komunikačním rozhraním, které využívá protokol HTTP a jazyk XML. Slouží ke komunikaci mezi Uživatelem a systémem Aukro. WebAPI je souborem služeb, které vývojářům umožňují vytvářet programy a nástroje zajišťující Uživatelům přístup k systému Aukro.

Výše a forma poplatku za používání rozhraní WebAPI závisí na zvoleném balíčku.

  • Základní balíček je zcela zdarma.
  • Profi balíček je hrazen formou předplatného na 6 měsíců.

Detailnější popis a ceník naleznete zde na webu aukro.cz. Samotný klíč k této službě můžete získat, pokud jste programátorem a registrovaným uživatelem Aukra. Stačí vyplnit speciální kontaktní formulář. O získání přístupu budete informováni emailovou zprávou.

Dokumentace rozhraní

Při komunikaci se systémem Aukro můžete využít celou řadu funkcí. V tomto článku se nebudu zabývat popisem každé z nich. Uvedu jen ty základní. Případným zájemcům uvádím odkaz do dokumentace, kde je možné najít další informace.

Způsob komunikace

„Rozhraní WebAPI“ je sadou definic WSDL protokolu SOAP, které popisují způsob komunikace interních aplikací s prostředky aukční služby Aukro.cz. V programovacím jazyce PHP jsem použil pro komunikaci nástroj SoapClient. Použití demonstruje následující ukázka:

$soap = new SoapClient('http://webapi.aukro.cz/uploader.php?wsdl');
$soap->soap_defencoding = 'UTF-8';
$soap->decode_utf8 = false;

$params = array('sysvar' => 1, // na kterou funkci se ptáme
'country-id' => 56, // id země (56 pro ČR)
'webapi-key' => '123456789'); // tvůj WebAPI klíč

try {
$output = $soap->__soapCall('doQuerySysStatus', $params);

if (is_null($output) || !isset($output['ver-key'])) {
throw new Exception('Unconsitent ver-key for AUKRO WebAPI access.');
}
} catch (Exception $e) {
echo 'Caught exception: ', $e->getMessage(), "n";
};

Tato část kódu se připojí WebAPI portálu Aukro.cz a zjistí klíč pro přihlášení, který následně používáme i u ostatních metod. K tomuto účelu nám posloužila metoda doQuerySysStatus. Dostaneme výsledek podobný tomuto:

array(2)
{

['info'] => strint(5) '1.2.3' // verze komponenty
['ver-key'] => int(22233344) // klíč pro přihlášení a užití u jiných metod

}

Pokud máme získané tyto údaje, tak nám zbývá provést přihlášení do systému Aukra. K tomuto je nutné použít metodu doLogin nebo doLoginEnc (pro zabezpečené přihlášení).

if(function_exists('hash')){
// hash používaný v PHP od verze 5.1.3
$password = hash('sha256', 'tajne_heslo_k_aukru', true);
}
else {
// ve starších verzích používáme mhash
$password = mhash(MHASH_SHA256, 'tajne_heslo_k_aukru');
}

// base64 pro zakódovaný binární přenos hesla
$password = base64_encode($password);

$params = array("user-login" => 'login_k_memu_uctu_aukra',
"user-password" => $password,
"country-code" => 56,
"webapi-key" => '123456789', // klíč k WebAPI
"local-version" => (int) $ver_key); // získaný klíč z doQuerySysStatus

try {
$session = $soap->__soapCall('doLoginEnc', $params);
$session = $session['session-handle-part'];
} catch (Exception $e) {
echo 'Caught exception: ', $e->getMessage(), "n";
}

Získáme tak session, která může být použita ve zbývajících metodách WebAPI. Životnost session je 3 hodiny a naráz jich lze vytvořit maximálně 5.

Co můžete čekat v dalším pokračování?

Když jsem začal psát tento článek, tak jsem zprvu nepočítal s tím, že těch informací bude takové množství. Postupně jak rozsah začal narůstat jsem se rozhodl, že ho rozdělím do několika pokračování, kde detailněji popíšu osobní zkušenosti komunikace s portálem Aukro.cz. Co tedy můžeme čekat v dalším díle:

  • Postup jak vytvořit testovací účet
  • Získání seznamu aukcí na portálu Aukro.cz
  • Založení nové aukce
  • Další užitečné metody