WAPI – Podręcznik

W tym artykule dowiesz się:

• Jak działa WAPI
  • Obsługiwane usługi
  • Ograniczenia żądań
  • Żądania synchroniczne i asynchroniczne
  • Kody odpowiedzi
• Jak aktywować WAPI w panelu administracyjnym WEDOS Global
• Jak zintegrować WAPI z własnym systemem
• Podstawowe żądania do testowania funkcji WAPI
• Rozwiązywanie typowych problemów
• Najczęściej zadawane pytania

---

WEDOS API (WAPI)

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

• Komunikacja jest albo synchroniczne (odpowiedź jest zwykle przetwarzana w ciągu kilku sekund od otrzymania żądania) lub asynchroniczne (niektóre odpowiedzi mogą trwać dłużej; proces jest monitorowany za pomocą powiadomień).
• Dane są przekazywane przez HTTPS protokół przez POST metodę w parametrze żądania; kodowanie danych to UTF-8.
• Obsługiwane formaty to zarówno XML i JSON.

Obsługiwane usługi

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

• Członkowie WEDOS Global
• WEDOS Protection
• WEDOS DNS i NSSET

Dodatkowo masz dostęp do usług rejestratora domen WEDOS:

• Domeny
• Kontakty domenowe
• Konto kredytowe

Ograniczenia WAPI

Aby zapobiec nadużyciom, 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 aż do upływu czasu oczekiwania.
• Jedno konto użytkownika może wykonać maksymalnie 100 zapytań o dostępność domen na godzinę. Dotyczy to żądań domain-check, domain-create i domain-transfer-check.
• 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 powodujące jakikolwiek błąd lub jakiekolwiek żądanie wykraczające poza inne ograniczenia) spowoduje zablokowanie adresu IP na 1 minutę za każde nieprawidłowe żądanie powyżej 10. Z każdym kolejnym nieprawidłowym żądaniem system wydłuża czas blokady.

Żądania synchroniczne i asynchroniczne

Większość żądań wykonywanych przez WAPI jest synchroniczna – wysyłasz żądanie i zwykle otrzymujesz wynik w ciągu kilku sekund.

Niektóre żądania są asynchroniczne – ich przetworzenie może trwać bardzo długo (nawet godziny lub dni). W takich przypadkach WAPI nie zwraca ostatecznego wyniku, a jedynie informację o przyjęciu żądania. System następnie przesyła informacje o postępie i o wyniku końcowym w postaci powiadomienia.

Kody odpowiedzi

Kody odpowiedzi wskazują status odpowiedzi WAPI. Niektóre kody są specyficzne dla danego żądania i znajdziesz je w odpowiedniej dokumentacji WAPI; poniższa lista dotyczy wszystkich żądań.

• 1000 = OK
• 2000 = Błąd analizy żądania
• 2001 = Nieprawidłowe żądanie – brak wymaganego parametru: user
• 2002 = Nieprawidłowe żądanie – brak wymaganego parametru: auth
• 2003 = Nieprawidłowe żądanie – brak wymaganego parametru: command
• 2004 = Nieprawidłowe żądanie – dozwolony jest tylko jeden element data
• 2005 = Nieprawidłowe żądanie – parametr clTRID jest zbyt długi
• 2006 = Przekroczono limit żądań
• 2007 = Nieprawidłowe żądanie – przekroczono maksymalny rozmiar żądania
• 2008 = Nieprawidłowe żądanie – żądanie jest zbyt złożone
• 2009 = Nieprawidłowe żądanie – żądanie jest puste
• 2010 = Nieznane polecenie
• 2011 = Polecenie wyłączone
• 2050 = Błąd uwierzytelnienia
• 2051 = Dostęp z tego adresu IP jest niedozwolony
• 2052 = Adres IP tymczasowo zablokowany z powodu zbyt wielu nieudanych żądań
• 2100 = Brak wymaganego parametru
• 2101 = Niezgodność parametrów
• 2102 = Nieprawidłowe żądanie – niezgodne kodowanie danych wejściowych
• 4000 = Błąd wewnętrzny
• 4001 = Wyjątek wewnętrzny
• 5000 = Błąd krytyczny
• 5001 = Wewnętrzny błąd uwierzytelnienia
• 5003 = Usługa niedostępna

---

Aktywuj WAPI

Zanim zaczniesz korzystać z WAPI, musisz je aktywować. Wykonaj następujące kroki:

1. Zaloguj się do Panel administracyjny WEDOS Global ⧉.
2. W lewym pasku wybierz WAPI.
3. W Konfiguracja WAPI wpisz następujące dane i potwierdź za pomocą Ustaw przycisk:
   • Dozwolone IP: Lista adresów IP (zarówno IPv4, jak i IPv6) oddzielonych przecinkami, z których Twój system łączy się z WAPI.
   • Tryb powiadomień: Sposób odbierania powiadomień o postępie żądań asynchronicznych.
   • Preferowany protokół: To ustawienie dotyczy wyłącznie powiadomień systemowych. Odpowiedzi mają ten sam format co żądania.
4. W Ustawienia hasła wpisz hasło WAPI (dwukrotnie, aby je potwierdzić) i kliknij Ustaw przycisk.

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

---

Integracja WAPI z Twoim systemem

Aby zintegrować WAPI ze swoim systemem po jego aktywacji, musisz:

• Przygotuj skrypt do połączenia z API
• Wyślij żądanie
• Odbiór i przetworzenie odpowiedzi
• Odbiór i przetworzenie powiadomienia

Połącz się z WAPI

Aby podłączyć swój system do WAPI, będziesz potrzebować:

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

WAPI przyjmuje pojedynczy ciąg uwierzytelniający, będący skrótem SHA-1 ciągu złożonego z nazwy użytkownika, skrótu SHA-1 hasła WAPI oraz bieżącej godziny (00-23). Strefa czasowa to Europe/Prague (UTC+1 CET lub UTC+2 CET z uwzględnieniem czasu letniego). Konkretny przykład znajdziesz w kodzie poniżej.

Poniższy szablon pokazuje połączenie 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=' . 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);
?>

Żądanie WAPI

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

• test: Flaga trybu testowego, opcjonalna. Jeśli w żądaniu umieścisz element test o wartości 1, WAPI tylko sprawdzi polecenie, ale nie wprowadzi żadnych zmian w systemie.
• użytkownik: Login (e-mail) Twojego konta klienta WEDOS, wymagany.
• auth: Ciąg autoryzacyjny, wymagany. Jest to hash SHA-1 ciągu złożonego z nazwy użytkownika, hasha SHA-1 hasła WAPI i aktualnej godziny (00-23). Strefa czasowa to Europe/Prague (UTC+1 CET lub UTC+2 CET z uwzględnieniem czasu letniego). Konkretny przykład znajdziesz w kodzie poniżej.
• polecenie: Właściwe żądanie WAPI. Wymagane.
• clTRID: Identyfikator żądania, opcjonalny. W tym elemencie możesz podać dowolny ciąg jako identyfikator, który WAPI zwróci w odpowiedzi.
• dane: Część danych żądania. Opcjonalna.

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:

• kod: Wartość zwrotna dla danego żądania. Więcej informacji o tych kodach znajdziesz w Kody odpowiedzi sekcji oraz dokumentacji konkretnego polecenia.
• wynik: Opis kodu zwrotnego.
• timestamp: Czas wykonania polecenia w formacie UNIX.
• clTRID: Identyfikator żądania klienta.
• svTRID: Identyfikator żądania serwera.
• polecenie: Żądanie WAPI.
• dane: Dane zwrotne. Brak, jeśli żądanie się nie powiedzie.
• test: Dołączane 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ć wykonane natychmiast. Postęp i wynik takich operacji możesz śledzić za pomocą powiadomień. Żądania synchroniczne nie używają powiadomień.

Jeśli WAPI nie może wykonać operacji natychmiast, zwraca w odpowiedzi Request pending (1001). Po zakończeniu operacji (w przypadku bardziej złożonych działań wieloetapowych) tworzy powiadomienie podobne do klasycznej odpowiedzi. Powiadomienie możesz przypisać do odpowiedniego żądania za pomocą parametrów clTRID lub svTRID.

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

Powiadomienia możesz otrzymywać w następujący sposób (zgodnie z ustawieniami):

• Korzystanie z kolejki POLL.
• Wyślij na podany adres e-mail.
• Przez protokół HTTP (lub HTTPS) na wskazany przez Ciebie adres URL metodą POST w parametrze request. Za sukces uznawana jest odpowiedź HTTP z kodem zwrotnym 200. Jeśli dostarczenie się nie powiedzie, system będzie próbował dostarczyć powiadomienie ponownie w kilkuminutowych odstępach.

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

---

Żądania podstawowe

Żądania podstawowe obejmują ping, ping-async, oraz polecenia do pracy z kolejką POLL poll-req i poll-ack.

ping

Ten ping żądanie służy do testowania działania WAPI – na przykład danych logowania, adresu IP lub kodu.

Wartości zwrotne 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

Ten ping-async żądanie testuje działanie powiadomień WAPI.

Wartości zwrotne to:

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

Szablon żądania JSON:

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

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żesz odbierać, łącząc poll-req i poll-ack polecenia:

1. Użyj poll-req polecenia, aby pobrać najstarsze dostępne powiadomienie.
2. Za pomocą poll-ack polecenia oznacz powiadomienie jako przeczytane i udostępnij nowsze, aż kolejka zostanie wyczerpana.

Wartości zwrotne dla poll-req to:

• 1000 – powiadomienie odebrane
• 1003 – brak nieprzeczytanych powiadomień w kolejce
• 2150 – pobieranie powiadomień z kolejki jest 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 (dostępne powiadomienie):

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

Uwzględnij następujące parametry w poll-ack żądanie:

• id – ID bieżącego powiadomienia poll

Wartości zwrotne 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 to:

• Brak uwierzytelnienia żądań

---

FAQ