Administration clientAdministration
Base de connaissances›Autres services›Manuel

WAPI – Manuel

Sur cette pageWEDOS APIActivation de WAPI dans l'administration clientCommunication et authentificationCommandes de baseListe des codes de retourGlossaire

Dans cet article, vous découvrirez :

WEDOS API

WEDOS API, c’est-à-dire WAPI, sert à piloter les services directement depuis votre système d’information. 

La condition préalable à l’utilisation de l’interface est l’usage d’un compte de crédit WEDOS, sur lequel le système prélève les paiements des enregistrements, renouvellements, transferts et autres frais facturés.

WAPI permet actuellement de gérer :

Limitations de WAPI

Pour se protéger contre les abus, WAPI applique les limitations suivantes :

  • Un même compte utilisateur peut envoyer au maximum 1000 requêtes par heure. Cela concerne toutes les requêtes de tous types ; lorsque cette limite est atteinte, WAPI refuse les requêtes suivantes jusqu’à l’expiration du délai.
  • Un même compte utilisateur peut soumettre au maximum 100 requêtes de disponibilité de domaine par heure. Cela concerne les commandes domain-check, domain-create et domain-transfer-check.
  • L’envoi répété de requêtes non valides (échec d’autorisation, accès depuis une adresse IP non autorisée, entrée erronée, paramètres manquants ou incorrects, commande inconnue, commandes se terminant par une erreur quelconque ou toute requête dépassant le cadre des autres limitations) entraîne, au-delà de 10 requêtes non valides, le blocage de l’adresse IP pendant 1 minute par requête non valide. À chaque nouvelle requête erronée, le système allonge la durée du blocage.

Opérations synchrones et asynchrones

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

Certaines opérations sont asynchrones : le traitement d’une telle commande peut prendre très longtemps (plusieurs heures, voire plusieurs jours). WAPI ne renvoie donc pas le résultat final, mais uniquement une confirmation de réception de la commande. Le système vous envoie ensuite des informations sur l’avancement et le résultat final sous forme de notifications.

Journalisation

Vous trouverez le journal des requêtes dans l’administration client en suivant ces étapes :

  1. Connectez-vous à l’administration client ⧉.
  2. Dans le menu du haut, sélectionnez My Account Customer.
  3. Dans le menu de gauche, sélectionnez WAPI queries.
Ouvrir l’aperçu des requêtes WAPI

Activation de WAPI dans l’administration client

Avant de commencer à utiliser WAPI, activez-le dans l’administration client en suivant ces étapes :

  1. Connectez-vous à l’administration client ⧉.
  2. Dans le menu du haut, sélectionnez My Account Customer.
  3. Dans le menu de gauche, sélectionnez WAPI interface.
  4. Définissez les adresses IP autorisées (IPv4 ou IPv6, CIDR pris en charge), le mode de notification, le protocole préféré et le mot de passe.
  5. Confirmez les paramètres en cliquant sur Set.
Ouvrir les paramètres WAPI
Exemple d'activation de WAPI
Exemple d’activation de WAPI

Tous les paramètres saisis lors de l’activation peuvent être modifiés ultérieurement de la même manière. En supprimant le contenu du champ Allowed IP addresses vous désactivez WAPI.

Communication et authentification

La communication avec l’interface WAPI s’effectue via le protocole HTTPS. Les données sont transmises par la méthode POST dans le paramètre request au format XML ou JSON. La forme de base de la commande et de la réponse est la même pour toutes les commandes. L’encodage des données est UTF-8.

URL de l’interface :

  • XML : https://api.wedos.com/wapi/xml
  • JSON : https://api.wedos.com/wapi/json

Structure de la requête

La requête se compose des données suivantes :

  • user: Nom d’utilisateur (e-mail) de votre compte client, paramètre obligatoire.
  • auth: Chaîne d’autorisation, paramètre obligatoire. Il s’agit du hash sha1 d’une chaîne composée du nom d’utilisateur, du hash sha1 du mot de passe WAPI et de l’heure actuelle (00-23). Le fuseau horaire est Europe/Prague (heure d’hiver UTC+1 CET, heure d’été UTC+2 CEST). Voir l’exemple concret dans le code ci-dessous.
  • command: La commande WAPI elle-même. Paramètre obligatoire.
  • clTRID: ID de la requête, paramètre facultatif. Vous pouvez insérer dans cet élément n’importe quelle chaîne comme identifiant, que WAPI renverra dans la réponse.
  • data: Partie données de la commande. Paramètre facultatif.
  • test: Indicateur du mode test, paramètre facultatif. Si vous insérez dans la commande l’élément test avec la valeur 1, WAPI se contentera de vérifier votre commande sans effectuer aucune modification.

Lors de la communication avec WAPI, indiquez le mot de passe WAPI. Le mot de passe du compte client ne fonctionne pas.

Le modèle de requête (JSON) est donc :

{
  "request":
  {
    "user": "votre@login.tld",
    "auth": "chaîne d'autorisation",
    "command": "nom de la requête",
    "data":
    {
      données de la requête
    }
    "clTRID": "identifiant de la requête (facultatif)",
    "test": "1 (si vous souhaitez uniquement tester la requête, facultatif)"
  }
}

Un exemple complet d’utilisation en PHP (format de données JSON) peut donc être :

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'votre@login.tld'; 
$wpass = 'votre mot de passe WAPI'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'nom de la requête',
  'data' => ['tableau de données de la requête'],
  'clTRID' => 'identifiant de la requête (facultatif)',
  'test' => '1 (si vous souhaitez uniquement tester la requête)'
  ]
];

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

Structure de la réponse

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

  • code: Valeur de retour de la commande. Vous trouverez plus d’informations dans le chapitre Codes de retour.
  • result: Description textuelle du code de retour.
  • timestamp: Heure d’exécution de la commande au format UNIX.
  • clTRID: Identifiant de la commande côté client.
  • svTRID: Identifiant de la commande côté serveur.
  • command: Commande WAPI.
  • data: Valeurs de retour. Si la commande échoue, aucune donnée n’est renvoyée.
  • test: Inséré dans la réponse aux commandes contenant également cet indicateur.

Voici un exemple de réponse au format JSON :

{
  "response":
  {
    "code": "1000",
    "result": "ok",
    "timestamp": "1286356644",
    "svTRID": "1286356644.0246.21616",
    "command": "domain-create",
    "data": 		
    {
      "num": "1311000863",
      "expiration": "2011-10-06"
    },
    "test": "1"
  }
}

Stránkování a hledání v seznamech

Seznamové příkazy domains-list et les dns-rows-list mají nepovinné parametry pro hledání a stránkování. Když je nezadáte, WAPI vrátí odpověď stejně jako dosud, tedy celý seznam.

Parametry v části data požadavku:

  • search: Hledaný text, bez rozlišení velikosti písmen. U domains-list se hledá v názvu domény, u dns-rows-list v názvu nebo datech záznamu.
  • page: Číslo stránky od 1. Výchozí hodnota je 1.
  • page_limit: Počet položek na stránku, nejvýše 1000 (větší hodnotu WAPI sníží na 1000). Když ho nezadáte nebo zadáte 0, WAPI vrátí všechny položky.

Commande dns-rows-list má navíc tyto filtry:

  • row_name: Přesný název záznamu. Hodnota @ znamená záznam přímo na doméně.
  • rdtype: Typ záznamu (A, AAAA, MX, TXT…), na velikosti písmen nezáleží.

Když zadáte kterýkoli z těchto parametrů, WAPI vrátí seznam jako pole (u domains-list v položce domain, u dns-rows-list v položce row) a v části data odpovědi doplní:

  • total: Celkový počet položek po použití filtrů.
  • page: Číslo vrácené stránky.
  • page_limit: Použitý počet položek na stránku (0 znamená všechny).

Na co dát pozor:

  • Stránka za koncem seznamu vrátí prázdný seznam s položkou total, ne chybu.
  • Neplatnou hodnotu page ou page_limit (text, záporné číslo) WAPI neodmítne, ale nahradí ji výchozí hodnotou: page 1, page_limit 0, tedy všechny položky.
  • Pole místo hodnoty v page ou page_limit vrátí chybu 2101.
  • Commande dns-domains-list vrací total (jako řetězec), page et les page_limit vždy. Když page_limit nezadáte nebo zadáte 0, použije 1000.

Commande JSON domains-list (aktivní domény obsahující „example“, první stránka po dvou doménách), podrobný popis v dokumentaci příkazu domains-list ⧉:

{
  "request": {
    "user": "votre@login.tld",
    "auth": "chaîne d'autorisation générée",
    "command": "domains-list",
    "clTRID": "votre code d'identification",
    "data": {
      "status": "active",
      "search": "example",
      "page": 1,
      "page_limit": 2
    }
  }
}

Commande JSON dns-rows-list (záznamy typu A domény example.cz, první stránka po 50 záznamech), podrobný popis v dokumentaci příkazu dns-rows-list ⧉:

{
  "request": {
    "user": "votre@login.tld",
    "auth": "chaîne d'autorisation générée",
    "command": "dns-rows-list",
    "clTRID": "votre code d'identification",
    "data": {
      "domain": "example.cz",
      "rdtype": "A",
      "page": 1,
      "page_limit": 50
    }
  }
}

Notification

Les opérations asynchrones ne peuvent pas être exécutées immédiatement. Vous pouvez suivre le déroulement 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, elle renvoie dans la réponse Request pending (1001). Une fois l’opération terminée (pour les actions plus complexes, à chaque étape), elle crée une notification, équivalente à une réponse classique. Vous pouvez associer la notification à la requête correspondante grâce aux paramètres clTRID ou svTRID.

Les données de notification sont toujours encodées en UTF-8.

Vous pouvez recevoir les notifications de l’une des manières suivantes (selon les paramètres définis lors de l’activation) :

  • Via la file POLL.
  • Par envoi à l’adresse e-mail indiquée.
  • Via le protocole HTTP (ou HTTPS) vers l’URL que vous avez définie, par la méthode POST dans le paramètre request. Une réponse HTTP avec le code de retour 200 est considérée comme une livraison correcte. Si la livraison échoue, notre système retentera de livrer la notification à intervalles de quelques minutes.

Voici un exemple de notification au format JSON :

{
  "notify": {
    "code": 1000,
    "result": "OK",
    "timestamp": 1286957932,
    "clTRID": "AvrX87Kqk6h3",
    "svTRID": "1286957874.1271.15706",
    "command": "ping-async",
    "ID": 2691
  }
}

Notifications système

Les notifications système envoient des informations sur des événements pertinents, actuellement uniquement sur le transfert d’un domaine vers un autre prestataire. Si WAPI est activé sur votre compte, le système envoie ces informations par notification, de façon similaire à une commande asynchrone.

Définissez le protocole dans lequel WAPI envoie les notifications système en suivant le chapitre Activation de WAPI dans l’administration client. Cette option s’applique aux notifications envoyées par e-mail ou à une URL. En cas de récupération depuis la file POLL, la réponse a la même forme que la commande.

La structure est la même que pour la notification classique, la commande (command) est toujours system-notify. Dans le nœud data vous trouverez des informations plus détaillées.

Commandes de base

Les commandes de base sont ping, ping-async et les commandes pour travailler avec la file POLL poll-req et poll-ack.

ping

La commande ping sert à tester le bon fonctionnement de WAPI, par exemple les identifiants de connexion, l’adresse IP ou le code.

Les valeurs de retour sont :

  • 1000 – OK

Commande JSON :

{
  "request": {
    "user": "votre@login.tld",
    "auth": "chaîne d'autorisation générée",
    "command": "ping",
    "clTRID": "votre code d'identification"
  }
}

Réponse JSON :

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "heure UTC",
    "clTRID": "votre code d'identification",
    "svTRID": "code d'identification du serveur",
    "command": "ping"
  }
}

ping-async

La commande ping-async teste le fonctionnement des notifications WAPI.

Les valeurs de retour sont :

  • 1000 OK
  • 1001 Commande en attente

Commande JSON :

{
  "request": {
    "user": "votre@login.tld",
    "auth": "chaîne d'autorisation générée",
    "command": "ping",
    "clTRID": "votre code d'identification"
  }
}

Réponse JSON :

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "heure UTC",
    "clTRID": "votre code d'identification",
    "svTRID": "code d'identification du serveur",
    "command": "ping"
  }
}

Notification JSON :

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "heure UTC",
    "clTRID": "votre code d'identification",
    "svTRID": "code d'identification du serveur",
    "command": "ping-async",
    "id": "id pour la file POLL",
    "data": {
      "round": "numéro de la tentative",
      "time": "heure",
      "done": 1
    }
  }
}

poll-req et poll-ack

Vous récupérez les notifications de la file POLL en combinant les commandes poll-req et poll-ack : 

  1. La commande poll-req télécharge la plus ancienne notification disponible.
  2. La commande poll-ack marque la notification comme reçue et rend ainsi accessibles les plus récentes, jusqu’à épuisement de la file.

Les valeurs de retour pour poll-req sont :

  • 1000 – notification obtenue
  • 1003 – aucune notification non lue dans la file
  • 2150 – le téléchargement des notifications depuis la file POLL n’est pas activé pour votre compte

Commande JSON poll-req:

{
  "request": {
    "user": "votre@login.tld",
    "auth": "chaîne d'autorisation générée",
    "command": "poll-req",
    "clTRID": "votre code d'identification"
  }
}

Réponse JSON à poll-req (notification disponible) :

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "heure UTC",
    "clTRID": "votre code d'identification",
    "svTRID": "code d'identification du serveur",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "heure UTC",
        "clTRID": "code d'identification propre de la commande trouvée",
        "svTRID": "code d'identification du serveur pour la commande trouvée",
        "command": "nom de la commande",
        "id": "id dans la file POLL"
      }
    }
  }
}

Réponse JSON à poll-req (file de notifications vide) :

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": “1286962852”,
    "clTRID": "votre code d'identification",
    "svTRID": "code d'identification du serveur",
    "command": "poll-req"
  }
}

Pour la commande poll-ack, vous indiquez les données (paramètres) suivantes :

  • id – ID de la notification POLL actuelle

Les valeurs de retour pour poll-ack sont :

  • 1002 – notification marquée comme reçue
  • 2151 – notification introuvable

Commande JSON poll-ack:

{
  "request": {
    "user": "votre@login.tld",
    "auth": "chaîne d'autorisation générée",
    "command": "poll-ack",
    "clTRID": "votre code d'identification",
    "data": {
      "id": “ID de la notification POLL reçue”
    }
  }
}

Réponse JSON à poll-ack:

{
  "response": {
    "code": “1002”,
    "result": "Notification acquired",
    "timestamp": "heure UTC",
    "clTRID": "votre code d'identification",
    "svTRID": "code d'identification du serveur",
    "command": "poll-ack"
  }
}

Les codes de retour dans les réponses et les notifications vous aident à identifier le déroulement et les éventuelles erreurs de WAPI.

Répartition de base des codes de retour :

  • 1xxx – la commande s’est déroulée correctement.
  • 2xxx – commande incorrecte (par exemple champs d’entrée manquants, format ou valeur incorrects).
  • 3xxx – erreur de l’objet cible – l’action demandée ne peut pas être effectuée, l’objet n’est pas dans l’état approprié (par exemple lors d’une tentative d’enregistrement d’un domaine déjà occupé, …).
  • 4xxx – erreur lors de l’exécution de la commande (p. ex. indisponibilité du registre de domaines, erreur de communication, etc.).
  • 5xxx – erreur interne ou état de notre système.
  • x0xx, x1xx – général.
  • x2xx – domaines.
  • x3xx – DNS.

Vous trouverez toujours les réponses concrètes renvoyées pour une commande donnée dans la documentation de cette commande.

Glossaire

  • Commande asynchrone: Commande exécutée pendant une durée plus longue ; elle ne renvoie qu’un message de réception, et vous suivez la suite du déroulement via les notifications.
  • API: Application Programming Interface. Interface qui vous permet, avec votre propre code, de récupérer des données ou de gérer une application tierce.
  • Data: Contenu de certaines commandes précisant des paramètres détaillés. La structure des données est définie par la commande concrète.
  • JSON : JavaScript Object Notation. Moyen moderne de communiquer avec l’API.
  • Code de retour : Numéro identifiant le type de réponse de WAPI à une commande.
  • Notification: Code JSON ou XML contenant des messages sur le déroulement d’une commande asynchrone.
  • Commande: Requête adressée à WAPI.
  • Commande synchrone: Commande exécutée pratiquement instantanément. Elle renvoie une réponse complète et n’utilise pas de notifications.
  • Notifications système: Type particulier de notifications sur les événements du système, que WAPI envoie automatiquement dans le format défini.
  • UTF-8: Unicode Transformation Format. Norme internationale répandue d’encodage de caractères prenant en charge un grand nombre d’écritures.
  • WAPI: Interface de gestion de certaines parties de l’administration client (compte de crédit, domaines, DNS).
  • XML: eXtended Markup Language. Ancien moyen de communiquer avec l’API.

Cet article vous a-t-il été utile ?

Votre avis nous aide à améliorer nos articles.

Votre message est transmis à l'équipe de rédaction de la documentation, qui n'y répond pas. Si vous avez besoin d’aide, contactez-nous via le formulaire de contact. N'indiquez ni mots de passe ni données personnelles.

Guides associés

WMS – Commande d'un nouveau service

Dans cet article, vous découvrirez ce que comprend le service WMS et comment le commander.

WebSite 1.0 – Activation du HTTPS

Dans cet article, vous découvrirez comment activer le HTTPS pour le service WebSite.

WMS – Bases de données

Dans cet article, vous découvrirez comment fonctionnent les bases de données du service WMS, comment en créer une…

Vous n'avez pas trouvé ce que vous cherchiez ?

Posez votre question aux autres clients sur le site communautaire Help.

Poser une question sur le site Help