WAPI – Manuel

Dans cet article, vous apprendrez :

• Comment fonctionne WAPI
  • Services pris en charge
  • Restrictions des requêtes
  • Requêtes synchrones et asynchrones
  • Codes de réponse
• Comment activer WAPI dans l’administration WEDOS Global
• Comment intégrer WAPI à votre système
• Requêtes de base pour tester les fonctions de WAPI
• Résolution des problèmes courants
• Questions fréquentes

---

API WEDOS (WAPI)

L’API WEDOS, en abrégé WAPI, permet de gérer les services WEDOS directement depuis votre système à l’aide de requêtes et de réponses.

• La communication est soit synchrone (la réponse est traitée généralement en quelques secondes après la réception de la requête), soit asynchrone (certaines réponses peuvent prendre plus de temps ; le processus est suivi via des notifications).
• Les données sont transmises via le protocole HTTPS par la méthode POST dans le paramètre request ; l’encodage des données est UTF-8.
• Les formats pris en charge sont à la fois XML et JSON.

Services pris en charge

WAPI prend actuellement en charge les services WEDOS Global suivants :

• Membres WEDOS Global
• WEDOS Protection
• WEDOS DNS et NSSET

Vous pouvez également accéder aux services du bureau d’enregistrement de domaines WEDOS :

• Domaines
• Contacts de domaine
• Compte de crédit

Restrictions de WAPI

Pour éviter les abus, WAPI applique les restrictions suivantes :

• Un compte utilisateur peut envoyer au maximum 1000 requêtes par heure. Cela s’applique à tous les types de requêtes. Lorsque cette limite est atteinte, WAPI rejette les requêtes suivantes jusqu’à l’expiration du délai d’attente.
• Un compte utilisateur peut effectuer au maximum 100 requêtes de disponibilité de domaine par heure. Cela s’applique aux requêtes domain-check, domain-create et domain-transfer-check.
• Les requêtes invalides répétées (échec d’autorisation, accès depuis une adresse IP non autorisée, saisie incorrecte, paramètres manquants ou incorrects, commandes inconnues, commandes se terminant par une erreur ou toute requête dépassant les autres restrictions) entraînent le blocage de l’adresse IP pendant 1 minute pour chaque requête invalide au-delà de 10. À chaque requête invalide supplémentaire, le système augmente la durée du blocage.

Requêtes synchrones et asynchrones

La plupart des requêtes exécutées via WAPI sont synchrones : vous envoyez la requête et vous obtenez généralement le résultat en quelques secondes.

Certaines requêtes sont asynchrones : leur traitement peut prendre très longtemps (même des heures ou des jours). Dans ce cas, WAPI ne renvoie pas le résultat final, mais uniquement l’information sur la réception de la requête. Le système vous envoie ensuite des informations sur l’avancement et le résultat final sous forme de notifications.

Codes de réponse

Les codes de réponse indiquent l’état d’une réponse WAPI. Certains codes sont propres à une requête et figurent dans la documentation WAPI correspondante ; la liste ci-dessous s’applique à toutes les requêtes.

• 1000 = OK
• 2000 = Erreur d’analyse de la requête
• 2001 = Requête invalide – paramètre requis manquant : user
• 2002 = Requête invalide – paramètre requis manquant : auth
• 2003 = Requête invalide – paramètre requis manquant : command
• 2004 = Requête invalide – un seul élément data est autorisé
• 2005 = Requête invalide – le paramètre clTRID est trop long
• 2006 = Limite de requêtes dépassée
• 2007 = Requête invalide – taille maximale de la requête dépassée
• 2008 = Requête invalide – la requête est trop complexe
• 2009 = Requête invalide – la requête est vide
• 2010 = Commande inconnue
• 2011 = Commande désactivée
• 2050 = Échec de l’authentification
• 2051 = Accès non autorisé depuis cette adresse IP
• 2052 = Adresse IP temporairement bloquée en raison d’un trop grand nombre de requêtes en échec
• 2100 = Paramètre requis manquant
• 2101 = Paramètres non concordants
• 2102 = Requête invalide – encodage des données d’entrée non concordant
• 4000 = Erreur interne
• 4001 = Exception interne
• 5000 = Erreur fatale
• 5001 = Erreur d’authentification interne
• 5003 = Hors service

---

Activer WAPI

Avant de pouvoir utiliser WAPI, vous devez l’activer. Procédez comme suit :

1. Connectez-vous à l’administration WEDOS Global ⧉.
2. Dans la barre de gauche, sélectionnez WAPI.
3. Dans le formulaire Configuration WAPI , saisissez les informations suivantes et validez à l’aide du bouton Définir :
   • Adresses IP autorisées : Une liste d’adresses IP séparées par des virgules (IPv4 et IPv6, la notation CIDR est prise en charge) depuis lesquelles votre système se connecte à WAPI.
   • Mode de notification : Une méthode de réception des notifications sur l’avancement des requêtes asynchrones.
   • Protocole préféré : Ce paramètre s’applique uniquement aux notifications système. Les réponses utilisent le même format que les requêtes.
4. Dans le formulaire Paramètres du mot de passe , saisissez le mot de passe WAPI (deux fois pour le confirmer) et cliquez sur le bouton Définir .

Les paramètres prennent effet dans un délai de 30 minutes.

---

Intégrer WAPI à votre système

Pour intégrer WAPI à votre système une fois celui-ci activé, vous devez :

• Créer un script pour vous connecter à l’API
• Envoyer une requête
• Recevoir et traiter une réponse
• Recevoir et traiter une notification

Se connecter à WAPI

Pour connecter votre système à WAPI, vous aurez besoin :

• De votre e-mail de connexion WEDOS et du mot de passe WAPI
• De l’URL de WAPI (selon le format) :
  • XML : https://api.wedos.com/wapi/xml
  • JSON : https://api.wedos.com/wapi/json

WAPI prend une seule chaîne d’authentification, qui est un hachage SHA-1 d’une chaîne composée du nom d’utilisateur, du hachage SHA-1 du mot de passe WAPI et de l’heure actuelle (00-23). Le fuseau horaire est Europe/Prague (UTC+1 CET, ou UTC+2 CET avec l’ajustement de l’heure d’été). Voir le code ci-dessous pour un exemple concret.

Le modèle suivant montre la connexion à WAPI à l’aide d’un script 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);
?>

Requête WAPI

Une requête WAPI se compose des données suivantes :

• test: Indicateur du mode test, facultatif. Si vous incluez dans la requête un élément test avec la valeur 1, WAPI vérifie uniquement la commande, sans effectuer de modification dans le système.
• user: Votre identifiant de compte client WEDOS (e-mail), requis.
• auth: Chaîne d’autorisation, requise. Il s’agit d’un hachage SHA-1 d’une chaîne composée du nom d’utilisateur, du hachage SHA-1 du mot de passe WAPI et de l’heure actuelle (00-23). Le fuseau horaire est Europe/Prague (UTC+1 CET, ou UTC+2 CET avec l’heure d’été). Voir l’exemple de code ci-dessous.
• commande: La requête WAPI proprement dite. Requis.
• clTRID: Identifiant de la requête, facultatif. Vous pouvez placer dans cet élément n’importe quelle chaîne servant d’identifiant que WAPI renverra dans la réponse.
• data: La partie données de la requête. Facultatif.

Voici un modèle de requête JSON :

{
  "request":
  {
    "user": "your@login.tld",
    "auth": "auth-string",
    "command": "request-name",
    "data":
    {
      données de la requête
    }
    "clTRID": "request-id (optional)",
  }
}

Réponse WAPI

La réponse se compose des données suivantes :

• code: La valeur de retour de la requête donnée. Vous trouverez plus d’informations sur ces codes dans la section Codes de réponse et dans la documentation de la commande concernée.
• result: Description du code de retour.
• timestamp: Heure d’exécution de la commande au format UNIX.
• clTRID: Identifiant de la requête côté client.
• svTRID: Identifiant de la requête côté serveur.
• commande: Requête WAPI.
• data: Données de retour. Aucune si la requête échoue.
• test: Inclus dans les réponses aux requêtes de test.

Voici un modèle de réponse JSON :

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

Notifications

Les requêtes asynchrones ne peuvent pas être exécutées immédiatement. Vous pouvez suivre la progression et le résultat de ces opérations grâce aux notifications. Les requêtes synchrones n’utilisent pas de notifications.

Si WAPI ne peut pas terminer l’opération immédiatement, il renvoie Request pending (1001) en réponse. Une fois l’opération terminée (pour les actions plus complexes composées de plusieurs étapes), il crée une notification semblable à une réponse classique. Vous pouvez associer la notification à la requête correspondante à l’aide des paramètres clTRID ou svTRID.

Les données des notifications sont toujours encodées en UTF-8.

Vous pouvez recevoir les notifications de la manière suivante (selon les paramètres) :

• Via la file POLL.
• Envoi à une adresse e-mail spécifiée.
• Via le protocole HTTP (ou HTTPS) à l’adresse URL que vous avez indiquée, à l’aide de la méthode POST dans le paramètre request. Une réponse HTTP avec le code de retour 200 est considérée comme un succès. En cas d’échec de la remise, le système tentera de remettre la notification à nouveau à intervalles de quelques minutes.

Voici un modèle de notification JSON :

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

---

Requêtes de base

Les requêtes de base comprennent ping, ping-async, ainsi que les commandes de gestion de la file d’attente POLL poll-req et poll-ack.

ping

La requête ping permet de tester le fonctionnement de WAPI – par exemple les identifiants de connexion, l’adresse IP ou le code.

Les valeurs de retour sont :

• 1000 – OK

Modèle de requête JSON :

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

Modèle de réponse JSON :

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

ping-async

La requête ping-async teste le fonctionnement des notifications de WAPI.

Les valeurs de retour sont :

• 1000 – OK
• 1001 – En attente de la requête

Modèle de requête JSON :

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

Modèle de réponse JSON :

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

Modèle de notification 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 et poll-ack

Vous pouvez recevoir les notifications de la file POLL en combinant poll-req et poll-ack :

1. Utilisez poll-req pour télécharger la notification la plus ancienne disponible.
2. Avec la commande poll-ack , marquez la notification comme lue et rendez les plus récentes disponibles jusqu’à épuisement de la file d’attente.

Les valeurs de retour pour poll-req sont :

• 1000 – notification reçue
• 1003 – aucune notification non lue dans la file d’attente
• 2150 – notifications de la file d’attente POLL désactivées pour ce compte

JSON poll-req modèle de requête :

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

JSON poll-req modèle de réponse (notification disponible) :

{
  "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 modèle de réponse (file d’attente de notifications vide) :

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

Incluez les paramètres suivants dans la requête poll-ack :

• id – identifiant actuel de la notification poll

Les valeurs de retour pour poll-ack sont :

• 1002 – notification marquée comme lue
• 2151 – notification introuvable

JSON poll-ack :

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

JSON poll-ack réponse :

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

---

Résolution des problèmes courants

Les problèmes courants avec WAPI sont notamment :

• L’échec de l’authentification des requêtes

---

FAQ