Administración del clienteAdministración
Base de conocimientos›Otros servicios›Manual

WAPI – Manual

En esta páginaWEDOS APIActivación de WAPI en la administración de clientesComunicación y autenticaciónComandos básicosLista de códigos de retornoGlosario de términos

En este artículo aprenderá:

WEDOS API

WEDOS API, es decir, WAPI, sirve para controlar los servicios directamente desde su sistema de información. 

Para utilizar la interfaz es necesario usar la cuenta de crédito de WEDOS, de la cual el sistema descuenta los pagos de registros, renovaciones, transferencias y otras tarifas aplicables.

Actualmente WAPI permite gestionar:

Límites de WAPI

Como protección contra el uso indebido, WAPI aplica los siguientes límites:

  • Con una misma cuenta de usuario puede enviar un máximo de 1000 solicitudes por hora. Esto afecta a todas las solicitudes de todos los tipos; al alcanzar este límite, WAPI rechaza las solicitudes siguientes hasta que expire el límite de tiempo.
  • Una misma cuenta de usuario puede enviar un máximo de 100 solicitudes de disponibilidad de dominio por hora. Esto afecta a los comandos domain-check, domain-create y domain-transfer-check.
  • El envío repetido de solicitudes no válidas (fallo de autorización, acceso desde una dirección IP no permitida, entrada incorrecta, parámetros ausentes o incorrectos, comando desconocido, comandos que terminan con cualquier error o cualquier solicitud que exceda el resto de límites) provoca, al superar las 10 solicitudes no válidas, el bloqueo de la dirección IP durante 1 minuto por cada solicitud no válida. Con cada solicitud errónea adicional, el sistema prolonga el tiempo de bloqueo.

Operaciones síncronas y asíncronas

La mayoría de los comandos que se ejecutan a través de WAPI son síncronos: usted envía el comando y, por lo general, en unos segundos conoce el resultado. 

Algunas operaciones son asíncronas, es decir, la tramitación de dicho comando puede tardar mucho tiempo (incluso horas o días). Por ello, WAPI no devuelve el resultado final, sino solo la confirmación de que ha recibido el comando. El sistema le envía después la información sobre el progreso y el resultado final mediante notificaciones.

Registro

Encontrará el registro de solicitudes en la administración de clientes siguiendo estos pasos:

  1. Inicie sesión en la administración de clientes ⧉.
  2. En el menú superior seleccione My Account Customer.
  3. En el menú izquierdo seleccione WAPI queries.
Open WAPI Queries Overview

Activación de WAPI en la administración de clientes

Antes de empezar a usar WAPI, actívelo en la administración de clientes siguiendo estos pasos:

  1. Inicie sesión en la administración de clientes ⧉.
  2. En el menú superior seleccione My Account Customer.
  3. En el menú izquierdo seleccione WAPI interface.
  4. Configure las direcciones IP permitidas (IPv4 o IPv6, admite CIDR), el método de notificaciones, el protocolo preferido y la contraseña.
  5. Confirme la configuración con el botón Set.
Open WAPI Settings
Ejemplo de activación de WAPI
Ejemplo de activación de WAPI

Todos los ajustes introducidos durante la activación pueden modificarse más adelante de la misma forma. Si borra el contenido del campo Allowed IP addresses desactivará WAPI.

Comunicación y autenticación

La comunicación con la interfaz WAPI se realiza a través del protocolo HTTPS. Los datos se transmiten mediante el método POST en el parámetro request en formato XML o JSON. La forma básica del comando y de la respuesta es la misma para todos los comandos. La codificación de los datos es UTF-8.

Direcciones URL de la interfaz:

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

Estructura de la solicitud

La solicitud consta de los siguientes datos:

  • user: Nombre de usuario (correo electrónico) de su cuenta de cliente, parámetro obligatorio.
  • auth: Cadena de autorización, parámetro obligatorio. Se trata del hash sha1 de una cadena compuesta por el nombre de usuario, el hash sha1 de la contraseña de WAPI y la hora actual (00-23). La zona horaria es Europe/Prague (horario de invierno UTC+1 CET, horario de verano UTC+2 CEST). Encontrará un ejemplo concreto en el código siguiente.
  • command: El propio comando de WAPI. Parámetro obligatorio.
  • clTRID: ID de la solicitud, parámetro opcional. En este elemento puede insertar cualquier cadena como identificador, que WAPI devolverá en la respuesta.
  • data: Parte de datos del comando. Parámetro opcional.
  • test: Indicador de modo de prueba, parámetro opcional. Si inserta en el comando el elemento test con el valor 1, WAPI solo comprobará su comando, pero no realizará ningún cambio.

Al comunicarse con WAPI, indique la contraseña de WAPI. La contraseña de la cuenta de cliente no funciona.

La plantilla de solicitud (JSON) es, por tanto:

{
  "request":
  {
    "user": "su@login.tld",
    "auth": "cadena de autorización",
    "command": "nombre de la solicitud",
    "data":
    {
      datos de la solicitud
    }
    "clTRID": "identificador de la solicitud (opcional)",
    "test": "1 (si desea solo probar la solicitud, opcional)"
  }
}

Un ejemplo completo de uso en PHP (formato de datos JSON) puede ser:

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'su@login.tld'; 
$wpass = 'su contraseña de WAPI'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'nombre de la solicitud',
  'data' => ['array de datos de la solicitud'],
  'clTRID' => 'identificador de la solicitud (opcional)',
  'test' => '1 (si desea solo probar la solicitud)'
  ]
];

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

Estructura de la respuesta

La respuesta consta de los siguientes datos:

  • code: Valor de retorno del comando. Encontrará más información en el capítulo Códigos de retorno.
  • result: Descripción textual del código de retorno.
  • timestamp: Hora de ejecución del comando en formato UNIX.
  • clTRID: Identificador del comando por parte del cliente.
  • svTRID: Identificador del comando en el servidor.
  • command: Comando de WAPI.
  • data: Valores de retorno. Si el comando falla, no se devuelven datos.
  • test: Se inserta en la respuesta a los comandos que también contienen este indicador.

Un ejemplo de respuesta en formato JSON tiene, por ejemplo, este aspecto:

{
  "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 y 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.

Comando 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 o 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 o page_limit vrátí chybu 2101.
  • Comando dns-domains-list vrací total (jako řetězec), page y page_limit vždy. Když page_limit nezadáte nebo zadáte 0, použije 1000.

Comando 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": "su@login.tld",
    "auth": "cadena de autorización generada",
    "command": "domains-list",
    "clTRID": "código id propio",
    "data": {
      "status": "active",
      "search": "example",
      "page": 1,
      "page_limit": 2
    }
  }
}

Comando 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": "su@login.tld",
    "auth": "cadena de autorización generada",
    "command": "dns-rows-list",
    "clTRID": "código id propio",
    "data": {
      "domain": "example.cz",
      "rdtype": "A",
      "page": 1,
      "page_limit": 50
    }
  }
}

Notificación

Las operaciones asíncronas no pueden ejecutarse de inmediato. Puede seguir el progreso y el resultado de dichas operaciones mediante notificaciones. Las solicitudes síncronas no utilizan notificaciones.

Si WAPI no puede completar la operación de inmediato, devuelve en la respuesta Request pending (1001). Una vez completada la operación (en acciones más complejas, cada uno de los pasos), crea una notificación, que es equivalente a una respuesta clásica. Puede asignar la notificación a la solicitud correspondiente mediante los parámetros clTRID o svTRID.

Los datos de la notificación siempre están codificados en UTF-8.

Puede recibir las notificaciones de las siguientes maneras (según la configuración realizada durante la activación):

  • A través de la cola POLL.
  • Mediante el envío a la dirección de correo electrónico indicada.
  • A través del protocolo HTTP (o HTTPS) a la dirección URL que usted establezca, mediante el método POST en el parámetro request. Se considera entrega correcta una respuesta HTTP con el código de retorno 200. Si la entrega no se logra, nuestro sistema intentará entregarla de nuevo a intervalos de varios minutos.

Un ejemplo de notificación en formato JSON tiene, por ejemplo, este aspecto:

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

Notificaciones del sistema

Las notificaciones del sistema envían información sobre eventos relevantes; actualmente solo sobre la transferencia de un dominio a otro proveedor. Si tiene WAPI activo en su cuenta, el sistema enviará dicha información mediante una notificación, de forma similar a un comando asíncrono.

El protocolo en el que WAPI envía las notificaciones del sistema se configura según el capítulo Activación de WAPI en la administración de clientes. Esta opción funciona para las notificaciones enviadas por correo electrónico o a una dirección URL. En caso de descarga desde la cola POLL, la respuesta tiene la misma forma que un comando.

La estructura es la misma que en la notificación clásica, el comando (command) es siempre system-notify. En el nodo data encontrará información más detallada.

Comandos básicos

Entre los comandos básicos se encuentran ping, ping-async y los comandos para trabajar con la cola POLL poll-req y poll-ack.

ping

El comando ping sirve para comprobar el funcionamiento de WAPI, por ejemplo, los datos de acceso, la dirección IP o el código.

Los valores de retorno son:

  • 1000 – OK

Comando JSON:

{
  "request": {
    "user": "su@login.tld",
    "auth": "cadena de autorización generada",
    "command": "ping",
    "clTRID": "código id propio"
  }
}

Respuesta JSON:

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "hora UTC",
    "clTRID": "código id propio",
    "svTRID": "código id del servidor",
    "command": "ping"
  }
}

ping-async

El comando ping-async comprueba el funcionamiento de las notificaciones de WAPI.

Los valores de retorno son:

  • 1000 OK
  • 1001 Comando en espera

Comando JSON:

{
  "request": {
    "user": "su@login.tld",
    "auth": "cadena de autorización generada",
    "command": "ping",
    "clTRID": "código id propio"
  }
}

Respuesta JSON:

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "hora UTC",
    "clTRID": "código id propio",
    "svTRID": "código id del servidor",
    "command": "ping"
  }
}

Notificación JSON:

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "hora UTC",
    "clTRID": "código id propio",
    "svTRID": "código id del servidor",
    "command": "ping-async",
    "id": "id para la cola POLL",
    "data": {
      "round": "número de intento",
      "time": "hora",
      "done": 1
    }
  }
}

poll-req y poll-ack

Para obtener notificaciones de la cola POLL se combinan los comandos poll-req y poll-ack: 

  1. Con el comando poll-req descarga la notificación disponible más antigua.
  2. Con el comando poll-ack marca la notificación como recibida y, de ese modo, hace accesibles las más recientes hasta agotar la cola.

Los valores de retorno de poll-req son:

  • 1000 – notificación obtenida
  • 1003 – no hay ninguna notificación sin leer en la cola
  • 2150 – su cuenta no tiene configurada la descarga de notificaciones desde la cola POLL

Comando JSON poll-req:

{
  "request": {
    "user": "su@login.tld",
    "auth": "cadena de autorización generada",
    "command": "poll-req",
    "clTRID": "código id propio"
  }
}

Respuesta JSON a poll-req (notificación disponible):

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "hora UTC",
    "clTRID": "código id propio",
    "svTRID": "código id del servidor",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "hora UTC",
        "clTRID": "código id propio del comando encontrado",
        "svTRID": "código id del servidor para el comando encontrado",
        "command": "nombre del comando",
        "id": "id en la cola POLL"
      }
    }
  }
}

Respuesta JSON a poll-req (cola de notificaciones vacía):

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": “1286962852”,
    "clTRID": "código id propio",
    "svTRID": "código id del servidor",
    "command": "poll-req"
  }
}

Al comando poll-ack se le proporcionan los datos (parámetros):

  • id – ID de la notificación POLL actual

Los valores de retorno de poll-ack son:

  • 1002 – notificación marcada como recibida
  • 2151 – notificación no encontrada

Comando JSON poll-ack:

{
  "request": {
    "user": "su@login.tld",
    "auth": "cadena de autorización generada",
    "command": "poll-ack",
    "clTRID": "código id propio",
    "data": {
      "id": “ID de la notificación POLL recibida”
    }
  }
}

Respuesta JSON a poll-ack:

{
  "response": {
    "code": “1002”,
    "result": "Notification acquired",
    "timestamp": "hora UTC",
    "clTRID": "código id propio",
    "svTRID": "código id del servidor",
    "command": "poll-ack"
  }
}

Los códigos de retorno en las respuestas y notificaciones le ayudarán a identificar el progreso y los posibles errores de WAPI.

Clasificación básica de los códigos de retorno:

  • 1xxx – el comando se ha ejecutado correctamente.
  • 2xxx – comando incorrecto (por ejemplo, campos de entrada ausentes, o con formato o valor incorrectos).
  • 3xxx – error del objeto de destino: no se puede realizar la acción solicitada porque el objeto no se encuentra en el estado correcto (por ejemplo, al intentar registrar un dominio ya ocupado, …).
  • 4xxx – error al ejecutar el comando (p. ej., registro de dominios no disponible, error de comunicación, etc.).
  • 5xxx – error o estado interno de nuestro sistema.
  • x0xx, x1xx – general.
  • x2xx – dominios.
  • x3xx – DNS.

Encontrará siempre las respuestas concretas devueltas para cada comando en la documentación del comando.

Glosario de términos

  • Comando asíncrono: Comando que se ejecuta durante un tiempo prolongado y devuelve solo un mensaje de recepción; el resto del progreso lo sigue mediante notificaciones.
  • API: Application Programming Interface. Interfaz que le permite obtener datos o gestionar una aplicación de terceros mediante su propio código.
  • Data: Contenido de algunos comandos que especifica la configuración detallada. La estructura de los datos viene determinada por el comando concreto.
  • JSON: JavaScript Object Notation. Forma moderna de comunicarse con una API.
  • Código de retorno: Número que identifica el tipo de respuesta de WAPI a un comando.
  • Notificación: Código JSON o XML con mensajes sobre el progreso de un comando asíncrono.
  • Comando: Solicitud a WAPI.
  • Comando síncrono: Comando que se ejecuta prácticamente de inmediato. Devuelve una respuesta completa y no utiliza notificaciones.
  • Notificaciones del sistema: Tipo especial de notificaciones sobre eventos del sistema; WAPI las envía automáticamente en el formato configurado.
  • UTF-8: Unicode Transformation Format. Estándar internacional muy extendido de codificación de caracteres que admite una gran cantidad de escrituras.
  • WAPI: Interfaz para la gestión de algunas partes de la administración de clientes (cuenta de crédito, dominios, DNS).
  • XML: eXtended Markup Language. Forma más antigua de comunicarse con una API.

¿Le ha resultado útil este artículo?

Su valoración nos ayuda a mejorar nuestros artículos.

Su mensaje llega al equipo de documentación, que no responde a los mensajes. Si necesita ayuda, contacte con nosotros mediante el formulario de contacto. No incluya contraseñas ni datos personales.

Artículos relacionados

WMS – Pedido de un nuevo servicio

En este artículo descubrirá qué incluye el servicio WMS y cómo contratarlo.

WebSite 1.0 – Activación de HTTPS

En este artículo encontrará cómo activar HTTPS en el servicio WebSite.

WMS – Bases de datos

En este artículo descubrirá cómo funcionan las bases de datos del servicio WMS, cómo crear una base de…

¿No ha encontrado lo que buscaba?

Pregunte a otros clientes en el sitio de la comunidad Help.

Preguntar en el sitio Help