WAPI - Podręcznik

W tym artykule dowiesz się:

• Jak działa WAPI
  • Usługi wspomagane
  • Ograniczenia dotyczące żądań
  • Żądania synchroniczne i asynchroniczne
• Jak aktywować WAPI w panelu administracyjnym WEDOS Global?
• Jak zintegrować WAPI z systemem
• Podstawowe żądania testowania funkcji WAPI
• Rozwiązywanie typowych problemów
• Często zadawane pytania

---

WEDOS API (WAPI)

WEDOS API, w skrócie WAPI, służy do zarządzania usługami WEDOS bezpośrednio z systemu za pośrednictwem żądań i odpowiedzi.

• Komunikacja jest synchroniczna (odpowiedź jest przetwarzana zazwyczaj w ciągu kilku sekund od otrzymania żądania) lub asynchroniczna (niektóre odpowiedzi mogą trwać dłużej; proces jest monitorowany za pomocą powiadomień).
• Dane są przekazywane za pośrednictwem protokołu HTTPS metodą POST w parametrze żądania; kodowanie danych to UTF-8.
• Obsługiwane formaty obejmują zarówno XML, jak i JSON.

Usługi wspomagane

WAPI obsługuje obecnie następujące usługi WEDOS Global:

• Globalni członkowie WEDOS
• Ochrona WEDOS
• WEDOS DNS i NSSET

Dodatkowo można uzyskać dostęp do usług rejestratora domen WEDOS:

• Domeny
• Kontakty w domenie
• Rachunek kredytowy

Ograniczenia WAPI

Aby chronić przed niewłaściwym użyciem, WAPI stosuje następujące ograniczenia:

• Jedno konto użytkownika może wysłać maksymalnie 1000 żądań na godzinę. Dotyczy to wszystkich typów żądań. Po osiągnięciu tego limitu WAPI odrzuca kolejne żądania do momentu wygaśnięcia limitu czasu.
• Jedno konto użytkownika może wykonać maksymalnie 100 żądań dostępności domeny na godzinę. Dotyczy to żądań sprawdzenia domeny, utworzenia domeny i sprawdzenia transferu domeny.
• Powtarzające się nieprawidłowe żądania (niepowodzenie autoryzacji, dostęp z nieautoryzowanego adresu IP, nieprawidłowe dane wejściowe, brakujące lub nieprawidłowe parametry, nieznane polecenia, polecenia skutkujące błędem lub wszelkie żądania wykraczające poza inne ograniczenia) spowodują zablokowanie adresu IP na 1 minutę za każde nieprawidłowe żądanie przekraczające 10. Z każdym dodatkowym nieprawidłowym żądaniem system wydłuża czas blokady.

Żądania synchroniczne i asynchroniczne

Większość żądań wykonywanych za pośrednictwem WAPI jest synchroniczna - wysyłasz żądanie i zazwyczaj otrzymujesz wynik w ciągu kilku sekund.

Niektóre żądania są asynchroniczne - przetwarzanie takich żądań może trwać bardzo długo (nawet godziny lub dni). W takich przypadkach WAPI nie zwraca końcowego wyniku, a jedynie informację o otrzymaniu żądania. Następnie system wysyła informacje o postępie i ostatecznym wyniku w formie powiadomień.

---

Aktywacja WAPI

Przed rozpoczęciem korzystania z WAPI należy go aktywować. Wykonaj następujące kroki:

1. Zaloguj się do panelu administracyjnego WEDOS Global ⧉.
2. Na lewym pasku wybierz WAPI.
3. W Konfiguracja WAPI wprowadź następujące dane i potwierdź za pomocą przycisku Zestaw przycisk:
   • Dozwolone adresy IP: Rozdzielana przecinkami lista adresów IP (zarówno IPv4, jak i IPv6), z których system łączy się z WAPI.
   • Metoda powiadomień: Metoda otrzymywania powiadomień o postępie żądań asynchronicznych.
   • Preferowany protokół: To ustawienie dotyczy tylko powiadomień systemowych. Odpowiedzi używają tego samego formatu co żądania.
4. W formularzu Ustawienia hasła wprowadź hasło WAPI (dwukrotnie, aby je potwierdzić) i kliknij przycisk Ustaw.

Ustawienia zaczną obowiązywać w ciągu 30 minut.

---

Zintegruj WAPI ze swoim systemem

Aby zintegrować WAPI z systemem po jego aktywacji, należy:

• Skonfiguruj skrypt, aby połączyć się z interfejsem API
• Wyślij żądanie
• Odbieranie i przetwarzanie odpowiedzi
• Odbieranie i przetwarzanie powiadomień

Połączenie z WAPI

Aby podłączyć system do WAPI, będziesz potrzebować

• Adres e-mail logowania do systemu WEDOS i hasło WAPI
• Adres URL WAPI (zależy od formatu):
  • XML: https://api.wedos.com/wapi/xml
  • JSON: https://api.wedos.com/wapi/json

WAPI pobiera pojedynczy ciąg uwierzytelniający, który jest skrótem sha1 ciągu składającego się z nazwy użytkownika, skrótu sha1 hasła WAPI i bieżącego czasu (00-23). Strefa czasowa to Europa/Praga (UTC+1 CET lub UTC+2 CET z korektą DST). Konkretny przykład znajduje się w poniższym kodzie.

Poniższy szablon demonstruje łączenie się z WAPI za pomocą skryptu 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);
?>

Żądanie WAPI

Żądanie WAPI składa się z następujących danych:

• test: Flaga trybu testowego, opcjonalna. Jeśli w żądaniu znajduje się element testowy o wartości 1, WAPI sprawdzi tylko polecenie, ale nie wprowadzi żadnych zmian w systemie.
• użytkownik: Wymagany login do konta klienta WEDOS (e-mail).
• auth: Ciąg autoryzacji, wymagany. Jest to hash sha1 ciągu składającego się z nazwy użytkownika, hasha sha1 hasła WAPI i aktualnego czasu (00-23). Strefa czasowa to Europa/Praga (UTC+1 CET lub UTC+2 CET z korektą DST). Konkretny przykład znajduje się w poniższym kodzie.
• polecenie: Rzeczywiste żądanie WAPI. Wymagane.
• clTRID: Identyfikator żądania, opcjonalny. W tym elemencie można umieścić dowolny ciąg znaków jako identyfikator, który WAPI zwróci w odpowiedzi.
• data: Część żądania zawierająca dane. Opcjonalne.

Poniżej znajduje się szablon żądania JSON:

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

Odpowiedź WAPI

Odpowiedź składa się z następujących danych:

• code: Wartość zwracana dla danego żądania. Więcej informacji na temat tych kodów można znaleźć w dokumentacji poszczególnych poleceń.
• wynik: Opis kodu zwrotnego.
• timestamp: Czas wykonania polecenia w formacie UNIX.
• clTRID: identyfikator żądania klienta.
• svTRID: identyfikator żądania serwera.
• polecenie: Żądanie WAPI.
• data: Dane zwrotne. Brak, jeśli żądanie nie powiedzie się.
• test: Dołączone do odpowiedzi na żądania testowe.

Poniżej znajduje się szablon odpowiedzi JSON:

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

Powiadomienia

Żądania asynchroniczne nie mogą być wykonywane natychmiast. Postęp i wynik takich operacji można monitorować za pomocą powiadomień. Żądania synchroniczne nie korzystają z powiadomień.

Jeśli WAPI nie może zakończyć operacji natychmiast, zwraca w odpowiedzi żądanie oczekujące (1001). Po zakończeniu operacji (w przypadku bardziej skomplikowanych działań poszczególnych kroków) tworzy powiadomienie, które jest podobne do klasycznej odpowiedzi. Powiadomienie można dopasować do odpowiedniego żądania za pomocą parametrów clTRID lub svTRID.

Dane powiadomień są zawsze kodowane w UTF-8.

Powiadomienia można otrzymywać na następujące sposoby (zgodnie z ustawieniami):

• Korzystanie z kolejki POLL.
• Wyślij na podany adres e-mail.
• Za pośrednictwem protokołu HTTP (lub HTTPS) na adres URL podany przez użytkownika przy użyciu metody POST w parametrze żądania. Odpowiedź HTTP z kodem zwrotnym 200 jest uznawana za powodzenie. Jeśli dostarczenie nie powiedzie się, system podejmie próbę ponownego dostarczenia powiadomienia w odstępach kilkuminutowych.

Poniżej znajduje się szablon powiadomienia JSON:

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

---

Podstawowe żądania

Podstawowe żądania obejmują ping, ping-async i polecenia do pracy z kolejką POLL poll-req i poll-ack.

ping

Żądanie ping służy do testowania funkcjonalności WAPI - na przykład poświadczeń logowania, adresu IP lub kodu.

Zwracane wartości to:

• 1000 - OK

Szablon żądania JSON:

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

Szablon odpowiedzi JSON:

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

ping-async

Żądanie ping-async testuje funkcjonalność powiadomień WAPI.

Zwracane wartości to:

• 1000 - OK
• 1001 - Oczekiwanie na żądanie

Szablon żądania JSON:

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

Szablon odpowiedzi JSON:

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

Szablon powiadomienia 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 i poll-ack

Powiadomienia z kolejki POLL można otrzymywać, łącząc polecenia poll-req i poll-ack:

1. Użyj polecenia poll-req, aby pobrać najstarsze dostępne powiadomienie.
2. Polecenie poll-ack oznacza powiadomienie jako przeczytane i udostępnia nowsze, aż do wyczerpania kolejki.

Zwracane wartości dla poll-req to:

• 1000 - otrzymane powiadomienie
• 1003 - brak nieprzeczytanych powiadomień w kolejce
• 2150 - powiadomienia kolejki ankiet wyłączone dla tego konta

JSON poll-req szablon żądania:

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

JSON poll-req szablon odpowiedzi (powiadomienie dostępne):

{
  "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 szablon odpowiedzi (pusta kolejka powiadomień):

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

W żądaniu poll-ack należy uwzględnić następujące parametry:

• id - identyfikator bieżącego powiadomienia o ankiecie

Zwracane wartości dla poll-ack to:

• 1002 - powiadomienie oznaczone jako przeczytane
• 2151 - nie znaleziono powiadomienia

JSON poll-ack żądanie:

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

JSON poll-ack odpowiedź:

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

---

Rozwiązywanie typowych problemów

Typowe problemy z WAPI obejmują:

• Nieudane uwierzytelnianie żądań

---

FAQ