WAPI – Manual

In this article, you will learn:

• How WAPI works
  • Supported services
  • Request restrictions
  • Synchronous and asynchronous requests
  • Response codes
• How to activate WAPI in the WEDOS Global admin panel
• How to integrate WAPI to your system
• Basic requests to test WAPI features
• Troubleshooting common issues
• Frequently asked questions

---

WEDOS API (WAPI)

The WEDOS API, WAPI for short, is used to manage WEDOS services directly from your system via requests and responses.

• Communication is either synchronous (una risposta viene elaborata di norma entro pochi secondi dalla ricezione della richiesta) oppure asynchronous (alcune risposte possono richiedere più tempo; il processo viene monitorato tramite notifiche).
• Data is passed via the HTTPS protocol by the POST method in the request parameter; data encoding is UTF-8.
• Supported formats include both XML and JSON.

Supported Services

WAPI currently supports the following WEDOS Global services:

• WEDOS Global Members
• WEDOS Protection
• WEDOS DNS and NSSET

Additionally, you can access WEDOS domain registrar services:

• Domains
• Domain contacts
• Credit account

WAPI Restrictions

To protect against misuse, WAPI applies the following restrictions:

• One user account can send a maximum of 1000 requests per hour. This applies to all types of requests. When this limit is reached, WAPI rejects further requests until the timeout expires.
• One user account is allowed to make a maximum of 100 domain availability requests per hour. This applies to the domain-check, domain-create and domain-transfer-check requests.
• Repeated invalid requests (errore di autorizzazione, accesso da un indirizzo IP non autorizzato, input errato, parametri mancanti o errati, comandi sconosciuti, comandi che generano un errore o qualsiasi richiesta che superi gli altri limiti) comporterà il blocco dell’indirizzo IP per 1 minuto per ogni richiesta non valida oltre le 10. Con ogni ulteriore richiesta non valida il sistema aumenta la durata del blocco.

Synchronous and asynchronous requests

Most of the requests executed via WAPI are synchronous – you send the request and you usually get the result within a few seconds.

Some requests are asynchronous – processing such requests can take a very long time (even hours or days). In such cases, WAPI doesn’t return the final result, but only information about receiving the request. The system then sends you information about the progress and the final result in the form of notifications.

Response codes

Response codes indicate the status of a WAPI response. Some codes are request-specific and can be found in the corresponding WAPI documentation; the list below applies to all requests.

• 1000 = OK
• 2000 = Errore di analisi della richiesta
• 2001 = Richiesta non valida – parametro obbligatorio mancante: user
• 2002 = Richiesta non valida – parametro obbligatorio mancante: auth
• 2003 = Richiesta non valida – parametro obbligatorio mancante: command
• 2004 = Richiesta non valida – è consentito un solo elemento di dati
• 2005 = Richiesta non valida – il parametro clTRID è troppo lungo
• 2006 = Limite di richieste superato
• 2007 = Richiesta non valida – dimensione massima della richiesta superata
• 2008 = Richiesta non valida – la richiesta è troppo complessa
• 2009 = Richiesta non valida – la richiesta è vuota
• 2010 = Comando sconosciuto
• 2011 = Comando disattivato
• 2050 = Autenticazione non riuscita
• 2051 = Accesso non consentito da questo indirizzo IP
• 2052 = Indirizzo IP temporaneamente bloccato per troppe richieste non riuscite
• 2100 = Parametro obbligatorio mancante
• 2101 = Parametri non corrispondenti
• 2102 = Richiesta non valida – codifica dei dati di input non corrispondente
• 4000 = Errore interno
• 4001 = Eccezione interna
• 5000 = Errore fatale
• 5001 = Errore di autenticazione interno
• 5003 = Fuori servizio

---

Activate WAPI

Prima di iniziare a usare WAPI, devi attivarla. Segui questi passaggi:

1. Log into the WEDOS Global admin panel ⧉.
2. In the left bar, select WAPI.
3. In the WAPI Setup form, enter the following and confirm using the Set button:
   • Allowed IPs: A comma-separated list of IP addresses (both IPv4 and IPv6, supports CIDR notation) from which your system connects to WAPI.
   • Notification Mode: Un metodo per ricevere notifiche sull’avanzamento delle richieste asincrone.
   • Preferred Protocol: This setting only applies to system notifications. Responses use the same format as requests.
4. In the Password Settings form, enter the WAPI password (twice to confirm it) and click the Set button.

The settings will take effect within 30 minutes.

---

Integrate WAPI into Your System

To integrate WAPI into your system once it’s been activated, you need to:

• Set up a script to connect to the API
• Send a request
• Receive and process a response
• Receive and process a notification

Connect to WAPI

To connect your system to WAPI, you will need:

• Your WEDOS login email and WAPI password
• The WAPI URL (depends on format):
  • XML: https://api.wedos.com/wapi/xml
  • JSON: https://api.wedos.com/wapi/json

WAPI takes a single authentication string, which is a SHA-1 hash of a string composed of the username, the SHA-1 hash of the WAPI password and the current time (00-23). The time zone is Europe/Prague (UTC+1 CET, or UTC+2 CET with DST adjustment). See code below for a specific example.

The following template demonstrates connecting to WAPI using a PHP script:

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

WAPI Request

Una richiesta WAPI è composta dai seguenti dati:

• test: Flag della modalità di test, facoltativo. Se includi nella richiesta un elemento test con valore 1, WAPI verificherà solo il comando, senza apportare alcuna modifica al sistema.
• user: Il login del tuo account cliente WEDOS (e-mail), obbligatorio.
• auth: Stringa di autorizzazione, obbligatoria. È un hash SHA-1 di una stringa composta da nome utente, hash SHA-1 della password WAPI e ora corrente (00-23). Il fuso orario è Europe/Prague (UTC+1 CET oppure UTC+2 CEST con l’ora legale). Nel codice qui sotto trovi un esempio concreto.
• command: La richiesta WAPI vera e propria. Obbligatoria.
• clTRID: ID della richiesta, facoltativo. In questo elemento puoi inserire una stringa qualsiasi come identificatore che WAPI restituirà nella risposta.
• data: La parte dati della richiesta. Facoltativa.

The following is a template JSON request:

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

WAPI Response

The response consists of the following data:

• code: Il valore di ritorno della richiesta data. Per ulteriori informazioni su questi codici consulta Response codes section and specific command documentation.
• result: Descrizione del codice di ritorno.
• timestamp: Ora di esecuzione del comando in formato UNIX.
• clTRID: Identificatore della richiesta del client.
• svTRID: Identificatore della richiesta del server.
• command: Richiesta WAPI.
• data: Dati restituiti. Nessuno se la richiesta non riesce.
• test: Incluso nelle risposte alle richieste di test.

The following is a template JSON response:

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

Notifications

Asynchronous requests cannot be performed immediately. You can monitor the progress and result of such operations through notifications. Synchronous requests do not use notifications.

If WAPI cannot complete the operation immediately, it returns Request pending (1001) in response. After the operation is completed (for more complicated actions of individual steps), it creates a notification that is similar to a classic response. You can match the notification to the corresponding request using the clTRID or svTRID parameters.

Notification data is always encoded in UTF-8.

You can receive notifications in the following ways (according to the settings):

• Using the POLL queue.
• Send to specified email address.
• Via HTTP (or HTTPS) protocol to the URL address specified by you using the POST method in the request parameter. An HTTP response with a return code of 200 is considered a success. If delivery fails, the system will attempt to deliver the notification againat several-minute intervals.

The following is a template JSON notification:

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

---

Basic Requests

Basic requests include ping, ping-async, e i comandi per lavorare con la coda POLL poll-req and poll-ack.

ping

The ping request is used to test WAPI functionality – for example, login credentials, IP address or code.

The return values are:

• 1000 – OK

JSON request template:

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

JSON response template:

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

ping-async

The ping-async request tests the functionality of WAPI notifications.

The return values are:

• 1000 – OK
• 1001 – In attesa della richiesta

JSON request template:

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

JSON response template:

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

JSON notification template:

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

You can receive notifications from the POLL queue by combining poll-req and poll-ack commands:

1. Use the poll-req command to download the oldest available notification.
2. With the poll-ack command, mark the notification as read and make newer ones available until the queue is exhausted.

The return values for poll-req are:

• 1000 – notifica ricevuta
• 1003 – nessuna notifica non letta in coda
• 2150 – notifiche della coda poll disabilitate per questo account

JSON poll-req request template:

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

JSON poll-req response template (notification available):

{
  "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 response template (empty notification queue):

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

Include the following parameters in the poll-ack request:

• id – current poll notification ID

The return values for poll-ack are:

• 1002 – notifica contrassegnata come letta
• 2151 – notifica non trovata

JSON poll-ack request:

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

JSON poll-ack response:

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

---

Troubleshooting Common Issues

Common issues with WAPI include:

• Failing to authenticate requests

---

FAQ

Questo articolo le è stato utile?

Il suo giudizio ci aiuta a migliorare i nostri articoli.

SìNo

Desidera scriverci qualcosa su questo articolo? (facoltativo)

Il suo messaggio viene letto dal team della documentazione, che però non risponde. Se ha bisogno di aiuto, contattici tramite il modulo di contatto. Non inserisca password né dati personali.

Lasci vuoto questo campo