WAPI – Manuál

V tomto článku se dozvíte:

• Jak funguje WAPI
  • Podporované služby
  • Omezení požadavků
  • Synchronní a asynchronní požadavky
  • Návratové kódy
• Jak aktivovat WAPI v administraci WEDOS Global
• Jak integrovat WAPI do vašeho systému
• Základní požadavky pro otestování funkcí WAPI
• Řešení běžných problémů
• Často kladené otázky

---

WEDOS API (WAPI)

WEDOS API, zkráceně WAPI, slouží ke správě služeb WEDOS přímo z vašeho systému pomocí požadavků a odpovědí.

• Komunikace je buď synchronní (odpověď se obvykle zpracuje během několika sekund od přijetí požadavku) nebo asynchronní (některé odpovědi mohou trvat déle; proces je sledován prostřednictvím notifikací).
• Data se předávají přes HTTPS protokol pomocí POST metodu v parametru requestu; kódování dat je UTF-8.
• Podporované formáty zahrnují XML a JSON.

Podporované služby

WAPI aktuálně podporuje následující služby WEDOS Global:

• Členové WEDOS Global
• WEDOS Protection
• WEDOS DNS a NSSET

Navíc máte přístup ke službám registrátora domén WEDOS:

• Domény
• Kontakty domény
• Kreditní účet

Omezení WAPI

Jako ochranu proti zneužití uplatňuje WAPI následující omezení:

• Jeden uživatelský účet může odeslat maximálně 1000 požadavků za hodinu. Platí to pro všechny typy požadavků. Po dosažení tohoto limitu WAPI odmítá další požadavky až do vypršení časového limitu.
• Jeden uživatelský účet může odeslat maximálně 100 dotazů na dostupnost domény za hodinu. Platí to pro požadavky domain-check, domain-create a domain-transfer-check.
• Opakované neplatné požadavky (selhání autorizace, přístup z neautorizované IP adresy, nesprávný vstup, chybějící nebo nesprávné parametry, neznámé příkazy, příkazy vedoucí k jakékoli chybě nebo jakýkoli požadavek nad rámec ostatních omezení) způsobí zablokování IP adresy na 1 minutu za každý neplatný požadavek přesahující 10. S každým dalším neplatným požadavkem systém prodlužuje dobu blokování.

Synchronní a asynchronní požadavky

Většina požadavků prováděných přes WAPI je synchronních – odešlete požadavek a výsledek obvykle dostanete během několika sekund.

Některé požadavky jsou asynchronní – jejich zpracování může trvat velmi dlouho (i hodiny nebo dny). V takových případech WAPI nevrací konečný výsledek, ale pouze informaci o přijetí požadavku. Systém vám poté zašle informace o průběhu a konečném výsledku formou notifikace.

Návratové kódy

Návratové kódy udávají stav odpovědi WAPI. Některé kódy jsou specifické pro konkrétní požadavek a najdete je v příslušné dokumentaci WAPI; níže uvedený seznam platí pro všechny požadavky.

• 1000 = OK
• 2000 = Chyba při zpracování požadavku
• 2001 = Neplatný požadavek – chybí povinný parametr: user
• 2002 = Neplatný požadavek – chybí povinný parametr: auth
• 2003 = Neplatný požadavek – chybí povinný parametr: command
• 2004 = Neplatný požadavek – je povolen pouze jeden element data
• 2005 = Neplatný požadavek – parametr clTRID je příliš dlouhý
• 2006 = Překročen limit požadavků
• 2007 = Neplatný požadavek – překročena maximální velikost požadavku
• 2008 = Neplatný požadavek – požadavek je příliš složitý
• 2009 = Neplatný požadavek – požadavek je prázdný
• 2010 = Neznámý příkaz
• 2011 = Příkaz je zakázán
• 2050 = Chyba autentizace
• 2051 = Přístup z této IP adresy není povolen
• 2052 = IP adresa dočasně zablokována kvůli příliš mnoha neúspěšným požadavkům
• 2100 = Chybí povinný parametr
• 2101 = Neshoda parametrů
• 2102 = Neplatný požadavek – neshoda kódování vstupních dat
• 4000 = Interní chyba
• 4001 = Interní výjimka
• 5000 = Fatální chyba
• 5001 = Interní chyba autentizace
• 5003 = Mimo provoz

---

Aktivovat WAPI

Než začnete WAPI používat, musíte jej aktivovat. Postupujte takto:

1. Přihlaste se do administrace WEDOS Global ⧉.
2. V levém panelu vyberte WAPI.
3. V Nastavení WAPI formuláři zadejte následující a potvrďte pomocí Nastavit tlačítko:
   • Povolené IP adresy: Čárkou oddělený seznam IP adres (IPv4 i IPv6), ze kterých se váš systém připojuje k WAPI.
   • Režim notifikací: Způsob přijímání oznámení o průběhu asynchronních požadavků.
   • Preferovaný protokol: Toto nastavení platí pouze pro systémové notifikace. Odpovědi používají stejný formát jako požadavky.
4. V Nastavení hesla formuláři zadejte heslo pro WAPI (dvakrát pro potvrzení) a klikněte na Nastavit tlačítko.

Nastavení se projeví do 30 minut.

---

Integrace WAPI do vašeho systému

K integraci WAPI do svého systému po jeho aktivaci potřebujete:

• Vytvoření skriptu pro připojení k API
• Odeslat požadavek
• Přijetí a zpracování odpovědi
• Přijetí a zpracování notifikace

Připojení k WAPI

K připojení svého systému k WAPI budete potřebovat:

• Váš přihlašovací e-mail WEDOS a heslo pro WAPI
• URL adresa WAPI (podle formátu):
  • XML:https://api.wedos.com/wapi/xml
  • JSON:https://api.wedos.com/wapi/json

WAPI přijímá jediný autentizační řetězec, kterým je SHA-1 hash řetězce složeného z uživatelského jména, SHA-1 hashe hesla WAPI a aktuální hodiny (00-23). Časová zóna je Europe/Prague (UTC+1 CET, případně UTC+2 CET při letním čase). Konkrétní příklad najdete v kódu níže.

Následující šablona ukazuje připojení k WAPI pomocí PHP skriptu:

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'your@login.tld'; 
$wpass = 'your-WAPI-password'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'request name',
  'data' => ['request data'],
  'clTRID' => 'request identifier',
  'test' => '1 (if you only want to test the request)'
  ]
];

$post = json_encode($input);
$ch = curl_init($url);
curl_setopt($ch,CURLOPT_TIMEOUT,60);
curl_setopt($ch,CURLOPT_POST,true);
curl_setopt($ch,CURLOPT_POSTFIELDS, 'request=' . urlencode($post));
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
$res = curl_exec($ch);
curl_close($ch);
?>

Požadavek WAPI

WAPI požadavek se skládá z následujících dat:

• test: Příznak testovacího režimu, volitelný. Pokud do požadavku vložíte element test s hodnotou 1, WAPI příkaz pouze zkontroluje, ale neprovede v systému žádné změny.
• uživatel: Přihlášení (e-mail) k vašemu zákaznickému účtu WEDOS, povinné.
• auth: Autorizační řetězec, povinný. Jde o SHA-1 hash řetězce složeného z uživatelského jména, SHA-1 hashe hesla WAPI a aktuální hodiny (00-23). Časové pásmo je Europe/Prague (UTC+1 CET, případně UTC+2 CET s letním časem). Konkrétní příklad najdete v kódu níže.
• příkaz: Vlastní WAPI požadavek. Povinný.
• clTRID: ID požadavku, volitelné. Do tohoto elementu můžete vložit libovolný řetězec jako identifikátor, který WAPI vrátí v odpovědi.
• data: Datová část požadavku. Volitelná.

Následuje šablona JSON požadavku:

{
  "request":
  {
    "user": "your@login.tld",
    "auth": "auth-string",
    "command": "request-name",
    "data":
    {
      request data
    }
    "clTRID": "request-id (optional)",
  }
}

Odpověď WAPI

Odpověď se skládá z následujících dat:

• kód: Návratová hodnota daného požadavku. Více informací o těchto kódech najdete v Návratové kódy sekci a dokumentaci konkrétního příkazu.
• výsledek: Popis návratového kódu.
• timestamp: Čas provedení příkazu v UNIXovém formátu.
• clTRID: Identifikátor požadavku klienta.
• svTRID: Identifikátor požadavku serveru.
• příkaz: WAPI požadavek.
• data: Návratová data. Při neúspěchu požadavku žádná.
• test: Součást odpovědí na testovací požadavky.

Následuje šablona JSON odpovědi:

{
  "response": {
    "code": "numerical code",
    "result": "message",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "request-name"
  }
}

Notifikace

Asynchronní požadavky nelze provést okamžitě. Průběh a výsledek takových operací můžete sledovat prostřednictvím notifikací. Synchronní požadavky notifikace nepoužívají.

Pokud WAPI nemůže operaci dokončit okamžitě, vrátí v odpovědi Request pending (1001). Po dokončení operace (u složitějších akcí jednotlivých kroků) vytvoří notifikaci podobnou klasické odpovědi. Notifikaci můžete přiřadit k odpovídajícímu požadavku pomocí parametrů clTRID nebo svTRID.

Data notifikací jsou vždy kódována v UTF-8.

Notifikace můžete přijímat těmito způsoby (podle nastavení):

• S využitím fronty POLL.
• Odeslat na zadanou e-mailovou adresu.
• Přes protokol HTTP (nebo HTTPS) na vámi zadanou URL adresu metodou POST v parametru request. Za úspěch se považuje HTTP odpověď s návratovým kódem 200. Pokud doručení selže, systém se pokusí notifikaci doručit znovu v několikaminutových intervalech.

Následuje šablona JSON notifikace:

{
  "notify": {
    "code": "numerical code",
    "result": "message",
    "timestamp": "UTF time",
    "svTRID": "server request id",
    "command": "request-name",
    "ID": "numerical id"
  }
}

---

Základní požadavky

Mezi základní požadavky patří ping, ping-async, a příkazy pro práci s frontou POLL poll-req a poll-ack.

ping

Tento ping požadavek slouží k otestování funkčnosti WAPI – například přihlašovacích údajů, IP adresy nebo kódu.

Návratové hodnoty jsou:

• 1000 – OK

Šablona požadavku JSON:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "ping",
    "clTRID": "user request id"
  }
}

Šablona odpovědi JSON:

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping"
  }
}

ping-async

Tento ping-async požadavek testuje funkčnost notifikací WAPI.

Návratové hodnoty jsou:

• 1000 – OK
• 1001 – Čeká se na požadavek

Šablona požadavku JSON:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "ping-async",
    "clTRID": "user request id"
  }
}

Šablona odpovědi JSON:

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping-async"
  }
}

Šablona notifikace JSON:

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "ping-async",
    "id": "poll queue id",
    "data": {
      "round": "attempt number",
      "time": "time",
      "done": 1
    }
  }
}

poll-req a poll-ack

Notifikace z fronty POLL můžete přijímat kombinací poll-req a poll-ack příkazy:

1. Použijte poll-req příkaz pro stažení nejstarší dostupné notifikace.
2. S poll-ack příkaz, označí notifikaci jako přečtenou a zpřístupní novější, dokud se fronta nevyčerpá.

Návratové hodnoty pro poll-req jsou:

• 1000 – oznámení přijato
• 1003 – ve frontě není žádné nepřečtené oznámení
• 2150 – stahování oznámení z fronty je pro tento účet zakázáno

JSON poll-req šablona požadavku:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "poll-req",
    "clTRID": "user request id"
  }
}

JSON poll-req šablona odpovědi (notifikace k dispozici):

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "UTF time",
        "clTRID": "request user id",
        "svTRID": "request server id",
        "command": "request name",
        "id": "poll queue id"
      }
    }
  }
}

JSON poll-req šablona odpovědi (prázdná fronta notifikací):

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": “1286962852”,
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-req"
  }
}

Zahrňte následující parametry do poll-ack požadavek:

• id – ID aktuální poll notifikace

Návratové hodnoty pro poll-ack jsou:

• 1002 – oznámení označeno jako přečtené
• 2151 – oznámení nenalezeno

JSON poll-ack požadavek:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "poll-ack",
    "clTRID": "user request id",
    "data": {
      "id": “poll notification id”
    }
  }
}

JSON poll-ack odpověď:

{
  "response": {
    "code": “1002”,
    "result": "Notification acquired",
    "timestamp": "UTF time",
    "clTRID": "user request id",
    "svTRID": "server request id",
    "command": "poll-ack"
  }
}

---

Řešení běžných problémů

Mezi časté problémy s WAPI patří:

• Nezdařená autentizace požadavků

---

FAQ