WAPI - Handbuch

In diesem Artikel erfahren Sie mehr:

WEDOS API (WAPI)

Die WEDOS-API, kurz WAPI, wird verwendet, um WEDOS-Dienste direkt von Ihrem System aus über Anfragen und Antworten zu verwalten.

  • Die Kommunikation erfolgt entweder synchron (eine Antwort wird in der Regel innerhalb von Sekunden nach Erhalt der Anfrage verarbeitet) oder asynchron (einige Antworten können länger dauern; der Prozess wird durch Benachrichtigungen überwacht).
  • Die Daten werden über das HTTPS-Protokoll mit der POST-Methode im Anfrageparameter übergeben; die Datenkodierung ist UTF-8.
  • Zu den unterstützten Formaten gehören sowohl XML als auch JSON.

Die Nutzung von WAPI erfordert ein aktives Guthabenkonto, von dem das System die Zahlungen abbucht.

Unterstützte Dienste

WAPI unterstützt derzeit die folgenden WEDOS Global Services:

Außerdem können Sie auf die Dienste der WEDOS-Domänenregistrierungsstelle zugreifen:

WAPI-Beschränkungen

Zum Schutz vor Missbrauch gelten für WAPI die folgenden Einschränkungen:

  • Ein Benutzerkonto kann maximal 1000 Anfragen pro Stunde senden. Dies gilt für alle Arten von Anfragen. Wenn diese Grenze erreicht ist, lehnt die WAPI weitere Anfragen ab, bis die Zeitüberschreitung abgelaufen ist.
  • Ein Benutzerkonto darf maximal 100 Domainverfügbarkeitsanfragen pro Stunde stellen. Dies gilt für die Abfragen "Domain-Check", "Domain-Create" und "Domain-Transfer-Check".
  • Wiederholte ungültige Anfragen (fehlende Autorisierung, Zugriff von einer nicht autorisierten IP-Adresse, falsche Eingabe, fehlende oder falsche Parameter, unbekannte Befehle, Befehle, die zu einem Fehler führen, oder jede Anfrage, die über andere Beschränkungen hinausgeht) führt dazu, dass die IP-Adresse für jede ungültige Anfrage, die über 10 hinausgeht, für 1 Minute gesperrt wird. Mit jeder weiteren ungültigen Anfrage erhöht das System die Sperrzeit.

Synchrone und asynchrone Anforderungen

Die meisten über die WAPI ausgeführten Anfragen sind synchron - Sie senden die Anfrage und erhalten das Ergebnis in der Regel innerhalb weniger Sekunden.

Einige Anfragen sind asynchron - die Bearbeitung solcher Anfragen kann sehr lange dauern (sogar Stunden oder Tage). In solchen Fällen gibt die WAPI nicht das Endergebnis zurück, sondern nur die Information, dass die Anfrage eingegangen ist. Das System sendet Ihnen dann Informationen über den Fortschritt und das Endergebnis in Form von Benachrichtigungen.

WAPI aktivieren

Vergewissern Sie sich vor der Aktivierung von WAPI, dass Sie ein aktives WEDOS-Kreditkonto haben.

Bevor Sie WAPI verwenden können, müssen Sie es aktivieren. Gehen Sie wie folgt vor:

  1. Loggen Sie sich in das WEDOS Global Admin-Panel ein ⧉.
  2. Wählen Sie in der linken Leiste WAPI.
  3. In der WAPI-Einrichtung geben Sie Folgendes ein und bestätigen Sie mit der Satz Taste:
    • Erlaubte IPs: Eine durch Kommata getrennte Liste von IP-Adressen (sowohl IPv4 als auch IPv6), von denen aus sich Ihr System mit WAPI verbindet.
    • Benachrichtigungsmethode: Eine Methode zum Empfang von Benachrichtigungen über den Fortschritt von asynchronen Anfragen.
    • Bevorzugtes Protokoll: Diese Einstellung gilt nur für Systembenachrichtigungen. Die Antworten verwenden das gleiche Format wie die Anfragen.
  4. Geben Sie im Formular Kennworteinstellungen das WAPI-Kennwort ein (zweimal zur Bestätigung) und klicken Sie auf die Schaltfläche Setzen.
Aktivieren Sie WAPI im WEDOS Global Admin Panel
Einstellen der zulässigen IP-Adressen und eines Passworts für WAPI in WEDOS Global
Einstellen der zulässigen IP-Adressen und eines Passworts für WAPI in WEDOS Global

Die Einstellungen werden innerhalb von 30 Minuten wirksam.

Integrieren Sie WAPI in Ihr System

Um WAPI in Ihr System zu integrieren, nachdem es aktiviert wurde, müssen Sie Folgendes tun

Der folgende Text geht davon aus, dass die Daten im JSON-Format übergeben werden. Bei XML müssen Sie Ihren Code entsprechend anpassen.

Verbindung zum WAPI

Um Ihr System mit WAPI zu verbinden, benötigen Sie:

  • Ihre WEDOS-Login-E-Mail und Ihr WAPI-Passwort
  • Die WAPI-URL (je nach Format):
    • XML: https://api.wedos.com/wapi/xml
    • JSON: https://api.wedos.com/wapi/json

WAPI benötigt einen einzigen Authentifizierungsstring, der ein sha1-Hash eines Strings ist, der sich aus dem Benutzernamen, dem sha1-Hash des WAPI-Passworts und der aktuellen Uhrzeit (00-23) zusammensetzt. Die Zeitzone ist Europa/Prag (UTC+1 MEZ, oder UTC+2 MEZ mit Sommerzeitanpassung). Siehe Code unten für ein spezifisches Beispiel.

Verwenden Sie das WAPI-Passwort, um mit WAPI zu kommunizieren. Das Passwort für das Kundenkonto funktioniert nicht.

Die folgende Vorlage demonstriert die Verbindung zu WAPI mit Hilfe eines PHP-Skripts:

<?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);
?>

WAPI-Anfrage

Eine WAPI-Anfrage besteht aus den folgenden Daten:

  • test: Testmodus-Flag, optional. Wenn Sie ein Testelement mit dem Wert 1 in die Anforderung aufnehmen, prüft das WAPI den Befehl nur, nimmt aber keine Änderungen im System vor.
  • Benutzer: Ihr WEDOS-Kundenkonto-Login (E-Mail), erforderlich.
  • auth: Autorisierungszeichenfolge, erforderlich. Dies ist ein sha1-Hash einer Zeichenfolge, die sich aus dem Benutzernamen, dem sha1-Hash des WAPI-Passworts und der aktuellen Uhrzeit (00-23) zusammensetzt. Die Zeitzone ist Europa/Prag (UTC+1 MEZ, oder UTC+2 MEZ mit Sommerzeitanpassung). Siehe Code unten für ein spezifisches Beispiel.
  • Befehl: Die eigentliche WAPI-Anfrage. Erforderlich.
  • clTRID: Anfrage-ID, optional. In dieses Element kann eine beliebige Zeichenkette als Kennung eingegeben werden, die WAPI in der Antwort zurückgibt.
  • Daten: Der Datenteil der Anfrage. Optional.

Es folgt eine Vorlage für eine JSON-Anfrage:

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

WAPI-Antwort

Die Antwort besteht aus den folgenden Daten:

  • Code: Der Rückgabewert für die gegebene Anfrage. Weitere Informationen zu diesen Codes finden Sie in der Dokumentation des jeweiligen Befehls.
  • Ergebnis: Rückgabecode Beschreibung.
  • Zeitstempel: Uhrzeit der Befehlsausführung im UNIX-Format.
  • clTRID: Bezeichner der Anfrage des Kunden.
  • svTRID: Bezeichner der Anfrage des Servers.
  • Befehl: WAPI-Anfrage.
  • Daten: Rückgabedaten. Keine, wenn die Anfrage fehlschlägt.
  • Test: In den Antworten auf Testanfragen enthalten.

Es folgt eine Vorlage für eine JSON-Antwort:

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

Benachrichtigungen

Asynchrone Anfragen können nicht sofort ausgeführt werden. Sie können den Fortschritt und das Ergebnis solcher Vorgänge durch Benachrichtigungen überwachen. Synchrone Anfragen verwenden keine Benachrichtigungen.

Kann die WAPI den Vorgang nicht sofort abschließen, gibt sie als Antwort Request pending (1001) zurück. Nach Beendigung des Vorgangs (bei komplizierteren Aktionen mit einzelnen Schritten) wird eine Benachrichtigung erstellt, die einer klassischen Antwort ähnelt. Sie können die Benachrichtigung über die Parameter clTRID oder svTRID der entsprechenden Anfrage zuordnen.

Die Meldungsdaten sind immer in UTF-8 kodiert.

Sie können Benachrichtigungen auf die folgenden Arten erhalten (je nach Einstellung):

  • Verwendung der POLL-Warteschlange.
  • An die angegebene E-Mail-Adresse senden.
  • Über das HTTP- (oder HTTPS-) Protokoll an die von Ihnen angegebene URL-Adresse unter Verwendung der POST-Methode im Anfrageparameter. Eine HTTP-Antwort mit dem Rückgabewert 200 wird als Erfolg gewertet. Schlägt die Zustellung fehl, versucht das System, die Benachrichtigung in Abständen von mehreren Minuten erneut zuzustellen.

Nachfolgend finden Sie eine Vorlage für eine JSON-Meldung:

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

Grundlegende Anforderungen

Zu den grundlegenden Anfragen gehören ping, ping-async und Befehle für die Arbeit mit der POLL-Warteschlange poll-req und poll-ack.

ping

Die Ping-Anfrage wird verwendet, um die WAPI-Funktionalität zu testen, z. B. die Anmeldedaten, die IP-Adresse oder den Code.

Die Rückgabewerte sind:

  • 1000 - OK

JSON-Anfragevorlage:

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

JSON-Antwortvorlage:

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

ping-async

Die ping-async-Anforderung testet die Funktionalität von WAPI-Benachrichtigungen.

Die Rückgabewerte sind:

  • 1000 - OK
  • 1001 - Warten auf Anfrage

JSON-Anfragevorlage:

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

JSON-Antwortvorlage:

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

JSON-Benachrichtigungsvorlage:

{
  "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 und poll-ack

Sie können Benachrichtigungen aus der POLL-Warteschlange erhalten, indem Sie die Befehle poll-req und poll-ack kombinieren:

  1. Verwenden Sie den Befehl poll-req, um die älteste verfügbare Benachrichtigung herunterzuladen.
  2. Mit dem Befehl poll-ack markieren Sie die Meldung als gelesen und stellen neue Meldungen bereit, bis die Warteschlange erschöpft ist.

Die Rückgabewerte für poll-req sind:

  • 1000 - Benachrichtigung erhalten
  • 1003 - keine ungelesene Benachrichtigung in der Warteschlange
  • 2150 - Benachrichtigungen über Warteschlangenabrufe für dieses Konto deaktiviert

JSON poll-req Vorlage anfordern:

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

JSON poll-req Antwortvorlage (Benachrichtigung verfügbar):

{
  "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 Antwortvorlage (leere Benachrichtigungswarteschlange):

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

Fügen Sie die folgenden Parameter in die Poll-ack-Anfrage ein:

  • id - aktuelle ID der Abrufbenachrichtigung

Die Rückgabewerte für poll-ack sind:

  • 1002 - Meldung als gelesen markiert
  • 2151 - Meldung nicht gefunden

JSON poll-ack Anfrage:

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

JSON poll-ack Antwort:

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

Fehlersuche bei allgemeinen Problemen

Zu den häufigsten Problemen mit WAPI gehören:

Authentifizierung der Anfrage fehlgeschlagen

Problem: Ich erhalte keine Antworten auf meine Anfragen.

Die Ursache: In der Regel handelt es sich um einen Authentifizierungsfehler, vor allem, wenn er weiterhin auftritt.

Lösung: Überprüfen Sie den WEDOS-Status ⧉ auf Unterbrechungen.

Stellen Sie das sicher:

  • Die IP-Adresse Ihres Systems ist unter den erlaubten IPs im Admin-Panel aufgeführt (wie im Kapitel WAPI aktivieren beschrieben).
  • Ihr Skript verwendet das WAPI-Passwort und nicht Ihr WEDOS-Anmeldepasswort.
  • Ihr Skript verwendet die Zeitzone Europa/Prag und die Zeit wird korrekt synchronisiert.

FAQ

Kann ich bei der Aktivierung von WAPI über WEDOS Global auch andere WAPI-Anfragen verwenden?

Ja, unabhängig davon, in welchem Verwaltungsbereich Sie WAPI aktiviert haben, können Sie alle Anfragen in Ihrem System verwenden.

War dies hilfreich?

Vielen Dank für Ihr Feedback!
Allgemeine Selektoren
Nur exakte Treffer
Suche im Titel
Suche im Inhalt
Post Type Selectors
Artikel TOC
Kategorien durchsuchen