Základné pojmy

  • Kanálom, cez ktorý prebieha komunikácia, je HTTPS. HTTP je jednoduchý textový protokol, S na konci znamená Secure = komunikácia s API prebieha v šifrovanej forme.

  • API štandardne vracia JSON, v prípade že uprednostňujete XML nastavte output na XML.

    
                $query = array(
    				'mid' => $mid, // Vaše základne ID
    				'timestamp' => $time, // Čas vytvorenia podpisu
    				'sign' => $sign, // Podpis
    				'output' => 'XML', //API vráti, xml dokument.
    				...
    			);
                
  • Každý zdroj dát reprezentuje určitá url adresa.

  • API akceptuje iba metódu POST. Bez ohľadu na typ požiadavky. POST-om sa okrem potrebných informácií posiela aj vaše identifikačné číslo, vygenerovaný podpis a čas, kedy bol podpis vytvorený.

  • Bez overenia podpisu, sa požiadavka nespracuje. Rovnako každá informácia, ktorú API vráti musí byť podpísaná. Neodporúčame akceptovať nepodpísané odpovede.

  • SIGN - bezpečnostný podpis, vytvára sa predpísaným postupom. Overuje sa ním komunikácia.

Zabezpečenie

Ako sa píše vyššie, komunikácia probieha šifrovane pomocou HTTPS; prípadný útočník teda nemôže odpočúvať data, ktoré si cez Odpadneš.sk API vymieňate.

Autentifikácia prebieha overením podpisu. Podpis sa generuje na základe identifikačných údajov, ktoré vám dodáme.

Príklad vytvorenia podpisu. Vaše identifikačné údaje sú napríklad: ID = 1xmpl11 a Heslo = 1Dva3456.

V prvom kroku zreťazíme ID, časovú značku(môže byť Unix Timestamp, alebo dátum vo formáte Y-m-d) a dáta k podpisu.

Zo zreťazeného stringu vytvoríme MD5 hash. Tento hash zašifrujeme pomocou hesla, metódou sha256. Z prvých 16 znakov vytvoríme znovu MD5 a prepíšeme veľkými písmenami.

Získaný podpis porovnáme. V prípade, že sa podpis nezhoduje, nie je možné považovať komunikáciu za bezpečnú. API v takom prípade vráti chybové hlásenie.

Z vlastných skúsenosti vieme, že vytvorenie podpisu môže spôsobovať problémy. Preto sme pre vás vytvorili knižnicu, ktorá zabezpečí vytvorenie podpisu.

API root

URL budú uvádzané relatívne voči tzv. API root, ten je:

https://partner.odpadnes.sk/api/v1

V prípade, že request bude /stat/used, jeho absolútna URL je https://dsapi.odpadnes.sk/api/v1/stat/used.

Metódy

Firmy

Pridanie firmy

Firma je miesto, kde sa predávaná služba môže uplatniť. Môže to byť napríklad hotel, reštaurácia, masážny salón a podobne.

Firmu pridáte poslaním POST požiadavky na url /firm/add.
V poste musíte poslať podpis, čas, kedy bol podpis vytvorený, vaše ID a dáta potrebné pre vytvorenie firmy.


		//vytvorenie podpisu
		$sign = odpadnes_sign::gi()->getKey($mid,$pass,$time,array('firm-add'));
		//poslanie požiadavky
		$query = array(
			'mid' => $mid, // vaše základne ID
			'timestamp' => $time, // čas vytvorenia podpisu
			'sign' => $sign, // podpis
			'id_portal' => $id, // id portálu vám dodáme spolu s heslo a základným id pre vytvorenie podpisu
			'name' => $data['name'], // nazov firmy, pomenovanie hotela, alebo služby
			'street' => $data['street'], // adresa kde je možné dostať službu - ulica
			'city' => $data['city'], // mesto
			'zip' => $data['zip'], // psč
			'country' => $data['country'], // krajina
			'mail' => $data['mail'], // email na zariadenie
			'phone' => $data['phone'], // telefon na zariadenie
			'web' => $data['web'], // URL adresa zariadenia, voliteľný údaj
			'gps' => $data['gps'], // GPS zariadenia, voliteľný údaj
			'description' => $data['description'], // popis zariadenia, voliteľný údaj
			'storno' => $data['storno'], // storno podmienky, voliteľný údaj
			'howTo' => $data['how_to'], // ako uplatniť, voliteľný údaj
			'important' => $data['important'] // doplnkové info, voliteľný údaj
		);
		$curlConfig = array(
			CURLOPT_URL            => $url,
			CURLOPT_POST           => true,
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_POSTFIELDS     => http_build_query($query)
		);
		curl_setopt_array($ch, $curlConfig);
		$result = curl_exec($ch);
		curl_close($ch);
	

Výstupom je JSON alebo XML podľa zvoleného výstupu. Vo výstupe bude stav spracovania a ID firmy vytvorené v našom systéme. Toto ID použijete na poslanie fotogalérie.

Pridanie fotogalérie firmy

Fotogaléria sa zobrazuje v detaile firmy. Posielajte obrázky v minimálnej šírke 900px.

Fotogalériu pridáte poslaním POST požiadavky na url /firm/add-photo.
V poste musíte poslať podpis, čas, kedy bol podpis vytvorený, vaše ID, ID firmy, ktoré ste získali pri vytváraní firmy a url adresu obrázku. Posielať môžete viac obrázkov naraz. Obrázky nemusia patriť k jednej firme, preto je potrebné identifikovať, ku ktorej firme obrázok patrí.


		//vytvorenie podpisu
		$sign = odpadnes_sign::gi()->getKey($mid,$pass,$time,array('firm-add-photo'));
		//poslanie požiadavky
		$query = array(
			'mid' => $mid, // vaše základne ID
			'timestamp' => $time, // čas vytvorenia podpisu
			'sign' => $sign, // podpis
			'photos' => array(
				array(
					'id_portal' => $id, // ID portálu vám dodáme spolu s heslo a základným ID pre vytvorenie podpisu.
					'id_firm' => $id_firm, // ID firmy, ziskali ste ho pri vkladani firmy.
					'url' => $url, // url adresa obrazku.
				),
				...
			)
		);
		$curlConfig = array(
			CURLOPT_URL            => $url,
			CURLOPT_POST           => true,
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_POSTFIELDS     => http_build_query($query)
		);
		curl_setopt_array($ch, $curlConfig);
		$result = curl_exec($ch);
		curl_close($ch);
	

Zoznam firiem

Zoznam firiem, ktoré ste pridali do Odpadneš.sk získate zavolaním requestu /firm/get-list.


		//vytvorenie podpisu
		$sign = odpadnes_sign::gi()->getKey($mid,$pass,$time,array('firm-get-list'));
		//poslanie požiadavky
		$query = array(
			'mid' => $mid, // vaše základne ID
			'timestamp' => $time, // čas vytvorenia podpisu
			'sign' => $sign, // podpis
			'id_portal' => $id  // ID portálu vám dodáme spolu s heslo a základným iIDd pre vytvorenie podpisu.
		);
		$curlConfig = array(
			CURLOPT_URL            => $url,
			CURLOPT_POST           => true,
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_POSTFIELDS     => http_build_query($query)
		);
		curl_setopt_array($ch, $curlConfig);
		$result = curl_exec($ch);
		curl_close($ch);
	

Ponuky

Pridanie ponuky

Ponuky sa pridávajú ku konkrétnej firme, k jednej firme môžete pridať viac ponúk. Ponuky pridáte poslaním POST requestu na url /deal/add.


		//vytvorenie podpisu
		$sign = odpadnes_sign::gi()->getKey($mid,$pass,$time,array('deal-add'));
		//poslanie požiadavky
		$query = array(
			'mid' => $mid, // Vaše základne ID
			'timestamp' => $time, // Čas vytvorenia podpisu
			'sign' => $sign, // Podpis
			'id_portal' => $id  // ID portálu vám dodáme spolu s heslo a základným ID pre vytvorenie podpisu.
			'id_firm' => $data['id_firm'], // ID firmy pre ktorú chcete pridať ponuku.
			'date_start_sell' => $data['date_start_sell'], // Začiatok predaja.
			'date_end_sell' => $data['date_end_sell'], // Koniec predaja.
			'date_start_voucher' => $data['date_start_voucher'], // Začiatok platnosti kupónu.
			'date_end_voucher' => $data['date_end_voucher'], // Koniec platnosti kupónu.
			'limit' => $data['limit'], // Limit predaných kupónov. 0 = neobmedzené množstvo.
			'title' => $data['title'], // Názov ponuky.
			'original_price' => $data['original_price'], // Pôvodná cena.
			'final_price' => $data['final_price'], // Cena po zľave.
			'nights_count' => $data['nights_count'], // Počet nocí. Voliteľný údaj, uvadzajte počet noci pri pobytoch.
			'description' => $data['description'], // Popis ponuky.
			'how_to' => $data['how_to'], // Ako uplatniť kupón, voliteľný údaj.
			'important' => $data['important'], // Dôležité info, voliteľný údaj.
			'storno' => $data['storno'], // Storno podmienky, voliteľný údaj.
			'charges' => $data['charges'] // Príplatky, voliteľný údaj.
		);
		$curlConfig = array(
			CURLOPT_URL            => $url,
			CURLOPT_POST           => true,
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_POSTFIELDS     => http_build_query($query)
		);
		curl_setopt_array($ch, $curlConfig);
		$result = curl_exec($ch);
		curl_close($ch);
	

Zoznam ponúk

Zoznam ponúk firmy získate poslaním POST requestu na /deal/get-list.


		//vytvorenie podpisu
		$sign = odpadnes_sign::gi()->getKey($mid,$pass,$time,array('deal-get-list'));
		//poslanie požiadavky
		$query = array(
			'mid' => $mid, // Vaše základne ID
			'timestamp' => $time, // Čas vytvorenia podpisu
			'sign' => $sign, // Podpis
			'id_portal' => $id  // ID portálu vám dodáme spolu s heslo a základným ID pre vytvorenie podpisu.
			'id_firm' => $data['id_firm'], // ID firmy pre ktorú chcete získať zoznám ponúk.
		);
		$curlConfig = array(
			CURLOPT_URL            => $url,
			CURLOPT_POST           => true,
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_POSTFIELDS     => http_build_query($query)
		);
		curl_setopt_array($ch, $curlConfig);
		$result = curl_exec($ch);
		curl_close($ch);
	

Vypnutie ponuky

V prípade potreby ponuku vypnete poslaním POST requestu na /deal/off.


		//vytvorenie podpisu
		$sign = odpadnes_sign::gi()->getKey($mid,$pass,$time,array('deal-off'));
		//poslanie požiadavky
		$query = array(
			'mid' => $mid, // Vaše základne ID
			'timestamp' => $time, // Čas vytvorenia podpisu
			'sign' => $sign, // Podpis
			'id_portal' => $id  // ID portálu vám dodáme spolu s heslo a základným ID pre vytvorenie podpisu.
			'id_firm' => $data['id_firm'], // ID firmy pre ktorú chcete získať zoznám ponúk.
			'id_deal' => $data['id_deal'] // ID ponuky ktorú chcete vypnúť.
		);
		$curlConfig = array(
			CURLOPT_URL            => $url,
			CURLOPT_POST           => true,
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_POSTFIELDS     => http_build_query($query)
		);
		curl_setopt_array($ch, $curlConfig);
		$result = curl_exec($ch);
		curl_close($ch);
	

Zapnutie ponuky

V prípade potreby ponuku zapnete poslaním POST requestu na /deal/on. Zapnúť môžte iba ponuku, ktorú ste vypli zavolaním /deal/off. Ukončenú, alebo administrátorom vypnutú nie je možne touto metódou zapnúť.


		//vytvorenie podpisu
		$sign = odpadnes_sign::gi()->getKey($mid,$pass,$time,array('deal-off'));
		//poslanie požiadavky
		$query = array(
			'mid' => $mid, // Vaše základne ID
			'timestamp' => $time, // Čas vytvorenia podpisu
			'sign' => $sign, // Podpis
			'id_portal' => $id  // ID portálu vám dodáme spolu s heslo a základným ID pre vytvorenie podpisu.
			'id_firm' => $data['id_firm'], // ID firmy.
			'id_deal' => $data['id_deal'] // ID ponuky ktorú chcete zapnúť.
		);
		$curlConfig = array(
			CURLOPT_URL            => $url,
			CURLOPT_POST           => true,
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_POSTFIELDS     => http_build_query($query)
		);
		curl_setopt_array($ch, $curlConfig);
		$result = curl_exec($ch);
		curl_close($ch);
	

Kupón

Uplatnený

Uplatnenie kupónov môžete vykonať poslaním POST requestu na /order/used.


		//vytvorenie podpisu
		$sign = odpadnes_sign::gi()->getKey($mid,$pass,$time,array('order-used'));
		//poslanie požiadavky
		$query = array(
			'mid' => $mid, // Vaše základne ID
			'timestamp' => $time, // Čas vytvorenia podpisu
			'sign' => $sign, // Podpis
			'code' => $data['code'] // Kód kupónu, ktorý bol uplatnený.
		);
		$curlConfig = array(
			CURLOPT_URL            => $url,
			CURLOPT_POST           => true,
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_POSTFIELDS     => http_build_query($query)
		);
		curl_setopt_array($ch, $curlConfig);
		$result = curl_exec($ch);
		curl_close($ch);
	

Zrušené

Storno kupónu môžete vykonať poslaním POST requestu na /order/cancel.


		//vytvorenie podpisu
		$sign = odpadnes_sign::gi()->getKey($mid,$pass,$time,array('order-cancel'));
		//poslanie požiadavky
		$query = array(
			'mid' => $mid, // Vaše základne ID
			'timestamp' => $time, // Čas vytvorenia podpisu
			'sign' => $sign, // Podpis
			'code' => $data['code'] // Kód kupónu, ktorý bol uplatnený.
		);
		$curlConfig = array(
			CURLOPT_URL            => $url,
			CURLOPT_POST           => true,
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_POSTFIELDS     => http_build_query($query)
		);
		curl_setopt_array($ch, $curlConfig);
		$result = curl_exec($ch);
		curl_close($ch);
	

Štatistika

Predané

Štatistiky predaných kupónov si môžete stiahnuť poslaním POST requestu na /stat/sold.


		//vytvorenie podpisu
		$sign = odpadnes_sign::gi()->getKey($mid,$pass,$time,array('stat-sold'));
		//poslanie požiadavky
		$query = array(
			'mid' => $mid, // Vaše základne ID
			'timestamp' => $time, // Čas vytvorenia podpisu
			'sign' => $sign, // Podpis
			'id_portal' => $id  // ID portálu vám dodáme spolu s heslo a základným ID pre vytvorenie podpisu.
			'id_firm' => $data['id_firm'], // ID firmy.
			'id_deal' => $data['id_deal'] // ID ponuky pre ktorú chcete získať štatistiku.
		);
		$curlConfig = array(
			CURLOPT_URL            => $url,
			CURLOPT_POST           => true,
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_POSTFIELDS     => http_build_query($query)
		);
		curl_setopt_array($ch, $curlConfig);
		$result = curl_exec($ch);
		curl_close($ch);
	

Uplatnené

Štatistiky uplatnených kupónov si môžete stiahnuť poslaním POST requestu na /stat/used.


		//vytvorenie podpisu
		$sign = odpadnes_sign::gi()->getKey($mid,$pass,$time,array('stat-used'));
		//poslanie požiadavky
		$query = array(
			'mid' => $mid, // Vaše základne ID
			'timestamp' => $time, // Čas vytvorenia podpisu
			'sign' => $sign, // Podpis
			'id_portal' => $id  // ID portálu vám dodáme spolu s heslo a základným ID pre vytvorenie podpisu.
			'id_firm' => $data['id_firm'], // ID firmy.
			'id_deal' => $data['id_deal'] // ID ponuky pre ktorú chcete získať štatistiku.
		);
		$curlConfig = array(
			CURLOPT_URL            => $url,
			CURLOPT_POST           => true,
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_POSTFIELDS     => http_build_query($query)
		);
		curl_setopt_array($ch, $curlConfig);
		$result = curl_exec($ch);
		curl_close($ch);
	

Zrušené

Štatistiky stornovaných kupónov si môžete stiahnuť poslaním POST requestu na /stat/cancel.


		//vytvorenie podpisu
		$sign = odpadnes_sign::gi()->getKey($mid,$pass,$time,array('stat-cancel'));
		//poslanie požiadavky
		$query = array(
			'mid' => $mid, // Vaše základne ID
			'timestamp' => $time, // Čas vytvorenia podpisu
			'sign' => $sign, // Podpis
			'id_portal' => $id  // ID portálu vám dodáme spolu s heslo a základným ID pre vytvorenie podpisu.
			'id_firm' => $data['id_firm'], // ID firmy.
			'id_deal' => $data['id_deal'] // ID ponuky pre ktorú chcete získať štatistiku.
		);
		$curlConfig = array(
			CURLOPT_URL            => $url,
			CURLOPT_POST           => true,
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_POSTFIELDS     => http_build_query($query)
		);
		curl_setopt_array($ch, $curlConfig);
		$result = curl_exec($ch);
		curl_close($ch);