WAPI - Manuál

V tomto článku se dozvíte:

• Jak funguje rozhraní WAPI
  • Podporované služby
  • Omezení žádosti
  • Synchronní a asynchronní požadavky
• Jak aktivovat WAPI v administraci WEDOS Global
• Jak integrovat rozhraní WAPI do systému
• Základní požadavky na testování funkcí WAPI
• Řešení běžných problémů
• Často kladené otázky

---

ROZHRANÍ WEDOS API (WAPI)

Rozhraní WEDOS API, zkráceně WAPI, slouží ke správě služeb WEDOS přímo ze systému prostřednictvím požadavků a odpovědí.

• Komunikace je buď synchronní (odpověď je zpracována obvykle do několika sekund od přijetí požadavku), nebo asynchronní (některé odpovědi mohou trvat déle; proces je monitorován prostřednictvím oznámení).
• Data jsou předávána protokolem HTTPS metodou POST v parametru požadavku; kódování dat je UTF-8.
• Podporované formáty zahrnují XML i JSON.

Podporované služby

WAPI v současné době podporuje následující služby WEDOS Global:

• WEDOS Global Oprávnění uživatelé
• WEDOS Protection
• WEDOS DNS a NSSET

Kromě toho máte přístup ke službám registrátora domén WEDOS:

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

Omezení WAPI

Na ochranu před zneužitím uplatňuje rozhraní WAPI následující omezení:

• Jeden uživatelský účet může odeslat maximálně 1000 požadavků za hodinu. To platí pro všechny typy požadavků. Po dosažení tohoto limitu rozhraní WAPI odmítá další požadavky, dokud nevyprší časový limit.
• Jeden uživatelský účet může za hodinu podat maximálně 100 požadavků na dostupnost domény. To platí pro požadavky na kontrolu domény, vytvoření domény a kontrolu přenosu domény.
• Opakované neplatné požadavky (selhání autorizace, přístup z neautorizované IP adresy, nesprávné zadání, chybějící nebo nesprávné parametry, neznámé příkazy, příkazy, které vedou k jakékoli chybě, nebo jakýkoli požadavek nad rámec jiných omezení) způsobí zablokování IP adresy na 1 minutu za každý neplatný požadavek nad 10. S každým dalším neplatným požadavkem systém dobu blokování prodlouží.

Synchronní a asynchronní požadavky

Většina požadavků prováděných prostřednictvím rozhraní WAPI je synchronní - odešlete požadavek a výsledek obvykle obdržíte 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 rozhraní WAPI nevrací konečný výsledek, ale pouze informaci o přijetí požadavku. Systém pak zasílá informace o průběhu a konečném výsledku ve formě oznámení.

---

Aktivace rozhraní WAPI

Než začnete WAPI používat, musíte jej aktivovat. Postupujte podle následujících kroků:

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

Nastavení se projeví do 30 minut.

---

Integrace rozhraní WAPI do systému

Chcete-li integrovat rozhraní WAPI do systému po jeho aktivaci, musíte:

• Nastavení skriptu pro připojení k rozhraní API
• Odeslat žádost
• Přijetí a zpracování odpovědi
• Přijetí a zpracování oznámení

Připojení k WAPI

K připojení systému k WAPI potřebujete:

• Váš přihlašovací e-mail do systému WEDOS a heslo WAPI.
• Adresa URL rozhraní WAPI (závisí na formátu):
  • XML: https://api.wedos.com/wapi/xml
  • JSON: https://api.wedos.com/wapi/json

WAPI přijímá jediný ověřovací řetězec, který je sha1 hash řetězce složeného z uživatelského jména, sha1 hash hesla WAPI a aktuálního času (00-23). Časové pásmo je Evropa/Praha (UTC+1 CET nebo UTC+2 CET s úpravou na letní čas). Konkrétní příklad viz kód níže.

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

<?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=' . $post);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
$res = curl_exec($ch);
?>

Požadavek WAPI

Požadavek WAPI se skládá z následujících údajů:

• test: Testovací režim, nepovinné. Pokud do požadavku zahrnete prvek test s hodnotou 1, WAPI příkaz pouze zkontroluje, ale neprovede v systému žádné změny.
• uživatel:(e-mail), povinné.
• auth: Autorizační řetězec, povinné. Jedná se o sha1 hash řetězce složeného z uživatelského jména, sha1 hashe hesla WAPI a aktuálního času (00-23). Časové pásmo je Evropa/Praha (UTC+1 CET nebo UTC+2 CET s úpravou na letní čas). Konkrétní příklad viz kód níže.
• příkaz: skutečný požadavek WAPI. Povinné.
• clTRID: ID požadavku, nepovinné. Do tohoto elementu můžete vložit libovolný řetězec jako identifikátor, který WAPI vrátí v odpovědi.
• údaje: Datová část požadavku. Nepovinné.

Následuje šablona požadavku JSON:

{
  "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 údajů:

• kód: Návratová hodnota pro daný požadavek. Další informace o těchto kódech najdete v dokumentaci ke konkrétnímu příkazu.
• výsledek: Popis návratového kódu.
• časové razítko: Čas provedení příkazu ve formátu UNIX.
• clTRID: Identifikátor požadavku klienta.
• svTRID: Identifikátor požadavku serveru.
• příkaz: WAPI request.
• údaje: Vrátit data. Žádné, pokud se požadavek nezdaří.
• test: Včetně odpovědí na žádosti o testování.

Následuje šablona odpovědi JSON:

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

Oznámení

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

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

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

Oznámení můžete přijímat následujícími způsoby (podle nastavení):

• Použití fronty POLL.
• Odeslat na zadanou e-mailovou adresu.
• prostřednictvím protokolu HTTP (nebo HTTPS) na vámi zadanou adresu URL pomocí metody POST v parametru požadavku. Odpověď HTTP s návratovým kódem 200 je považována za úspěšnou. Pokud se doručení nezdaří, systém se pokusí doručit oznámení znovuv několikaminutových intervalech.

Následuje šablona oznámení JSON:

{
  "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

Požadavek ping se používá k testování funkčnosti rozhraní WAPI - například přihlašovacích údajů, adresy IP 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

Požadavek ping-async testuje funkčnost oznámení WAPI.

Návratové hodnoty jsou:

• 1000 - OK
• 1001 - Čekání na požadavek

Šablona požadavku JSON:

{
  "request": {
    "user": "your@login.tld",
    "auth": "auth code",
    "command": "ping",
    "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"
  }
}

Šablona oznámení 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

Oznámení z fronty POLL můžete přijímat kombinací příkazů poll-req a poll-ack:

1. Pomocí příkazu poll-req stáhnete nejstarší dostupné oznámení.
2. Příkazem poll-ack označíte oznámení jako přečtené a zpřístupníte novější, dokud nebude fronta vyčerpána.

Návratové hodnoty pro poll-req jsou:

• 1000 - přijaté oznámení
• 1003 - ve frontě není žádné nepřečtené oznámení
• 2150 - pro tento účet jsou vypnuta oznámení z volební fronty

JSON poll-req šablona žádosti:

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

JSON poll-req šablona odpovědi (k dispozici oznámení):

{
  "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 oznámení):

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

V požadavku na poll-ack uveďte následující parametry:

• id - ID aktuálního oznámení o průzkumu

Návratové hodnoty pro poll-ack jsou:

• 1002 - oznámení označeno jako přečtené
• 2151 - oznámení nebylo nalezeno

JSON poll-ack žádost:

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

JSON poll-ack reakce:

{
  "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 běžné problémy s rozhraním WAPI patří:

• Selhání ověřování požadavků

---

ČASTO KLADENÉ DOTAZY