SLEDUJTE NÁS:

Doménové API

API registrace domén

API (Application Programming Interface) je určen pro vzdálený – strojový přístup k rozhraní pro správu doménových jmen. Rozhraní je zpřístupněno pomocí protokolu SOAP (Simple Object Access Protocol), který má podporu ve většině běžně používaných jazyků.

Historie

Verze 2.0 (26. 10. 2010)

  • Nové rozhraní.
  • Nová dokumentace.

Verze 1.3 (16.02.2009)

  • Přidání funkcí pro zaslání transfer hesel.
  • Úprava dokumentace.

Verze 1.2 (9.10.2008)

  • Úprava dokumentace (chybové kódy).
  • Přidání COCZ funkcí.

Verze 1.1 (22.04.2008)

  • Přidána captcha k infoslužbám pro cizí .CZ domény.
  • Přidány info služby (vlastní domény bez captcha).

Verze 1.0 (15.04.2008)

  • Zveřejnění API.

Jak získat přístup k API

Pro přístup k doménovému API stačí mít přístup k ovládacímu panelu se službou „Správa Domén“. Pokud účet nemáte stačí jej zaregistrovat. Po úspěšné registraci máte zřízeny jak doménové služby v ovládacím panelu tak i SOAP přístup, který můžete ihned využívat dle níže uvedené dokumentace.

Pravidla použití

Pravidla použití se řídí především Smluvními dokumenty.

Uživatel je dále oprávněn službu užívat pouze v případě, že:

  • užití není v rozporu s dobrými mravy a právy třetích osob,
  • uživatel nezneužívá službu pro strojové čtení dat službou poskytnuté,
  • uživatel nezneužije rozhraní k poškození poskytovatele.

Limity přístupů

Služba má interně nastavené bezpečnostní limity pro volání.

Omezení dle IP adresy

API dokáže přijímat rychlostí cca 3 požadavky za sekundu. Pokud je k API přistupováno z více vláken je nutné dodržet limit 3 požadavky za sekundu. V případě nedodžení stanoveného limitu systém vrací vyjimky. Pokud však přistupujete z jednoho vlánka (aplikace) stačí rozhraní běžně používat a k vrácení výjimky nedojde.

Omezení na počty volání jednotlivých funkcí:

Pokud bude volána jakákoliv stejná funkce dříve jak 3 sec od předchozího volání bude o 3 sec pozdržena (první volání je bez zdržení). V případě volání vícevláknově (několik spojení zároveň) je při nedodžení odstupu 3 sec vyvolána výjimka.

V praxi limity fungují následovně:

// Bez omezení
domainContactCreate();
domainNSSetCreate();
domainCreate();

// Druhé volání opožděno o 3 vteřiny.
comainContactCreate();
domainContactCreate();

Příklad volání z PHP5

Základní předpoklady:
  • je vyžadována verze PHP5,
  • všechny vstupy a výstupy jsou v UTF8,
  • adresa WSDL je http://www.web4u.cz/cp/wsdl/Web4uGateway.wsdl
  • každé volání má první tři parametry obdobné – přihlašovací jméno, heslo, identifikátor služby, za nimi následuje object s nastavenými parametry volání.
Ověření funkčnosti SOAP volání

Zda vše funguje jak má lze ověřit následujícím způsobem:

$client = new SoapClient("http://www.web4u.cz/cp/wsdl/Web4uGateway.wsdl");
echo $client->greeting();

Volání vypíše: Greeting from Web4u soap gateway

Jak získat identifikátor služby:

Identifikátor služby (Správy Domén), pod kterou budete funkce volat, získáte jakýmkoliv zavoláním existující funkce, pouze s vašimi parametry „login“, „password“. Výsledkem bude výjimka obsahující přehled použitelných služeb s jejich ID.

try{
	$client = new SoapClient("http://www.web4u.cz/cp/wsdl/Web4uGateway.wsdl", $options);
	$result = $client->domainCheck("login", "password");
}catch(Exception $e){
	var_dump($e->getMessage());
}

Přehled služeb můžete získat také voláním funkce getServiceList s parametry „login“, „password“.

Příklad volání
try{
	$options = array(
		"cache_wsdl" => WSDL_CACHE_NONE,
		"features"   => SOAP_SINGLE_ELEMENT_ARRAYS
	);
	$client = new SoapClient("http://www.web4u.cz/cp/wsdl/Web4uGateway.wsdl", $options);
	$params = array(array(
		"name" => "domain_name", // Název attributu
		"data" => "test.cz" // Hodnota attributu
	));
	$result = $client->domainCheck(
		"login", "password", "id_service", $params
	);
}catch(SoapFault $e){
	// Zpracování soap výjimky
}catch(Exception $e){
	// Zpracování ostatních výjimek
}
var_dump($result);

První parametry lze pak skrýt následovně:

class Web4uSoapClient extends SoapClient{
	static private
		$options = array(
			"cache_wsdl" => WSDL_CACHE_NONE,
			"features"   => SOAP_SINGLE_ELEMENT_ARRAYS
		),
		$url = "http://www.web4u.cz/cp/wsdl/Web4uGateway.wsdl",
		$login = "muj_login",
		$pwd = "moje_heslo",
		$srv = "moje_service_id"
	;

	public function __construct(){
		parent::__construct(self::$url, self::$options);
	}

	public function __call($method, $args){
		return parent::__call($method, array(
			self::$login, self::$pwd, self::$srv, $args[0]
		));
	}
}

pak voláme:

...
$client = new Web4uSoapClient();
$result = $client->domainCheck(array(array(
	"name" => "domain_name", "data" > "test.cz"
)));
print_r($result);
...

Příklad zpracování chyb

try{
	$client = new Web4uSoapClient();
	$result = $client->domainCheck(array(array(
		"name" => "domain_name", "data" => "test.cz"
	)));
}catch(SoapFault $e){ // Zpracování soap výjimky
	// Validační chyby
	if($e->faultcode == 10){
		$lines = explode("\n", $e->faultstring);
		foreach($lines as $line){ // Získané hodnoty z validátoru
			list($ecode, $emesg, $eexam, $ehelp, $eval) = explode('|',$line);
			print_r($emesg);
		}
	}else{ // Ostatní zpracování
		print_r($e->faultstring);
	}
}catch(Exception $e){ // Zpracování ostatních výjimek
	print_r($e->getMessage());
}
print_r($result);

Tabulka chybových hlášení

Chyby které jsou vraceny přímo (s chybovým kódem):

ČísloPopis
1 Chyba při přihlašování, nevyplněn login, heslo, nebo jsou údaje nesprávné.
2 Chybný počet vstupních parametrů, očekáván jiný počet.
3 Na požadovanou službu nemáte právo (tato služba není v aktuálně zvoleném servisu nebo je chybně parametr$service).
4 Seznam UID použitelných servisů s jejich popisem (seznam sprav domen, webhostingu, atd.)
5 Tuto službu nemáte povolenou – je volána metoda, kterou nemáte ve Vašem účtu oprávnění.
8 Zvolené service ID nepodporuje doménové operace (je potreba zvolit ID některé ze service typu správa domén).
9 Neočekávaná sytémová chyba.
10 Chyba validace vstupních parametrů: v chybě je obsažen seznam chybných parametrů oddělených

Následující chyby jsou „zabaleny“ v chybě číslo 10 (chyba validace), pokud mají číslo jedná se o níže definované chyby, jinak se jedná o chyby validačního charakteru.

ČísloPopis
6 Nebyly vyplněny všechny požadované parametry
7 Doménaje jiz obsazena, prosím zvolte jiný název.
11 Nebyly vyplněny všechny požadované parametry u adm_c
12 Doménaje neexistuje!
13 Parametry mimo povolený rozsah!
14 Doména není v naší správě!
15 Doména je již u nás vedena!
16 Doména není vedena ve Vašem účtu, informace o ní tak není možné získat!
17 Chybný typ autorizace požadavku!
18 Chyba při získávání informací o doméně!
19 Prodloužení domény již není možné!, prosím použijte volbu obnovení domény.
20 Obnovení domény není možné použít!, prosím použijte volbu prodloužení domény.
21 Kontakt již existuje
22 Pokud zadáváte identifikační parametry, musí bý zadány kompletně!
23 NSSet již existuje
24 Kontakt neexistuje
25 NSSet neexistuje
26 NSSet je již u nás veden!
27 Kontakt je již u nás veden!
28 NSSet není v naší správě!
29 Autorizační kontakt nemá právo změnu potvrdit!
30 Chybné autorizační heslo!
31 Kontak není v naší správě!
32 Nebyla provedena žádná změna!
33 Chybná verze pravidel!
34 Nevyplněna informace o klientovi, který potvrdil pravidla!
35 Rozdílné jméno v souhlasu s pravidly vs jméno držitele domény!
36 Nebyl potvrzen souhlas s pravidly!
37 Doména není v naší správě!
38 Autorizace heslem není v případě změny držitele povolena!
39 Nevyplněn nový držitel doménového jména!
40 Stávající i nový držitel doménového jména je shodný!
41 Chybně zadaný počet let!
42 Nameserver nemůže být použít vícekrát, musí být použity různé adresy nameserverů!
43 Chybně zadaný captcha kód!
44 Klíč není korektní!
45 Příliš mnoho klíčů!
46 Klíč je duplicitní!
47 Požadavek na službu nenalezen!
48 Neoprávněný přístup k požadavku na službu!
49 Doménový požadavek nenalezen!